okf 1.9.0 → 1.11.0

data/lib/okf/cli/server.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Boot the graph server. One verb covers three intentions and the argument
+    # count is the whole interface: one dir serves it at /, several serve them
+    # behind a hub, none serves the registry. Passing dirs never registers them.
+    class Server < Command
+      def self.id
+        :server
+      end
+
+      def self.group
+        :act
+      end
+
+      def self.help_rows
+        [
+          [ "server    [DIR|@slug…] [-p PORT] [--bind ADDR] [...]", "serve one bundle, or many behind a hub" ]
+        ]
+      end
+
+      def call(argv)
+        require "okf/server/app"
+        require "rack/deflater"
+
+        options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose", read_only: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf server [DIR|@slug…] [-p PORT] [--bind ADDR] [--layout NAME] [-t title] [-l url]"
+          o.on("-p", "--port PORT", Integer, "port to serve on (default #{options[:port]})") { |v| options[:port] = v }
+          o.on("--bind ADDR", "address to bind (default #{options[:bind]})") { |v| options[:bind] = v }
+          o.on("-t", "--title TITLE", "graph title, single bundle only (default: parent/bundle dir name)") { |v| options[:title] = v }
+          o.on("-l", "--link URL", "source URL shown in the header, single bundle only") { |v| options[:link] = v }
+          o.on("--layout NAME", OKF::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+          o.on("--read-only", "serve the bundles list without its registry controls") { options[:read_only] = true }
+          help_flag(o)
+        end
+        dirs = positional_dirs(parser, argv) or return 2
+
+        # A flag that will have no effect in this mode gets a note, not silence.
+        @err.puts "note: --title/--link apply to a single-bundle server; ignored" if dirs.size != 1 && (options[:title] || options[:link])
+
+        # One dir keeps the historical single-bundle server at `/`; zero (the
+        # persistent registry) or many (ephemeral) fan out behind a hub.
+        if dirs.size == 1
+          folder = OKF::Bundle::Folder.load(dirs.first)
+          report_skipped(folder)
+          run_server(folder, options)
+        else
+          run_hub(dirs, options)
+        end
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      private
+
+      # Build the single-bundle Rack app and hand it to the runner (WEBrick by
+      # default, injected so tests drive this without a socket).
+      def run_server(folder, options)
+        # search_endpoint is named here rather than defaulted in App: the page
+        # resolves it against the URL the reader is on, and this is the layer that
+        # knows the app is mounted at the root. An embedding host mounting App
+        # elsewhere passes its own.
+        app = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link],
+          layout: options[:layout], search_endpoint: "search")
+        # minimal: the banner wants a count, not bodies — and Folder#graph is not
+        # memoized, so a full build here parses every concept a second time (the
+        # App builds its own) purely to print one number.
+        app.warm_search
+        count = folder.graph(minimal: true).nodes.size
+        @out.puts "serving #{count} #{pluralize(count, "concept")} at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
+        serve(app, options)
+      end
+
+      # Build the multi-bundle hub and hand it to the runner. With dirs it serves
+      # those ephemerally; with none it serves the persistent registry. Either way
+      # the first bundle is the one `/` opens — for the registry that is its own
+      # order, and a first entry whose directory has vanished drops out here, so
+      # `/` lands on the next one that is actually there.
+      def run_hub(dirs, options)
+        require "okf/server/hub"
+        require "okf/registry"
+        reg = nil
+        if dirs.empty?
+          # A malformed registry raises OKF::Error, which `server` rescues into a
+          # usage error — no guarded load needed on this path.
+          reg = OKF::Registry.load
+          # The hub's own loader, so the set it rebuilds after a browser-side
+          # write is built exactly the way this one was.
+          bundles = OKF::Server::Hub.bundles_for(reg) { |entry| skip_registered(entry) }
+          bundles.each { |bundle| report_skipped(bundle.folder) }
+        else
+          bundles = ephemeral_bundles(dirs)
+        end
+        # The hub keeps the registry so its /b/ manager can report on entries it
+        # could not host — a folder deleted out from under one is the question
+        # "where did my bundle go?", and only the registry can answer it.
+        hub = OKF::Server::Hub.new(bundles, layout: options[:layout], registry: reg, writable: writable?(options))
+        hub.warm_search
+        concepts = bundles.inject(0) { |sum, bundle| sum + bundle.folder.graph(minimal: true).nodes.size }
+        @out.puts "serving #{bundles.size} #{pluralize(bundles.size,
+          "bundle")}, #{concepts} #{pluralize(concepts, "concept")} at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
+        print_mounts(hub)
+        serve(hub, options)
+      end
+
+      # The one boot seam every served app passes through, so a hub gzips exactly
+      # like a single bundle — the wrap belongs to booting a server, not to either
+      # mode, and a mode added later gets it for free. Deliberately not inside the
+      # runner: an embedding app mounting OKF::Server::App brings its own middleware.
+      def serve(app, options)
+        # gzip responses when the client accepts it — transparent, no new dependency
+        @runner.call(Rack::Deflater.new(app), options[:bind], options[:port])
+      end
+
+      # The mount table — which dir landed on which /b/<slug>/ and where `/` goes.
+      # Mirrors the Hub's own default resolution (explicit slug, else first).
+      # Ask the hub which bundle it chose rather than re-deriving the
+      # explicit-else-first rule, and mount at its own prefix: two copies of a
+      # rule is two answers waiting to disagree.
+      def print_mounts(hub)
+        hub.bundles.each do |bundle|
+          marker = bundle.equal?(hub.default) ? "*" : " "
+          @out.puts "  #{marker} #{OKF::Server::Hub::MOUNT}/#{bundle.slug}/  #{bundle.title}"
+        end
+      end
+
+      # Load the given directories as unregistered bundles, slugged by basename and
+      # deduped within the run. The same directory listed twice mounts once — two
+      # windows on one bundle would just burn a slug on a URL that vanishes next run.
+      def ephemeral_bundles(dirs)
+        roots = []
+        dirs.each do |dir|
+          root = File.expand_path(dir)
+          roots << root unless roots.include?(root)
+        end
+
+        # A registered slug owns its mount outright: reserve every ref's slug
+        # before any basename is deduped. Otherwise argv order decides, and
+        # `server ./two @two` mounts the *unregistered* ./two at /b/two/ while
+        # pushing the ref — the bundle whose slug that is — to /b/two-2/, so a
+        # bookmark from a bundle-less run silently opens the wrong graph.
+        taken = roots.map { |root| ref_slugs[root] }.compact
+        roots.each_with_object([]) do |root, bundles|
+          folder = OKF::Bundle::Folder.load(root)
+          report_skipped(folder)
+          slug = ref_slugs[root]
+          unless slug
+            slug = OKF::Registry.dedupe(File.basename(root), taken)
+            taken << slug
+          end
+          bundles << OKF::Server::Hub::Bundle.new(slug, folder, folder.name)
+        end
+      end
+
+      # May the browser change the registry? On a loopback bind, yes: the server
+      # is reachable only from this machine, and the audience this was built for
+      # should not need a flag to use the page they were pointed at. Anywhere
+      # else, no — and there is no flag that says otherwise, because the registry
+      # is a per-user file and the machine that owns it is the machine that
+      # manages it. `--bind 0.0.0.0` is how a personal tool becomes a public one,
+      # and 0.0.0.0 is *not* loopback: it is every interface, which is the exact
+      # case this guards.
+      #
+      # So the only flag is the way *out*. It was `--allow-manage`, an opt-in
+      # that read as the on switch and was not one — the loopback default had
+      # already turned management on, and the flag only widened it to a bind
+      # nobody should widen it to. Naming the exception instead means the flag
+      # cannot be misread as permission: `--read-only` is the word the hub's own
+      # refusal already uses, and this server never writes a reader's markdown
+      # anyway, so in context it can only mean the registry.
+      def writable?(options)
+        !options[:read_only] && loopback?(options[:bind])
+      end
+
+      def loopback?(bind)
+        address = bind.to_s
+        address == "localhost" || address == "::1" || address.start_with?("127.")
+      end
+    end
+
+    register(Server)
+  end
+end

