okf 1.12.0 → 1.13.0

data/lib/okf/bundle/folder.rb

@@ -54,6 +54,10 @@ module OKF
         @bundle.hubs
       end
 
+      def directories
+        @bundle.directories
+      end
+
       def directory_index
         @bundle.directory_index
       end
@@ -104,6 +108,17 @@ module OKF
         Concept::File.read(root: @root, path: path)
       end
 
+      # The raw markdown bytes for one concept id — read once through the same
+      # containment guard as #concept, but without the parse #concept pays for,
+      # so a caller that wants the file verbatim (never a re-serialized copy)
+      # does one read, not a read plus a discarded frontmatter parse. nil when no
+      # concept has that id; raises Path::Error if the file has become a symlink
+      # escaping the root, and the reader's own SystemCallError if it has gone.
+      def concept_source(id)
+        path = @bundle.paths_by_id[id] or return nil
+        Concept::File.new(root: @root, path: path).read
+      end
+
       # Materialize the in-memory bundle to disk (Writer validates §9 before
       # publishing, so a malformed bundle is never written).
       def save(overwrite: false)
@@ -131,8 +146,12 @@ module OKF
       end
 
       def log_content(path)
-        File.read(File.join(@root, path), encoding: "UTF-8")
-      rescue SystemCallError
+        # Live, but through the same containment as every other read: a log.md
+        # that was a real file at boot and is a symlink out of the root now falls
+        # back to the boot snapshot rather than serving the target — the same
+        # answer a vanished file gets, since an escape is a file we must not read.
+        SafeRead.read!(@root, File.join(@root, path))
+      rescue SystemCallError, Path::Error
         @bundle.reserved_content(path)
       end
     end

data/lib/okf/bundle/reader.rb

@@ -12,10 +12,17 @@ module OKF
     # cannot open at all — is retained as an unparseable entry (carrying the
     # ParseError message or the errno, so §9.1 can report it) rather than dropped
     # or raised. That tolerance is the whole §9 best-effort promise: one bad file
-    # never breaks the rest, and this is the read every verb shares. Every read
-    # goes through Path.join_under! so a symlinked or crafted path cannot escape
-    # the bundle root — that guard still raises, because a path leaving the root
-    # is not a bad file, it is a bundle lying about its shape.
+    # never breaks the rest, and this is the read every verb shares.
+    #
+    # Containment is enforced twice, because the two ways out of the root are
+    # different. A crafted *path* (`..`, an absolute string) is caught lexically
+    # by Path.join_under!. A *symlink* whose name sits inside the root but whose
+    # target does not cannot be seen lexically — File.expand_path does not
+    # resolve links — so each file is also realpath-resolved and its real
+    # location checked against the real root before a byte is read. An escaping
+    # file joins the unparseable bucket rather than raising: a planted symlink is
+    # one bad file, and letting it take down the whole bundle read would hand any
+    # writer of a served directory a denial of service. §9.1 then names it.
     class Reader
       def self.read(dir)
         new(dir).read
@@ -32,9 +39,22 @@ module OKF
         reserved = []
         unparseable = []
 
-        markdown_paths.each do |path|
+        paths = markdown_paths
+        # Resolved once for the whole loop, but never at the cost of the
+        # best-effort promise: if the root itself has become unreadable since
+        # the glob, this stays nil and each file's own SafeRead call raises
+        # inside the per-file rescue below — one bad bundle degrades to
+        # unparseable entries, it does not crash the read every verb shares.
+        real_root = begin
+          File.realpath(@root) unless paths.empty?
+        rescue SystemCallError
+          nil
+        end
+
+        paths.each do |path|
           begin
-            content = File.read(Path.join_under!(@root, path), encoding: "UTF-8")
+            absolute = Path.join_under!(@root, path)
+            content = SafeRead.read!(@root, absolute, real_root: real_root)
             if Concept.reserved?(path)
               reserved << Entry.new(path: path, content: content)
             else
@@ -43,18 +63,21 @@ module OKF
             end
           rescue Markdown::Frontmatter::ParseError => e
             unparseable << Entry.new(path: path, content: content, error: e.message)
