okf 1.4.0 → 1.6.0

data/lib/okf/cli.rb

@@ -3,7 +3,7 @@
 require "optparse"
 
 module OKF
-  # Command-line front end: `okf graph|validate|lint|loose|index|catalog|files|tags|types|stats|server <dir>`.
+  # Command-line front end: `okf graph|validate|lint|loose|search|index|catalog|files|tags|types|stats|server <dir>`.
   # This is the
   # only layer that parses argv, prints, writes files, and decides exit codes — the
   # lib classes below it just return data. Streams are injectable for testing.
@@ -47,6 +47,7 @@ module OKF
       when "validate" then validate(argv)
       when "lint" then lint(argv)
       when "loose" then loose(argv)
+      when "search" then search(argv)
       when "index" then index(argv)
       when "catalog" then catalog(argv)
       when "files" then files(argv)
@@ -54,6 +55,7 @@ module OKF
       when "types" then types(argv)
       when "stats" then stats(argv)
       when "server" then server(argv)
+      when "render" then render(argv)
       when "skill" then skill(argv)
       when "version", "--version", "-v" then @out.puts(OKF::VERSION); 0
       when "help", "--help", "-h" then usage(@out); 0
@@ -131,6 +133,65 @@ module OKF
       0
     end
 
+    # Deterministic text retrieval — the browser page's search brought to the CLI
+    # and extended to bodies. Terms after the directory are ANDed case-insensitive
+    # substrings (Ruby regexps with --regexp); rows rank by where they hit (title >
+    # id > tags > type/description > body) and carry one bounded context snippet,
+    # so "which concept covers X?" costs a few rows, not a body read. Advisory
+    # read: exit 0 even with no matches. Deliberately not fuzzy — the consuming
+    # agent is the fuzzy layer.
+    def search(argv)
+      options = { json: false, regexp: false }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf search <bundle-dir> <term> [term ...] [--regexp] [--in FIELDS] [--type T] [--area A] [--tag T] [--json]"
+        json_flags(o, options, "emit the matches as JSON")
+        projection_flags(o, options)
+        o.on("-e", "--regexp", "treat each term as a Ruby regular expression (case-insensitive)") { options[:regexp] = true }
+        o.on("--in LIST", Array, "search only these fields (#{OKF::Bundle::Search::FIELDS.join(", ")})") { |v| options[:in] = v.map(&:downcase) }
+        filter_flags(o, options, :type, :area, :tag)
+      end
+      dir = positional_dir(parser, argv) or return 2
+      terms = argv
+      if terms.empty?
+        @err.puts parser.banner
+        return 2
+      end
+
+      unknown = Array(options[:in]) - OKF::Bundle::Search::FIELDS
+      return usage_error("unknown field(s): #{unknown.join(", ")} (searchable: #{OKF::Bundle::Search::FIELDS.join(", ")})") unless unknown.empty?
+
+      folder = OKF::Bundle::Folder.load(dir)
+      report_skipped(folder)
+      rows = OKF::Bundle::Search.call(folder.bundle, terms, fields: options[:in], regexp: options[:regexp])
+      keep = filter_ids(folder, options)
+      rows = rows.select { |row| keep.include?(row[:id]) } unless keep.nil?
+      return print_search_json(dir, terms, rows, options) if options[:json]
+
+      print_search(dir, terms, rows, folder.bundle.concepts.size)
+      0
+    rescue RegexpError => e
+      usage_error("invalid pattern: #{e.message}")
+    end
+
+    def print_search(dir, terms, rows, total)
+      @out.puts "Search — #{dir} · #{terms.join(" ")} (#{counted(rows.size, total, "concepts")})"
+      if rows.empty?
+        @out.puts "  no matches — fewer or broader terms, or scan `okf tags #{dir}` for the vocabulary"
+        return
+      end
+
+      width = rows.map { |row| row[:id].length }.max
+      rows.each do |row|
+        @out.puts
+        @out.puts "  #{row[:id].ljust(width)}  #{row[:title]}  ·  #{row[:type]}  ·  #{row[:matched].join("+")}"
+        @out.puts "    #{truncate(row[:snippet], 100)}" unless row[:snippet].empty?
+      end
+    end
+
+    def print_search_json(dir, terms, rows, options)
+      emit_list_json(dir, "matches", rows.map { |row| stringify(row) }, options, "query" => terms)
+    end
+
     def server(argv)
       require "okf/server/app"
 
