okf 1.8.0 → 1.10.0

data/lib/okf/{server → render}/graph.rb

@@ -3,10 +3,14 @@
 require "rack/utils"
 
 module OKF
-  module Server
-    # Renders an OKF::Bundle::Graph as the interactive graph page served by
-    # OKF::Server::App. The markup lives in graph/template.html.erb; #render
-    # returns the HTML string.
+  # The view layer: turns a bundle into the interactive graph page. Pairs with the
+  # pure OKF::Bundle::Graph (the data model) — Bundle builds the graph, Render
+  # draws it. A shell (reads the template, escapes with rack/utils), but knows
+  # nothing about HTTP: OKF::Server::App serves what this produces, and `okf
+  # render` writes it to a file, from the one class.
+  module Render
+    # Renders an OKF::Bundle::Graph as the interactive graph page. The markup lives
+    # in graph/template.html.erb; #render returns the HTML string.
     #
     # The page boots from a *minimal* payload — nodes carry only id + title, plus
     # compact TYPES/TAGS inverted indexes for colouring and filtering. It has two
@@ -16,9 +20,9 @@ module OKF
     #     metadata, catalog, index and log are pulled from OKF::Server::App on
     #     demand via fetch, so the initial payload stays small and bodies read
     #     live from disk (edits show without a restart). Nothing extra embedded.
-    #   render mode (embed: payload) — `okf render` bakes the whole bundle in:
-    #     the same fetch getters resolve from the injected payload instead, so
-    #     the single file needs no server (e.g. hosting on GitHub Pages).
+    #   render mode (embed: payload) — `okf render` bakes the whole bundle in via
+    #     .static below: the same fetch getters resolve from the injected payload
+    #     instead, so the single file needs no server (e.g. GitHub Pages).
     #
     # NOTE (trust boundary): the page loads Cytoscape + marked from a CDN, so it
     # needs network for those libraries even in render mode. Fetched/embedded
@@ -38,6 +42,28 @@ module OKF
       # built from the backslash code point so no literal escape appears here.
       LT_ESCAPE = (92.chr(Encoding::UTF_8) + "u003c").freeze
 
+      # `okf render`: the whole page as one self-contained file, the bundle baked
+      # in, so it hosts where no server answers a fetch. Takes any bundle handle
+      # (an OKF::Bundle::Folder) and returns the HTML string.
+      def self.static(folder, title: nil, link: nil, layout: "cose")
+        new(folder.graph(minimal: true), title: title || folder.name, link: link, layout: layout, embed: payload(folder)).render
+      end
+
+      # What the baked page carries in place of the endpoints a live server would
+      # answer. Every key here is data a client getter reads from EMBED instead of
+      # fetching — and each derives from the *same* folder method the matching
+      # OKF::Server::App endpoint uses, so the bake and the live server cannot
+      # drift (/node/meta is the exception: the fragment is derived on the client
+      # from the catalog's raw description, so no map is baked for it).
+      def self.payload(folder)
+        {
+          catalog: folder.catalog,
+          index: folder.directory_index,
+          logs: folder.log_entries,
+          bodies: folder.concepts.each_with_object({}) { |concept, map| map[concept.id] = concept.body.to_s }
+        }
+      end
+
       # +node_endpoint+/+meta_endpoint+ are the (mount-relative) URLs the page
       # fetches a concept's raw markdown and metadata fragment from — relative so
       # the page works whether served at "/" or mounted under a Rails prefix.
@@ -45,9 +71,11 @@ module OKF
       # +siblings+/+self_slug+/+hub_path+ carry the hub's bundle switcher into the
       # page (server mode only). nil — the standalone-server and `okf render`
       # default — injects an empty SIBLINGS, so the switcher never appears in a
-      # single bundle or a static file.
+      # single bundle or a static file. +search_endpoint+ rides along with them:
+      # the hub's cross-bundle /search, which only a hub can answer.
       def initialize(graph, title: nil, link: nil, layout: "cose", node_endpoint: "node", meta_endpoint: "node/meta", embed: nil,
-                     siblings: nil, self_slug: nil, hub_path: nil)
+                     siblings: nil, self_slug: nil, hub_path: nil, search_endpoint: nil,
+                     manage_root: nil, manage_token: nil)
         @graph = graph
         @title = title
         @link = link
@@ -58,6 +86,9 @@ module OKF
         @siblings = siblings
         @self_slug = self_slug
         @hub_path = hub_path
+        @search_endpoint = search_endpoint
+        @manage_root = manage_root
+        @manage_token = manage_token
       end
 
       def render
@@ -74,6 +105,12 @@ module OKF
         html_escape(graph_name)
       end
 
+      # The bundle's own name, for the client: what the header already shows, so
+      # the page can label the root with it instead of `(root)` or `/`.
+      def name_json
+        json_for_script(graph_name)
+      end
+
       def og_title
         html_escape("OKF · #{graph_name}")
       end