-          rescue SystemCallError => e
-            # A file that cannot be opened is one unusable file, not a broken
-            # bundle. Letting the errno out of here breaks "one bad file never
-            # breaks the rest" for every verb at once — the read is the one path
-            # they all share — and it breaks it in the worst way: a backtrace,
-            # under an exit code that claims the bundle is non-conformant. So it
-            # joins the same bucket a bad frontmatter block does, and §9.1 reports
-            # it naming the file and the errno.
+          rescue Path::Error, SystemCallError => e
+            # A file we cannot safely read is one unusable file, not a broken
+            # bundle: an errno on open, or a path that leaves the root — lexically
+            # (`..`, an absolute string) or through a symlink whose target escapes
+            # it. Letting either out of here breaks "one bad file never breaks the
+            # rest" for every verb at once — the read is the one path they all
+            # share — and in the worst way: a backtrace under an exit code that
+            # claims non-conformance, or a served bundle taken down by one planted
+            # symlink. So it joins the same bucket a bad frontmatter block does,
+            # and §9.1 reports it naming the file and the reason.
             #
             # Its content is "" rather than nil: unknown, but every analyzer reads
-            # it as text, and empty is the honest shape of a file we never saw —
-            # no links to resolve, no encoding to be invalid, nothing claimed.
+            # it as text, and empty is the honest shape of a file we never read —
+            # no links to resolve, nothing claimed, and for a symlink escape, none
+            # of the target's bytes.
             unparseable << Entry.new(path: path, content: "", error: e.message)
           end
         end

data/lib/okf/bundle.rb

@@ -160,6 +160,18 @@ module OKF
     # `id` must not move a concept out of the directory it lives in. Pure: derived
     # from the concepts and the reserved index text, no disk. Shared by the
     # `okf index` view and the server's Index panel (/index).
+    # Every directory this bundle has — the same set #directory_index enumerates
+    # (concepts, an index.md or a log.md, plus every ancestor), without building
+    # the map. It is the answer to "does this bundle have a directory named X?",
+    # and the CLI needs exactly that to decide whether `--dir root` names a real
+    # directory or the bundle root. Reading it off #catalog instead is the same
+    # question asked of a smaller set, which is how the two views came to
+    # disagree about one bundle. Memoized: the model is immutable once read,
+    # and the resolvers above ask per invocation, not per bundle load.
+    def directories
+      @directories ||= directory_set(concepts.map { |concept| File.dirname(concept.path) }.uniq)
+    end
+
     def directory_index
       by_dir = concepts.group_by { |concept| File.dirname(concept.path) }
       dirs = directory_set(by_dir.keys)
@@ -200,11 +212,14 @@ module OKF
       id.include?("/") ? id.split("/").first : "(root)"
     end
 
-    # Every directory to show: those holding concepts or an index.md, plus each of
-    # their ancestors up to the root, so the subdir tree stays connected even when
-    # an intermediate directory holds nothing directly. Sorted with "." first.
+    # Every directory to show: those holding concepts, an index.md or a log.md,
+    # plus each of their ancestors up to the root, so the subdir tree stays
+    # connected even when an intermediate directory holds nothing directly. A
+    # scoped log counts because `okf log` reads it — a directory whose only file
+    # is its history still exists, and leaving it out is how the `root` alias
+    # beat a real `root/` for the second file kind in a row. Sorted "." first.
     def directory_set(concept_dirs)
-      seed = concept_dirs + index_files.map { |path| File.dirname(path) }
+      seed = concept_dirs + (index_files + log_files).map { |path| File.dirname(path) }
       dirs = {}
       seed.each do |dir|
         current = dir

data/lib/okf/cli/catalog.rb

@@ -33,7 +33,7 @@ module OKF
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.catalog
-        selected = filter_entries(entries, options)
+        selected = filter_entries(entries, options, dir_scope(folder, options))
         return print_catalog_json(dir, selected, options) if options[:json]
 
         print_catalog(dir, selected, entries.size)

data/lib/okf/cli/command.rb

@@ -190,22 +190,52 @@ module OKF
         parser.on("--tag TAG", "only concepts carrying this tag") { |v| options[:tag] = v } if keys.include?(:tag)
       end
 
