okf 1.11.0 → 1.13.0

data/lib/okf/cli/registry.rb

@@ -10,7 +10,7 @@ module OKF
     class Registry < Command
       # The `registry` umbrella's subcommands — the dispatch, and the words a
       # flag-first invocation is checked against.
-      SUBCOMMANDS = %w[set del list default rename].freeze
+      SUBCOMMANDS = %w[init set del list default rename group ungroup].freeze
 
       def self.id
         :registry
@@ -22,11 +22,14 @@ module OKF
 
       def self.help_rows
         [
+          [ "registry  init", "create a project-local .okf-registry.json (nearest one wins)" ],
           [ "registry  list [--json]", "list registered bundles (* marks the default)" ],
           [ "registry  set <dir|@slug> [--as SLUG] [--default]", "add or update a bundle (a bare `server` serves them)" ],
-          [ "registry  del <dir|@slug>", "remove a bundle from the registry" ],
+          [ "registry  del <dir|@slug>", "remove a bundle or group from the registry" ],
           [ "registry  default <@slug>", "move a bundle to the front (the default)" ],
-          [ "registry  rename <@slug> <new>", "rename a registered bundle (<new> is a new name, not a ref)" ]
+          [ "registry  rename <@slug> <new>", "rename a bundle or group (<new> is a new name, not a ref)" ],
+          [ "registry  group <slug> <@member…>", "create a group, or add members (search/server can target @slug)" ],
+          [ "registry  ungroup <slug> <@member…>", "remove members from a group (emptying it deletes it)" ]
         ]
       end
 
@@ -35,11 +38,14 @@ module OKF
 
         sub = argv.first
         case sub
+        when "init" then registry_init(argv.drop(1))
         when "set" then registry_set(argv.drop(1))
         when "del" then registry_del(argv.drop(1))
         when "list" then registry_list(argv.drop(1))
         when "default" then registry_default(argv.drop(1))
         when "rename" then registry_rename(argv.drop(1))
+        when "group" then registry_group(argv.drop(1))
+        when "ungroup" then registry_ungroup(argv.drop(1))
         else
           # A bare word that isn't a known subcommand is a typo (`registry remove x`
           # must not silently render the list and read as success).
@@ -61,6 +67,38 @@ module OKF
 
       private
 