data/lib/okf/cli/skill.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Install this gem's companion agent skill into a destination directory. The
+    # destination is required (no magic default) so the user always decides where
+    # their agent picks the skill up. By default the skill lands in a skills/okf/
+    # folder under it — point at a project or skills dir (.claude, .agents/skills)
+    # and it settles in its own folder, never loose among the others — so the
+    # resolved path is echoed back. --here installs straight into <dest-dir>.
+    class Skill < Command
+      def self.id
+        :skill
+      end
+
+      def self.group
+        :act
+      end
+
+      def self.help_rows
+        [
+          [ "skill     <dest> [--here] [--force]", "install the companion agent skill" ]
+        ]
+      end
+
+      def call(argv)
+        options = { force: false, nest: true }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf skill <dest-dir> [--here] [--force]"
+          o.on("--here", "install straight into <dest-dir>, wherever it is (no skills/okf nesting)") { options[:nest] = false }
+          o.on("--force", "overwrite a non-empty destination") { options[:force] = true }
+          help_flag(o)
+        end
+        # Through the shared pair like every other verb that takes one positional:
+        # `positional` for the value, `no_extras?` for what must not follow it.
+        # Hand-rolling the shift is how this one came to accept a second
+        # destination, install into the first and exit 0 — the silent-wrong-answer
+        # shape the <dir> verbs are guarded against, on the one verb whose
+        # positional is not a <dir>.
+        dest = positional(parser, argv) or return 2
+        no_extras?(argv) or return 2
+
+        skill = OKF::Skill.new(dest, force: options[:force], nest: options[:nest])
+        files = skill.install
+        @out.puts "installed the okf skill (#{files.size} files) -> #{skill.dest}"
+        files.each { |f| @out.puts "  #{f}" }
+        @out.puts "your agent picks it up from #{skill.dest} (needs the `okf` CLI, which you already have)."
+        0
+      rescue OKF::Skill::Error => e
+        @err.puts "error: #{e.message}"
+        2
+      end
+    end
+
+    register(Skill)
+  end
+end