-      def filter_entries(entries, options)
+      # The argument is resolved once per view, not once per entry: the `root`
+      # alias below has to consult the bundle's own directories, and that is a
+      # question about the whole set rather than about the row in hand.
+      #
+      # +dirs+ is that set, and every in-tree caller passes it (see #dir_scope)
+      # rather than deriving it from +entries+ — the catalog knows only
+      # directories that hold *concepts*, so a `root/` carrying an index.md and
+      # nothing else was invisible here while `dirs` and `index` (which read
+      # Bundle#directories) saw it. Two answers to one question about one
+      # bundle is how the alias survived its own fix.
+      #
+      # The default is a compatibility promise, not a shortcut: this base is
+      # what every plugin verb inherits, and 1.12.0 shipped the two-argument
+      # shape. An out-of-tree caller that never learned the third argument gets
+      # exactly the resolution it was written against — the alias folds with no
+      # directory set consulted — no better and no worse.
+      def filter_entries(entries, options, dirs = nil)
+        area = options[:area] && fold_area(options[:area], dirs)
+        base = options[:dir] && fold_dir(options[:dir], dirs)
         entries.select do |entry|
           (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
-            (options[:area].nil? || fold(entry[:top_dir]) == fold_area(options[:area])) &&
-            (options[:dir].nil? || under_dir?(entry[:dir], options[:dir])) &&
+            (area.nil? || fold(entry[:top_dir]) == area) &&
+            (base.nil? || under_dir?(entry[:dir], base)) &&
             (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
         end
       end
 
+      # The directory set only when a flag is going to consult it. Deriving it
+      # walks every path up to the root, and #filter_entries reads it solely to
+      # resolve the `root`/`--area` aliases — a plain listing, or a type/tag
+      # narrowing, never needs the walk.
+      def dir_scope(folder, options)
+        options[:dir] || options[:area] ? folder.directories : nil
+      end
+
       # The one rule --dir is built on: a dir names itself and everything beneath
       # it. `--dir foo` reaches foo/bar, `--dir foo/bar` narrows, and `--dir .`
       # needs no special case at all — nothing starts with "./", so the root
       # selects only what lives directly in it.
-      def under_dir?(entry_dir, wanted)
+      #
+      # +path+ arrives already folded, through #fold_dir for a user's argument
+      # and #fold for a stored one. A stored dir is never an alias — that is the
+      # distinction the old signature could not make, and it is what had a row
+      # named `root` counting the bundle root's subtree instead of its own.
+      def under_dir?(entry_dir, path)
         entry = fold(entry_dir)
-        path = fold_dir(wanted)
         entry == path || entry.start_with?("#{path}/")
       end
 
@@ -213,16 +243,34 @@ module OKF
         value.to_s.downcase
       end
 
-      def fold_area(value)
+      def fold_area(value, known = nil)
         folded = trim_slash(fold(value))
-        folded == "root" ? "(root)" : folded
+        folded == "root" && !names_dir?(known, "root") ? "(root)" : folded
       end
 
       # `.` is the stored spelling of the root everywhere; `root` is the one a
       # shell needs no quoting for, and the only reason the two exist.
-      def fold_dir(value)
+      #
+      # A bundle that really has a `root/` directory owns the word, and +known+
+      # — the directories that bundle actually holds — is what decides. The
+      # alias is a convenience; being able to name a directory at all is not, so
+      # the convenience yields. Without this, `--dir root` answered for the
+      # bundle root in such a bundle: the wrong concepts, exit 0, nothing said.
+      def fold_dir(value, known = nil)
         folded = trim_slash(fold(value))
-        folded.empty? || folded == "root" ? "." : folded
+        return "." if folded.empty?
+
+        folded == "root" && !names_dir?(known, "root") ? "." : folded
+      end
+
+      # Does the bundle hold a directory by this name? An ancestor counts: a
+      # bundle whose only concept sits in `root/deep` still has a `root`, and
+      # `--dir root` has to reach it by the prefix rule above.
+      def names_dir?(known, name)
+        Array(known).any? do |dir|
+          folded = fold(dir)
+          folded == name || folded.start_with?("#{name}/")
+        end
       end
 
       # The human views print a directory with the slash that says it is one —
@@ -307,7 +355,7 @@ module OKF
 
         stored = known.each_with_object({}) { |dir, out| out[fold(dir)] = dir }
         Array(options[:dirs]).each_with_object([]) do |path, out|
-          base = fold_dir(path)
+          base = fold_dir(path, known)
           next unless stored.key?(base)
 
           current = dir_parent(base)
@@ -331,7 +379,7 @@ module OKF
       # they do not define one. The ancestor chain is unioned on top by the
       # caller, which is also what tells a row apart from context.
       def select_dirs(dirs, options)
-        bases = Array(options[:dirs]).map { |path| fold_dir(path) }
+        bases = Array(options[:dirs]).map { |path| fold_dir(path, dirs) }
         depth = options[:depth]&.to_i
         return dirs if bases.empty? && depth.nil?
         # No --dir means the whole bundle is the starting point, which is *not*
@@ -373,10 +421,17 @@ module OKF
 
       # 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)
+      #
+      # +dirs+ overrides the folder's own directory set, which is what a
+      # multi-bundle run passes: the `root` alias is a fact about a bundle, so
+      # resolving it per folder inside a loop let one `--dir root` mean the
+      # `root/` subtree in one bundle and the bundle root in the next, merged
+      # into a single ranking with nothing saying so. One invocation, one
+      # meaning — see Search#multi_search.
+      def filter_ids(folder, options, dirs = nil)
         return nil if options[:type].nil? && options[:area].nil? && options[:dir].nil? && options[:tag].nil?
 
-        filter_entries(folder.catalog, options).map { |entry| entry[:id] }
+        filter_entries(folder.catalog, options, dirs || dir_scope(folder, options)).map { |entry| entry[:id] }
       end
 
       # §9 best-effort: the graph is built from concepts that parse. Surface any that

data/lib/okf/cli/dirs.rb

@@ -79,7 +79,7 @@ module OKF
       def subtree_counts(entries)
         entries.each_with_object({}) do |entry, out|
           out[entry[:dir]] = entries.reduce(0) do |sum, other|
-            under_dir?(other[:dir], entry[:dir]) ? sum + other[:count] : sum
+            under_dir?(other[:dir], fold(entry[:dir])) ? sum + other[:count] : sum
           end
         end
       end

data/lib/okf/cli/files.rb

@@ -33,7 +33,7 @@ module OKF
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.catalog
-        selected = filter_entries(entries, options)
+        selected = filter_entries(entries, options, dir_scope(folder, options))
         return print_files_json(dir, selected, options) if options[:json]
 
         print_files(dir, selected, entries.size)

data/lib/okf/cli/index.rb

@@ -91,11 +91,11 @@ module OKF
       # deprecated flag that quietly widens is worse than one that is merely old.
       # Nothing passed keeps the whole map.
       def select_directories(entries, options)
-        areas = Array(options[:areas]).map { |area| fold_dir(area) }
+        all_dirs = entries.map { |entry| entry[:dir] }
+        areas = Array(options[:areas]).map { |area| fold_dir(area, all_dirs) }
         scoped = !options[:dirs].nil? || !options[:depth].nil?
         return [ entries, [] ] if areas.empty? && !scoped
 
-        all_dirs = entries.map { |entry| entry[:dir] }
         wanted = scoped ? select_dirs(all_dirs, options) : []
         chain = ancestor_dirs(options, all_dirs) - wanted
         selected = entries.select do |entry|

data/lib/okf/cli/search.rb

@@ -209,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/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|

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

data/lib/okf/safe_read.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "path"
+
+module OKF
+  # Shell-side containment for reads. `Path.under?` is the pure decision; the
+  # `File.realpath` that feeds it is disk I/O, so it lives here, out of the pure
+  # core. Every byte a bundle serves is read through this one primitive — the
+  # Reader's bulk load, `Concept::File`, the live `log.md` re-read, the MCP
+  # shell's concept and index reads — so a symlink whose name sits inside the
+  # root but whose target does not is refused in exactly one place. A read that
+  # rolled its own check could quietly drift and reopen the escape; there is
+  # nothing to drift from here.
+  #
+  # Scope. This closes the escape a *symlink* opens — the one a bundle can carry
+  # through a git clone, a copy or a tarball, which is the portable, adversarial
+  # case (a shared bundle whose author points a link at your secrets). It does
+  # not close a *hardlink*: File.realpath cannot resolve one (a hardlink shares
+  # its target's inode and keeps its own in-root path), and the obvious guard —
+  # rejecting st_nlink > 1 — would break a bundle on a deduplicating filesystem
+  # (a Nix store, some CI caches) where ordinary files legitimately share links.
+  # A hardlink to an outside file requires local write access to the served
+  # directory on the target's own filesystem, and cannot survive being copied,
+  # so it is a narrower, non-portable threat left deliberately out of scope.
+  module SafeRead
+    module_function
+
+    # The file's real, symlink-resolved location, or Path::Error if it escapes
+    # +root+. Pass +real_root+ when resolving many paths under one root (the
+    # Reader's loop) so the root is resolved once, not per file.
+    def contained_path!(root, path, real_root: nil)
+      real = ::File.realpath(path)
+      real_root ||= ::File.realpath(root)
+      raise Path::Error, "symlink target escapes bundle root" unless Path.under?(real_root, real)
+
+      real
+    end
+
+    # +path+'s bytes, read from its *resolved* location — so a symlink swapped in
+    # anywhere but the final component is caught, since the resolved path has no
+    # links left to follow — and refused if it escapes. The microscopic window
+    # between resolving and opening the leaf is not closed here (that needs an
+    # open-by-descriptor the 2.4 stdlib does not lend itself to); reading the
+    # resolved path is strictly better than reading the caller's raw name, which
+    # re-followed every link on every read.
+    def read!(root, path, real_root: nil, encoding: "UTF-8")
+      ::File.read(contained_path!(root, path, real_root: real_root), encoding: encoding)
+    end
+  end
+end

data/lib/okf/skill/reference/cli.md

@@ -275,7 +275,8 @@ enumeration drift a grep can't (you can't grep for a listing entry that is *miss
 
 `--dir PATH` narrows to a directory **and everything below it**, and is
 **repeatable** — `--dir model --dir format` shows both; `root` (or `.`) names the
-bundle root. A `--dir` also brings the **chain from the root down to it**, so a branch is
+bundle root, unless the bundle really has a `root/` directory, which owns the
+word. A `--dir` also brings the **chain from the root down to it**, so a branch is
 never shown adrift of the authored context that says what it is — the root
 `index.md`'s prose first among it. Those rows print with a leading `↑` and carry
 `ancestor: true`; `--no-ancestors` drops them. Ascent and descent are separate
@@ -392,7 +393,9 @@ The four list views narrow with the same filters the browser panels offer —
 itself (`tags` can't filter by tag). Matching is case-insensitive; `--type` and
 `--tag` are exact, `--dir` takes the named directory **and everything below it**
 (`--dir platform` reaches `platform/services/api`). A concept at the bundle root
-lives in `.`, which `--dir` also accepts as plain `root` (no shell quoting). A
+lives in `.`, which `--dir` also accepts as plain `root` (no shell quoting) —
+except in a bundle holding a real `root/` directory, where that directory takes
+the name and `.` is the only spelling of the bundle root. A
 filter that matches nothing is an empty view, not an error: `okf tags <dir> --dir
 billing --json` answers "which tags does the billing cluster use?",
 `okf catalog <dir> --tag auth` answers "what carries the auth tag?".

data/lib/okf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OKF
-  VERSION = "1.12.0"
+  VERSION = "1.13.0"
 end

data/lib/okf.rb

@@ -38,6 +38,7 @@ module OKF
 
   # ── kernel: cross-cutting primitives ──
   require "okf/path"
+  require "okf/safe_read"
 
   # ── Markdown: parse structure out of a markdown document (§4/§5/§8) ──
   require "okf/markdown/frontmatter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -78,7 +78,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - NOTICE
 - README.md
@@ -124,6 +123,7 @@ files:
 - lib/okf/registry.rb
 - lib/okf/render/graph.rb
 - lib/okf/render/graph/template.html.erb
+- lib/okf/safe_read.rb
 - lib/okf/server/app.rb
 - lib/okf/server/hub.rb
 - lib/okf/server/hub/not_found.rb
@@ -155,7 +155,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/serradura/okf-gem
   source_code_uri: https://github.com/serradura/okf-gem
-  changelog_uri: https://github.com/serradura/okf-gem/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/serradura/okf-gem/blob/main/okf/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/CODE_OF_CONDUCT.md

@@ -1,10 +0,0 @@
-# Code of Conduct
-
-"okf" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
-
-* Participants will be tolerant of opposing views.
-* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
-* When interpreting the words and actions of others, participants should always assume good intentions.
-* Behaviour which can be reasonably considered harassment will not be tolerated.
-
-If you have any concerns about behaviour within this project, please contact us at ["rodrigo.serradura@gmail.com"](mailto:"rodrigo.serradura@gmail.com").