@@ -159,6 +220,34 @@ module OKF
       @runner.call(app, options[:bind], options[:port])
     end
 
+    # The static counterpart to `server`: bake the whole bundle into one
+    # self-contained HTML file (bodies, catalog, index, logs baked in, no server
+    # needed — e.g. hosting on GitHub Pages). Prints to stdout unless -o is given.
+    def render(argv)
+      require "okf/server/app"
+
+      options = { output: nil, title: nil, link: nil, layout: "cose" }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf render <bundle-dir> [-o FILE] [--layout NAME] [-t title] [-l url]"
+        o.on("-o", "--output FILE", "write to FILE instead of stdout") { |v| options[:output] = v }
+        o.on("-t", "--title TITLE", "graph title (default: parent/bundle dir name)") { |v| options[:title] = v }
+        o.on("-l", "--link URL", "source URL shown in the header") { |v| options[:link] = v }
+        o.on("--layout NAME", OKF::Server::Graph::LAYOUTS, "initial layout (#{OKF::Server::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+      end
+      dir = positional_dir(parser, argv) or return 2
+
+      folder = OKF::Bundle::Folder.load(dir)
+      report_skipped(folder)
+      html = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link], layout: options[:layout]).render_static
+      if options[:output]
+        File.write(options[:output], html)
+        @out.puts "wrote #{folder.graph(minimal: true).nodes.size} concepts to #{options[:output]}"
+      else
+        @out.print html
+      end
+      0
+    end
+
     def graph(argv)
       options = { json: false, minimal: false, body: true }
       parser = OptionParser.new do |o|
@@ -801,13 +890,16 @@ module OKF
     # 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).
-    def emit_list_json(dir, key, items, options)
+    def emit_list_json(dir, key, items, options, extra = {})
       return usage_error("--fields and --except are mutually exclusive") if options[:fields] && options[:except]
 
       unknown = unknown_fields(items, options)
       return usage_error("unknown field(s): #{unknown.join(", ")} (available: #{available_fields(items).join(", ")})") unless unknown.empty?
 
-      emit_json("bundle" => dir, "count" => items.size, key => project(items, options))
+      payload = { "bundle" => dir }.merge(extra)
+      payload["count"] = items.size
+      payload[key] = project(items, options)
+      emit_json(payload)
       0
     end
 
@@ -884,11 +976,13 @@ module OKF
 
           skill     <dest> [--here] [--force]               install the companion agent skill
           server    <dir> [-p PORT] [--bind ADDR] [...]     serve an interactive HTML graph
+          render    <dir> [-o FILE] [--layout NAME] [...]   write a static, self-contained HTML graph
 
           lint      <dir> [--json] [--fail-on warn] [...]   report curation-quality issues
           loose     <dir> [--json]                          list files with no graph links, by folder
           validate  <dir> [--json]                          check OKF v0.1 conformance
 
+          search    <dir> <term…> [-e] [--in FIELDS] [...]  find concepts by text or regexp, ranked
           index     <dir> [--json] [--area A] [--no-body]   the index map: dirs, their listings and rollups
           stats     <dir> [--json]                          bundle rollups (concepts, types, areas, links, tags)
           types     <dir> [--json] [filters]                list types with their concepts, by count
@@ -903,7 +997,7 @@ module OKF
         tags --by DIM regroups the tags per concept dimension — type or area — with
         within-group counts, the view for curating a tag vocabulary.
         --json emits compact JSON (the machine substrate); add --pretty to indent it.