@@ -126,6 +163,45 @@ module OKF
         json_for_script(@hub_path)
       end
 
+      # The hub's cross-bundle /search, mount-relative — null everywhere else, and
+      # that null is the gate: a standalone server and a static file have no set
+      # of bundles to search, so the palette never offers concepts there.
+      def search_endpoint_json
+        json_for_script(@search_endpoint)
+      end
+
+      # Behind a hub the mark is a link back to the bundle list — "../" reaches
+      # it under any mount, because every page lives at <prefix>/b/<slug>/.
+      # Standalone and static have nowhere to go, so there it stays the plain
+      # identity badge it has always been, and an <a href> to nothing is worse
+      # than no <a> at all.
+      def rail_brand_open
+        return %(<span class="rail-brand" title=") unless @manage_root
+
+        %(<a class="rail-brand" href="../" aria-label="All bundles" title=")
+      end
+
+      def rail_brand_close
+        @manage_root ? "</a>" : "</span>"
+      end
+
+      # The hub root, mount-relative — where the Bundles panel reads /bundles and
+      # posts /registry/<verb>. Null everywhere else, and that null is the gate:
+      # a standalone server and a static file have no registry behind them, so
+      # the panel never appears there.
+      def manage_root_json
+        json_for_script(@manage_root)
+      end
+
+      # This boot's CSRF token, and only where a write could be honoured — a
+      # read-only hub bakes null, so the page holds no credential it may not use.
+      # It is no wider than the /b/ manager, which any script on this origin
+      # could already read; keeping it out of the page where it is useless is
+      # tidiness, not a boundary.
+      def manage_token_json
+        json_for_script(@manage_token)
+      end
+
       # JSON-encode for safe embedding in an inline <script>: escaping every `<` to
       # its JSON unicode escape neutralizes </script>, <!-- and <script in one
       # stroke, and the result stays valid JSON *and* JavaScript.

data/lib/okf/server/app.rb

@@ -2,7 +2,7 @@
 
 require "rack"
 
-require "okf/server/graph"
+require "okf/render/graph"
 
 module OKF
   module Server
@@ -11,7 +11,7 @@ module OKF
     #
     #   mount OKF::Server::App.new(folder) => "/knowledge"
     #
-    # The page (OKF::Server::Graph) boots from a *minimal* graph (id + title + edges
+    # The page (OKF::Render::Graph) boots from a *minimal* graph (id + title + edges
     # + type/tag indexes) and pulls each concept's markdown body and description from
     # here on demand, so the initial payload stays small and bodies are read live
     # from disk (edits show without a restart). Part of the shell — it does I/O.
@@ -33,9 +33,11 @@ module OKF
     class App
       # +siblings+/+self_slug+/+hub_path+ are set only when this app is hosted under
       # a hub (OKF::Server::Hub): the other bundles the in-page switcher offers, this
-      # bundle's own mount slug, and the hub root. They stay nil for a standalone
-      # server and for `okf render`, so a static file never advertises a switcher.
-      def initialize(folder, title: nil, link: nil, layout: "cose", siblings: nil, self_slug: nil, hub_path: nil)
+      # bundle's own mount slug, the hub root, and the hub's cross-bundle search
+      # route. They stay nil for a standalone server and for `okf render`, so a
+      # static file never advertises a switcher or a search it cannot answer.
+      def initialize(folder, title: nil, link: nil, layout: "cose", siblings: nil, self_slug: nil, hub_path: nil,
+                     search_endpoint: nil, manage_root: nil, manage_token: nil)
         @folder = folder
         @title = title
         @link = link
@@ -43,6 +45,9 @@ module OKF
         @siblings = siblings
         @self_slug = self_slug
         @hub_path = hub_path
+        @search_endpoint = search_endpoint
+        @manage_root = manage_root
+        @manage_token = manage_token
       end
 
       def call(env)
@@ -62,13 +67,6 @@ module OKF
         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
-
       # The 404 both this app and the Hub answer with, so the two cannot drift.
       def self.not_found
         [ 404, { "content-type" => "text/plain; charset=utf-8" }, [ "not found\n" ] ]
@@ -97,50 +95,21 @@ module OKF
         { 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.
+      # The §7 history the Log panel renders: every log.md with its content, root
+      # scope first, read live from disk. Built by OKF::Bundle::Folder#log_entries,
+      # shared with `okf render`'s bake so the served and baked logs cannot drift.
       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)
+        { logs: @folder.log_entries }
       end
 
       def page
-        @page ||= Graph.new(
+        @page ||= OKF::Render::Graph.new(
           graph, title: @title || @folder.name, link: @link, layout: @layout,
-          siblings: @siblings, self_slug: @self_slug, hub_path: @hub_path
+          siblings: @siblings, self_slug: @self_slug, hub_path: @hub_path, search_endpoint: @search_endpoint,
+          manage_root: @manage_root, manage_token: @manage_token
         ).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?