data/lib/okf/cli/stats.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Bundle rollups — concepts, dirs, types, links, tags — in one screen.
+    class Stats < Command
+      def self.id
+        :stats
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "stats     <dir|@slug> [--json]", "bundle rollups (concepts, dirs, types, links, tags)" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf stats <dir|@slug> [--json]"
+          json_flags(o, options, "emit the stats as JSON")
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        stats = bundle_stats(folder)
+        options[:json] ? print_stats_json(dir, stats) : print_stats(dir, stats)
+        0
+      end
+
+      private
+
+      # Bundle-level rollups derived from the catalog and the graph indexes.
+      def bundle_stats(folder)
+        graph = folder.graph(minimal: true)
+        entries = folder.catalog
+        by_type = graph.type_index.transform_values(&:size).sort_by { |_, n| -n }.to_h
+        by_area = entries.group_by { |entry| entry[:area] }.transform_values(&:size).sort_by { |_, n| -n }.to_h
+        by_dir = directory_counts(folder)
+        {
+          concepts: entries.size,
+          dirs: by_dir.size,
+          areas: by_area.size,
+          types: by_type.size,
+          cross_links: graph.edges.size,
+          tags: graph.tag_index.size,
+          by_type: by_type,
+          by_dir: by_dir,
+          by_area: by_area
+        }
+      end
+
+      # Every directory the bundle has, with the concepts that live *directly* in
+      # it. Read off Bundle#directory_index — the same map `okf dirs` lists and
+      # `--dir` is answered against — rather than off the catalog, which knows
+      # only the directories that happen to hold a concept. Grouping the catalog
+      # made `stats` and `dirs` report different totals for one bundle, and left
+      # an addressable directory out of by_dir entirely: `--dir deeply` answers,
+      # but nothing in `stats` said `deeply` was there to ask about.
+      #
+      # A directory holding nothing directly therefore appears at 0. That is the
+      # honest reading — it is the same zero `okf dirs` prints in its Concepts
+      # column — and it keeps `dirs` equal to `by_dir.size`. Ties break by path so
+      # the order is total, not whatever the sort happened to leave.
+      def directory_counts(folder)
+        folder.directory_index
+              .map { |entry| [ entry[:dir], entry[:count] ] }
+              .sort_by { |dir, count| [ -count, dir ] }.to_h
+      end
+
+      def print_stats(dir, stats)
+        @out.puts "Stats — #{bundle_label(dir)}"
+        @out.puts
+        @out.puts "  concepts       #{stats[:concepts]}"
+        @out.puts "  dirs           #{stats[:dirs]}"
+        @out.puts "  concept types  #{stats[:types]}"
+        @out.puts "  cross-links    #{stats[:cross_links]}"
+        @out.puts "  distinct tags  #{stats[:tags]}"
+        print_stat_breakdown("By type", stats[:by_type])
+        # One grouping word in the human view: `by_area` stays in --json for the
+        # deprecation window, but a screen that printed both would be teaching the
+        # vocabulary the rest of this change is retiring.
+        print_stat_breakdown("By dir", stats[:by_dir]) { |label| dir_label(label) }
+      end
+
+      def print_stat_breakdown(title, counts)
+        return if counts.empty?
+
+        labels = counts.keys.map { |key| block_given? ? yield(key) : key }
+        width = labels.map(&:length).max
+        @out.puts
+        @out.puts "  #{title}"
+        counts.each_with_index { |(_, count), i| @out.puts "    #{labels[i].ljust(width)}  #{count}" }
+      end
+
+      def print_stats_json(dir, stats)
+        emit_json(bundle_head(dir).merge(
+          "concepts" => stats[:concepts], "dirs" => stats[:dirs], "areas" => stats[:areas],
+          "concept_types" => stats[:types], "cross_links" => stats[:cross_links], "distinct_tags" => stats[:tags],
+          "by_type" => stats[:by_type], "by_dir" => stats[:by_dir], "by_area" => stats[:by_area]
+        ))
+      end
+    end
+
+    register(Stats)
+  end
+end