-        --fields / --except project the JSON to the properties you want (index/catalog/files).
+        --fields / --except project the JSON to the properties you want (search/index/catalog/files).
 
         okf --version
       USAGE

data/lib/okf/server/app.rb

@@ -24,6 +24,12 @@ module OKF
     #                       tags, timestamp, status, area, dir, links_*} ] } (JSON)
     #   GET /tags           the tag index  { tag  => [id, …] } (JSON)
     #   GET /types          the type index { type => [id, …] } (JSON)
+    #   GET /index          the §6 progressive-disclosure map for the Index panel:
+    #                       { directories: [ …okf-index rows… ] } (JSON, from the
+    #                       boot snapshot — authored maps are structure)
+    #   GET /log            the §7 history for the Log panel: { logs: [ {path,
+    #                       dir, content} ] } (JSON; content read live from disk,
+    #                       like a body — the log is the file that changes most)
     class App
       def initialize(folder, title: nil, link: nil, layout: "cose")
         @folder = folder
@@ -43,10 +49,19 @@ module OKF
         when "/catalog" then respond_json(catalog)
         when "/tags" then respond_json(graph.tag_index)
         when "/types" then respond_json(graph.type_index)
+        when "/index" then respond_json(directory_index)
+        when "/log" then respond_json(logs)
         else not_found
         end
       end
 
+      # The same interactive page, but with the whole bundle baked in — bodies,
+      # catalog, index and logs — so it needs no server. This is what `okf render`
+      # writes: the fetch getters resolve from the embedded payload, not from here.
+      def render_static
+        Graph.new(graph, title: @title || @folder.name, link: @link, layout: @layout, embed: embed_payload).render
+      end
+
       private
 
       # The minimal graph snapshot taken at boot — drives the page and the indexes.
@@ -63,10 +78,54 @@ module OKF
         { concepts: @folder.catalog }
       end
 
+      # The §6 map the Index panel renders — the same rows `okf index` prints,
+      # built by the pure OKF::Bundle#directory_index over the boot snapshot
+      # (authored index bodies are structure, read at load like the graph).
+      def directory_index
+        { directories: @folder.directory_index }
+      end
+
+      # Every log.md with its content, root scope first. Content is read live
+      # from disk so a just-appended entry shows without a restart; paths come
+      # from the loaded bundle, never from the request.
+      def logs
+        entries = @folder.bundle.log_files.sort_by { |path| [ path == "log.md" ? 0 : 1, path ] }
+        { logs: entries.map { |path| { path: path, dir: File.dirname(path), content: log_content(path) } } }
+      end
+
+      def log_content(path)
+        File.read(File.join(@folder.root, path), encoding: "UTF-8")
+      rescue SystemCallError
+        @folder.bundle.reserved_content(path)
+      end
+
       def page
         @page ||= Graph.new(graph, title: @title || @folder.name, link: @link, layout: @layout).render
       end
 
+      # Everything the on-demand endpoints would serve, baked for render mode. The
+      # arrays match what each client getter extracts from the JSON envelope; the
+      # per-concept maps mirror /node (raw, unstripped body) and /node/meta (the
+      # same escaped fragment). Read from the in-memory bundle — no live disk read,
+      # since a static file is a snapshot, not a window on edits.
+      def embed_payload
+        {
+          catalog: @folder.catalog,
+          index: @folder.directory_index,
+          logs: logs[:logs],
+          bodies: bodies,
+          meta: meta
+        }
+      end
+
+      def bodies
+        @folder.bundle.concepts.each_with_object({}) { |concept, map| map[concept.id] = concept.body.to_s }
+      end
+
+      def meta
+        @folder.bundle.concepts.each_with_object({}) { |concept, map| map[concept.id] = description_fragment(concept) }
+      end
+
       def node_body(id)
         concept = concept_for(id)
         return not_found if concept.nil?