+      # Create a project-local .okf-registry.json in the current directory. Once it
+      # exists, discovery finds it (walking up from cwd) and every registry op —
+      # and every @ref — resolves through it instead of the global $OKF_HOME one.
+      # init only writes the empty file; `registry set` fills it. Refuses to clobber
+      # an existing local registry, and notes a parent one it would shadow.
+      def registry_init(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry init"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        no_extras?(argv) or return 2
+
+        target = File.join(Dir.pwd, OKF::Registry::LOCAL_FILE)
+        display = "./#{OKF::Registry::LOCAL_FILE}"
+        return usage_error("already initialized: #{display}") if File.exist?(target)
+
+        # The parent it would shadow, if any — a courtesy, not a barrier: nested
+        # registries resolve nearest-first, so creating one here is legitimate.
+        parent = OKF::Registry.discover(File.dirname(Dir.pwd))
+        @err.puts "note: a parent registry at #{parent} — the nearest one wins" if parent
+
+        OKF::Registry.new(target).save
+        @out.puts "initialized #{display}"
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
       # Add a bundle to the persistent registry (so a later bare `okf server` finds
       # it), or update one already there. The entry is keyed by the bundle's path: a
       # path already registered refreshes its title in place, and --as renames it. A
@@ -78,7 +116,7 @@ module OKF
         # positional through `positional`, which does not check.
         dir = positional_dir(parser, argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         # Said before the upsert: after it, an update is indistinguishable from an
         # add, and "registered" for what was a rename reads as a duplicate entry.
         known = reg.listing.any? { |row| row[:dir] == File.expand_path(dir) }
@@ -104,7 +142,7 @@ module OKF
         slug = positional(parser, argv) or return 2
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         slug = registry_slug(slug, reg) or return 2
         removed = reg.remove(slug)
         return usage_error("no such bundle: #{slug}") unless removed
@@ -131,8 +169,11 @@ module OKF
         end
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
-        return emit_list_json({ "registry" => reg.path }, "bundles", reg.listing.map { |row| stringify(row) }, options) if options[:json]
+        reg = open_registry
+        if options[:json]
+          groups = { "groups" => reg.groups_listing.map { |row| stringify(row) } }
+          return emit_list_json({ "registry" => reg.path }, "bundles", reg.listing.map { |row| stringify(row) }, options, groups)
+        end
 
         print_registry(reg)
         0
@@ -153,7 +194,7 @@ module OKF
         slug = positional(parser, argv) or return 2
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         slug = registry_slug(slug, reg) or return 2
         reg.default = slug
         @out.puts "default bundle → #{reg.default.slug} (now first)"
@@ -196,7 +237,7 @@ module OKF
         end
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         # The old name may be a ref; the new one is a name being minted, never one.
         old_slug = registry_slug(old_slug, reg) or return 2
         entry = reg.rename(old_slug, new_slug)
@@ -211,15 +252,111 @@ module OKF
         usage_error(e.message)
       end
 
+      # Create a group, or add members to one. Members are bundle or group slugs,
+      # bare or as @refs; the model normalizes, unions, checks each names something,
+      # and refuses a cycle. Only `search`/`server` can then target @slug.
+      def registry_group(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry group <slug> <@member…>"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        slug = argv.shift
+        if slug.nil? || argv.empty?
+          @err.puts parser.banner
+          return 2
+        end
+
+        reg = open_registry
+        group = reg.set_group(slug, argv)
+        count = reg.expand(group.slug).size
+        @out.puts "grouped #{group.slug} → #{group.members.map { |m| "@#{m}" }.join(", ")} " \
+                  "(#{count} #{pluralize(count, "bundle")})"
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # Remove members from a group. Emptying it deletes the group — an empty group
+      # resolves to nothing, so it is not worth keeping.
+      def registry_ungroup(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry ungroup <slug> <@member…>"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        slug = argv.shift
+        if slug.nil? || argv.empty?
+          @err.puts parser.banner
+          return 2
+        end
+
+        reg = open_registry
+        removed, emptied = reg.unset_group_members(slug, argv)
+        name = OKF::Registry.normalize(slug)
+        if emptied
+          @out.puts "removed empty group #{name}"
+        elsif removed.empty?
+          @out.puts "no members removed from #{name} (none of #{argv.join(", ")} were in it)"
+        else
+          @out.puts "ungrouped #{removed.map { |m| "@#{m}" }.join(", ")} from #{name}"
+        end
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
       def print_registry(reg)
-        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty?
+        # A header only when a project-local registry is in play — the case where
+        # "which registry am I looking at?" is a real question. The global $OKF_HOME
+        # one is the default, so it stays headerless (and the JSON envelope names
+        # the file for a script either way).
+        @out.puts "registry: #{registry_display(reg)}" if local_registry?(reg)
+        groups = reg.groups_listing
+        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty? && groups.empty?
 
         rows = reg.listing
-        width = rows.map { |row| row[:slug].length }.max
-        rows.each do |row|
-          marker = row[:default] ? "*" : " "
-          missing = row[:missing] ? "  (missing)" : ""
-          @out.puts "#{marker} #{row[:slug].ljust(width)}  #{row[:title]}  (#{row[:dir]})#{missing}"
+        unless rows.empty?
+          width = rows.map { |row| row[:slug].length }.max
+          rows.each do |row|
+            marker = row[:default] ? "*" : " "
+            missing = row[:missing] ? "  (missing)" : ""
+            @out.puts "#{marker} #{row[:slug].ljust(width)}  #{row[:title]}  (#{row[:dir]})#{missing}"
+          end
+        end
+        print_groups(groups, rows) unless groups.empty?
+      end
+
+      # Whether this registry was discovered as a project-local file rather than
+      # read from $OKF_HOME — the basename settles it (only a local one is named
+      # .okf-registry.json).
+      def local_registry?(reg)
+        File.basename(reg.path) == OKF::Registry::LOCAL_FILE
+      end
+
+      # How to name the local registry in the header: `./` when it sits in cwd
+      # (the common case, a bare `init` here), its absolute path when discovery
+      # walked up to an ancestor.
+      def registry_display(reg)
+        File.dirname(reg.path) == Dir.pwd ? "./#{OKF::Registry::LOCAL_FILE}" : reg.path
+      end
+
+      # The groups section under the bundle listing: one row per group, its members
+      # and how many bundles it resolves to (a hand-edited cycle shows `(cycle)`).
+      def print_groups(groups, rows)
+        @out.puts "" unless rows.empty?
+        @out.puts "groups:"
+        width = groups.map { |group| group[:slug].length }.max
+        groups.each do |group|
+          members = group[:members].map { |m| "@#{m}" }.join(", ")
+          count = group[:resolved].nil? ? "cycle" : "#{group[:resolved]} #{pluralize(group[:resolved], "bundle")}"
+          @out.puts "  #{group[:slug].ljust(width)}  #{members}  (#{count})"
         end
       end
     end

data/lib/okf/cli/render.rb

@@ -23,20 +23,21 @@ module OKF
       def call(argv)
         require "okf/render/graph"
 
-        options = { output: nil, title: nil, link: nil, layout: "cose" }
+        options = { output: nil, title: nil, link: nil, layout: "cose", map: false }
         parser = OptionParser.new do |o|
           o.banner = "Usage: okf render <dir|@slug> [-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::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+          o.on("--map", "open in the Map view: concepts boxed by directory, links on selection") { options[:map] = true }
           help_flag(o)
         end
         dir = positional_dir(parser, argv) or return 2
 
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
-        html = OKF::Render::Graph.static(folder, title: options[:title], link: options[:link], layout: options[:layout])
+        html = OKF::Render::Graph.static(folder, title: options[:title], link: options[:link], layout: options[:layout], map: options[:map])
         if options[:output]
           # A bad -o path (a missing directory, a permission denial) is a bad
           # *argument*: exit 2 with the reason, never a backtrace and an exit code

data/lib/okf/cli/search.rb

@@ -158,8 +158,17 @@ module OKF
         pairs
       end
 
-      # One @ref as a single-element [[slug, dir]], or nil after reporting.
+      # One @ref as [[slug, dir], …]: a group fans out to its readable member
+      # bundles, a plain @slug is the single-element pair it always was. nil after
+      # reporting. `ref_targets` dedupes across refs, and #expand within a group, so
+      # `@backend @okf` (okf ∈ backend) still searches okf once.
       def ref_pair(ref)
+        registry = load_registry
+        return nil unless registry
+
+        slug = OKF::Registry.normalize(ref[1..-1])
+        return group_pairs(registry, slug) if !slug.empty? && registry.group?(slug)
+
         path = resolve_registered(ref)
         unless path
           # Only an unknown slug is plausibly a mistyped term — a broken registry
@@ -170,6 +179,28 @@ module OKF
         [ [ ref_slugs[path], path ] ]
       end
 
+      # A group's readable member bundles as [slug, dir] pairs, skipping vanished
+      # ones with a note (as `@all` does) and labelling each leaf by its own slug.
+      # nil (reported) when nothing readable is left, or on a hand-edited cycle.
+      def group_pairs(registry, slug)
+        pairs = []
+        registry.expand(slug).each do |entry|
+          if File.directory?(entry.path)
+            ref_slugs[entry.path] = entry.slug
+            pairs << [ entry.slug, entry.path ]
+          else
+            skip_registered(entry)
+          end
+        end
+        return pairs unless pairs.empty?
+
+        @err.puts "error: @#{slug} resolves to no readable bundle (okf registry list)"
+        nil
+      rescue OKF::Error => e
+        @err.puts "error: #{e.message}"
+        nil
+      end
+
       # Search every bundle at once and merge the rankings, each row labeled with
       # its bundle's slug. The bundles go in as *one* corpus rather than one search
       # each: BM25 weighs a term by how rare it is, so ranking each bundle on its own
@@ -178,16 +209,30 @@ module OKF
       #
       # Filters stay per-bundle — they are per-folder questions — so they apply to
       # the merged rows by (slug, id) afterwards.
+      #
+      # The one thing that is *not* a per-folder question is what `--dir root`
+      # means. The alias yields to a directory that really carries the name, so
+      # resolving it inside this loop made one flag mean two things in one
+      # ranking: the `root/` subtree where a bundle has one, the bundle root
+      # where it does not, merged with nothing in the output saying so. The
+      # served set answers it once, and a bundle without the directory then
+      # matches nothing — which is what `--dir` already does everywhere for a
+      # directory a bundle lacks.
       def multi_search(pairs, terms, options)
-        bundles = []
-        keeps = {}
-        total = 0
-        pairs.each do |slug, dir|
+        folders = pairs.map do |slug, dir|
           folder = OKF::Bundle::Folder.load(dir)
           report_skipped(folder)
-          total += folder.bundle.concepts.size
-          bundles << [ slug, folder.bundle ]
-          keep = filter_ids(folder, options)
+          [ slug, folder ]
+        end
+        total = folders.reduce(0) { |sum, (_, folder)| sum + folder.bundle.concepts.size }
+        bundles = folders.map { |slug, folder| [ slug, folder.bundle ] }
+        # The served set's directories, only when a flag will consult them —
+        # the alias is resolved once across the whole run (see filter_ids),
+        # and an unfiltered search never pays the walk.
+        dirs = options[:dir] || options[:area] ? folders.flat_map { |_, folder| folder.directories }.uniq : nil
+        keeps = {}
+        folders.each do |slug, folder|
+          keep = filter_ids(folder, options, dirs)
           keeps[slug] = keep unless keep.nil?
         end
         rows = OKF::Bundle::Search.across(bundles, terms, fields: options[:in], regexp: options[:regexp],

data/lib/okf/cli/server.rb

@@ -24,7 +24,7 @@ module OKF
         require "okf/server/app"
         require "rack/deflater"
 
-        options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose", read_only: false }
+        options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose", read_only: false, map: 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 }
@@ -32,10 +32,14 @@ module OKF
           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("--map", "open in the Map view: concepts boxed by directory, links on selection") { options[:map] = true }
           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
+        # expand_groups: `okf server @backend` fans a group out to its member
+        # bundles (single-bundle verbs reject a group; server is one of the two that
+        # take a set).
+        dirs = positional_dirs(parser, argv, expand_groups: true) 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])
@@ -64,7 +68,7 @@ module OKF
         # 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")
+          layout: options[:layout], search_endpoint: "search", map: options[:map])
         # 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.
@@ -86,7 +90,7 @@ module OKF
         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
+          reg = open_registry
           # 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) }
@@ -97,7 +101,7 @@ module OKF
         # 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 = OKF::Server::Hub.new(bundles, layout: options[:layout], registry: reg, writable: writable?(options), map: options[:map])
         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,

data/lib/okf/cli/stats.rb

@@ -41,18 +41,18 @@ module OKF
         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_top_dir = entries.group_by { |entry| entry[:top_dir] }.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,
+          top_dirs: by_top_dir.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
+          by_top_dir: by_top_dir
         }
       end
 
@@ -83,9 +83,9 @@ module OKF
         @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.
+        # One grouping word in the human view: `by_top_dir` stays in --json (the
+        # first-segment rollup) but a screen that printed both it and `by_dir`
+        # would double up on one idea, so the human view shows the full-path cut.
         print_stat_breakdown("By dir", stats[:by_dir]) { |label| dir_label(label) }
       end
 
@@ -101,9 +101,9 @@ module OKF
 
       def print_stats_json(dir, stats)
         emit_json(bundle_head(dir).merge(
-          "concepts" => stats[:concepts], "dirs" => stats[:dirs], "areas" => stats[:areas],
+          "concepts" => stats[:concepts], "dirs" => stats[:dirs], "top_dirs" => stats[:top_dirs],
           "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]
+          "by_type" => stats[:by_type], "by_dir" => stats[:by_dir], "by_top_dir" => stats[:by_top_dir]
         ))
       end
     end

data/lib/okf/cli/tags.rb

@@ -61,7 +61,7 @@ module OKF
       # 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
+        by_id = filter_entries(folder.catalog, options, dir_scope(folder, options)).map { |entry| [ entry[:id], entry ] }.to_h
         groups = {}
         totals = Hash.new(0)
         tag_index.each do |tag, ids|
@@ -93,7 +93,7 @@ module OKF
         case dim
         when :type then entry_type(entry)
         when :dir then entry[:dir]
-        else entry[:area]
+        else entry[:top_dir]
         end
       end
 

data/lib/okf/cli.rb

@@ -32,14 +32,14 @@ module OKF
     # Declared in emission order, so the "available:" list a typo prints reads
     # the same as the rows themselves.
     ROW_FIELDS = {
-      "matches" => %w[id title type dir area tags matched score snippet],
+      "matches" => %w[id title type dir top_dir tags matched score snippet],
       # Registry mode labels every row with the bundle it came from; a plain-dir
       # search has one bundle and no slug to carry. Two shapes, because the typo
       # guard checks against the *declared* one — a single shape covering both
       # would let `--fields slug` pass on a search whose rows have none, and hand
       # back an empty object per match under a count that says otherwise.
-      "matches_by_ref" => %w[slug id title type dir area tags matched score snippet],
-      "concepts" => %w[id title type description tags timestamp status backlog_ref dir area links_out links_in],
+      "matches_by_ref" => %w[slug id title type dir top_dir tags matched score snippet],
+      "concepts" => %w[id title type description tags timestamp status backlog_ref dir top_dir links_out links_in],
       "files" => %w[path id dir type title description],
       "directories" => %w[dir ancestor index_path present synthesized count types tags subdirs body listing],
       "dirs" => %w[dir ancestor count subtree subdirs],

data/lib/okf/concept/file.rb

@@ -14,6 +14,13 @@ module OKF
     #
     # NOTE: this class is named File, which shadows Ruby's File inside the
     # OKF::Concept namespace — every filesystem call here uses ::File explicitly.
+    #
+    # absolute_path guards the *name* lexically (Path.join_under!), which is all a
+    # write needs — the file may not exist yet. A read has more to prove: the file
+    # is on disk now, so it may be a symlink whose name is inside the root but
+    # whose target is not, and File.expand_path does not resolve links. So #read
+    # goes through SafeRead, which realpath-resolves and refuses a target outside
+    # the root, closing the same escape Bundle::Reader closes on the bulk read.
     class File
       attr_reader :root, :path, :concept
 
@@ -53,11 +60,19 @@ module OKF
       end
 
       def reload
-        content = ::File.read(absolute_path, encoding: "UTF-8")
-        frontmatter, body = Markdown::Frontmatter.parse(content)
+        frontmatter, body = Markdown::Frontmatter.parse(read)
         @concept = Concept.new(path: @path, frontmatter: frontmatter, body: body)
         self
       end
+
+      # The file's own bytes, refused if the resolved target escapes the root by
+      # symlink. This is the guarded read a caller that wants the raw markdown
+      # (not a re-serialized `concept.to_markdown`) must use instead of reading
+      # #absolute_path itself — that path guards the *name* lexically, which a
+      # write needs but a read does not, since the file exists and may be a link.
+      def read
+        SafeRead.read!(@root, absolute_path)
+      end
     end
   end
 end

data/lib/okf/path.rb

@@ -24,11 +24,25 @@ module OKF
       relative = normalize_relative!(path)
       expanded_root = File.expand_path(root.to_s)
       expanded_path = File.expand_path(File.join(expanded_root, relative))
-      unless expanded_path == expanded_root || expanded_path.start_with?("#{expanded_root}#{File::SEPARATOR}")
-        raise Error, "path escapes bundle root"
-      end
+      raise Error, "path escapes bundle root" unless under?(expanded_root, expanded_path)
 
       expanded_path
     end
+
+    # Is +path+ the root itself or a descendant of it? Pure string containment
+    # (no disk access), so it works on both lexical paths (File.expand_path) and
+    # symlink-resolved ones (File.realpath) — the shell resolves, this decides.
+    # Both arguments must already be absolute and normalized the same way.
+    #
+    # The prefix guards against a sibling passing as a child ("/foo" is not under
+    # "/food"), and reuses the root itself as the prefix when the root already
+    # ends in the separator — i.e. the filesystem root "/", whose children would
+    # otherwise be tested against "//" and every one rejected.
+    def self.under?(root, path)
+      return true if path == root
+
+      prefix = root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+      path.start_with?(prefix)
+    end
   end
 end