data/lib/okf/cli/tags.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The tag index: which tags exist, how often, and on what. --by regroups them
+    # per concept dimension, which is the view for curating a vocabulary rather
+    # than reading one.
+    class Tags < Command
+      def self.id
+        :tags
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "tags      <dir|@slug> [--json] [--by DIM] [filters]", "list tags with their concepts, by count" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false, by: nil }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf tags <dir|@slug> [--by type|dir] [--type T] [--dir D] [--json]"
+          json_flags(o, options, "emit the tag index as JSON")
+          o.on("--by DIM", %w[type dir area], "group the tags by a concept dimension (type | dir)") do |v|
+            options[:by] = v.to_sym
+            deprecated("--by area", "--by dir") if options[:by] == :area
+          end
+          filter_flags(o, options, :type, :area)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        return grouped_tags(dir, options) if options[:by]
+
+        print_inverted_index(dir, "Tags", :tag, "tags", options)
+      end
+
+      private
+
+      # `tags --by type|dir`: the tag index re-cut per concept type or directory,
+      # with within-group counts — the curation view. A tag confined to one
+      # group at count 1 is scattered; one recurring across groups is connective.
+      # The --type/--dir filters narrow the concepts first, then the grouping cuts.
+      def grouped_tags(dir, options)
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        graph = folder.graph(minimal: true)
+        titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
+        groups = tag_groups(graph.tag_index, folder, options)
+        options[:json] ? print_grouped_tags_json(dir, options[:by], groups) : print_grouped_tags(dir, options[:by], groups, titles)
+        0
+      end
+
+      # [ [ group, rows ], … ] — groups sorted by name, rows shaped like index_rows'
+      # plus each tag's total across the narrowed set. A tag carried in several
+      # groups appears in each, counted per group; count/total per row is what
+      # makes a tag's spread — local to one group, or cutting across several —
+      # readable without cross-referencing the groups by hand.
+      def tag_groups(tag_index, folder, options)
+        by_id = filter_entries(folder.catalog, options).map { |entry| [ entry[:id], entry ] }.to_h
+        groups = {}
+        totals = Hash.new(0)
+        tag_index.each do |tag, ids|
+          ids.each do |id|
+            entry = by_id[id]
+            next if entry.nil?
+
+            key = group_key(entry, options[:by])
+            ((groups[key] ||= {})[tag] ||= []) << id
+            totals[tag] += 1
+          end
+        end
+        groups.map do |key, tags|
+          rows = tags.map { |tag, ids| { tag: tag, count: ids.length, total: totals[tag], concepts: ids } }
+                     .sort_by { |row| [ -row[:count], row[:tag] ] }
+          [ key, rows ]
+        end.sort_by(&:first)
+      end
+
+      # A catalog entry's type for display — "Untyped" when blank, matching the graph.
+      def entry_type(entry)
+        OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
+      end
+
+      # The group a concept falls in, in its *stored* spelling — `.` for the root
+      # under --by dir, never "(root)". The human label is applied at print time,
+      # so the JSON and the table cannot disagree about which one is the data.
+      def group_key(entry, dim)
+        case dim
+        when :type then entry_type(entry)
+        when :dir then entry[:dir]
+        else entry[:area]
+        end
+      end
+
+      # `.` prints "(root)" bare; every other dir carries the trailing slash that
+      # says it is one. The deprecated --by area already stores "(root)" itself.
+      def group_label(key, dim)
+        return key if dim == :type
+
+        dir_label(key, slash: true)
+      end
+
+      def print_grouped_tags(dir, dim, groups, titles)
+        @out.puts "Tags — #{bundle_label(dir)} (#{distinct_tags(groups)} distinct, by #{dim})"
+        groups.each do |key, rows|
+          label = group_label(key, dim)
+          @out.puts
+          @out.puts "  #{label} (#{rows.size} #{pluralize(rows.size, "tag")})"
+          width = rows.map { |row| row[:tag].length }.max || 0
+          cwidth = [ 3, *rows.map { |row| count_cell(row).length } ].max
+          rows.each do |row|
+            names = row[:concepts].map { |id| titles[id] || id }.join(", ")
+            @out.puts "    #{row[:tag].ljust(width)}  #{count_cell(row).rjust(cwidth)}   #{truncate(names, 76)}"
+          end
+        end
+      end
+
+      # "2/3" when the tag spreads beyond this group, the plain count when it is
+      # local — so equality (locality 1.0) reads by absence.
+      def count_cell(row)
+        row[:count] == row[:total] ? row[:count].to_s : "#{row[:count]}/#{row[:total]}"
+      end
+
+      def print_grouped_tags_json(dir, dim, groups)
+        groups_json = groups.map do |key, rows|
+          rows_json = rows.map { |row| { "tag" => row[:tag], "count" => row[:count], "total" => row[:total], "concepts" => row[:concepts] } }
+          { dim.to_s => key, "count" => rows.size, "tags" => rows_json }
+        end
+        emit_json(bundle_head(dir).merge("count" => distinct_tags(groups), "by" => dim.to_s, "groups" => groups_json))
+      end
+
+      def distinct_tags(groups)
+        groups.flat_map { |_, rows| rows.map { |row| row[:tag] } }.uniq.size
+      end
+    end
+
+    register(Tags)
+  end
+end

data/lib/okf/cli/types.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The type index: which types exist, how often, and on what.
+    class Types < Command
+      def self.id
+        :types
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "types     <dir|@slug> [--json] [filters]", "list types with their concepts, by count" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf types <dir|@slug> [--dir D] [--tag T] [--json]"
+          json_flags(o, options, "emit the type index as JSON")
+          filter_flags(o, options, :area, :tag)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        print_inverted_index(dir, "Types", :type, "types", options)
+      end
+    end
+
+    register(Types)
+  end
+end

data/lib/okf/cli/validate.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The §9 conformance judge: is this legal OKF? Binary and tolerant — it is
+    # forbidden from failing a bundle over a broken link or a missing optional
+    # field, which is lint's job. Exit 1 when non-conformant.
+    class Validate < Command
+      def self.id
+        :validate
+      end
+
+      def self.group
+        :judge
+      end
+
+      def self.help_rows
+        [
+          [ "validate  <dir|@slug> [--json]", "check OKF v0.1 conformance" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf validate <dir|@slug> [--json]"
+          json_flags(o, options, "emit a JSON report")
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        result = OKF::Bundle::Folder.load(dir).validate
+        options[:json] ? print_validation_json(dir, result) : print_validation(dir, result)
+        result.valid? ? 0 : 1
+      end
+
+      private
+
+      def print_validation(dir, result)
+        counts = result.counts
+        @out.puts "OKF v0.1 conformance — #{bundle_label(dir)}"
+        @out.puts "  concepts: #{counts[:concepts]}   index.md: #{counts[:indexes]}   log.md: #{counts[:logs]}"
+        result.errors.each { |e| @out.puts "  #{paint("✗ ERROR", 31)}  #{e[:path]}: #{e[:message]}" }
+        result.warnings.each { |w| @out.puts "  #{paint("! warn", 33)}  #{w[:path]}: #{w[:message]}" }
+        if result.valid? && result.warnings.empty?
+          @out.puts "  #{paint("✓ conformant — no issues", 32)}"
+        elsif result.valid?
+          @out.puts "  #{paint("✓ conformant", 32)} (#{result.warnings.size} warning(s))"
+        else
+          @out.puts "  #{paint("✗ non-conformant", 31)} (#{result.errors.size} error(s))"
+        end
+      end
+
+      def print_validation_json(dir, result)
+        emit_json(bundle_head(dir).merge(
+          "conformant" => result.valid?,
+          "counts" => result.counts,
+          "errors" => result.errors,
+          "warnings" => result.warnings
+        ))
+      end
+    end
+
+    register(Validate)
+  end
+end