okf-tui 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c091f949e3ec53c2374154e8c006a32780d4051bd30949d4bd100da01cc3f178
-  data.tar.gz: 685a0064a008179fe03ee3321b135e978998894a279498cdc1354148032af12b
+  metadata.gz: 1b9c76ae8e2518d6c115a26a21a4edae22c3be73a7a6bd106879a85586127b29
+  data.tar.gz: d69fa699c20acfa5032f6016a2ad9ab24ad6be57f5c6e97681a07021e40aa3b6
 SHA512:
-  metadata.gz: 0e1b81de7727c72fb6ec150485bc2a555ee0238fe3b0636e57520b1ef714f804b1f44cf33bd14d3eba0b235f9dc2cefdd5d195a8f85a0838cc74e819f9ad7bc6
-  data.tar.gz: ddce9998f93e6a1259bb3972600ddb1cca8bcd2458d8134d91cd0a4ca966f935949a08bdb40034fc12bcff08f755b495a30f41292fa1216a48eeea0128c56dca
+  metadata.gz: c7a02cb3069109567ed1cd224ec3983f0c420e302547db1f62024da33de118f334d08801507b8384f64c97f2f17cf64924ef3a1b978458029219d2a4b2374f2c
+  data.tar.gz: a95161b1c57329060964bb37c969c54fa9b3e435f69fd94c11221491713bc428db9403f760edaf9dd70433ac699a45ab34a11f80379b95d99c6110d44ad58413

data/.okf/decisions/registry-write-boundary.md

@@ -65,6 +65,33 @@ slug and cascade through every member list that names it. None of that is
 reimplemented; `groups_test.rb` asserts the *effects* — that renaming `@docs`
 leaves `@everything` naming `@papers` — precisely so the cascades stay okf's.
 
+# A linked bundle is inside the boundary and still read-only
+
+okf's global registry can `link` another registry file, and that file's bundles
+and groups resolve into this view. They are configuration in exactly the sense
+above — but configuration this session does not own, since the file that holds
+them is somewhere else and okf refuses every write against one.
+
+So the four keys that act on the selected row — `d`, `n`, `x`, `+` — **refuse
+before the prompt**, naming the link. Letting the ask through would work: okf
+raises, `Workspace` rescues, and the status line carries the message. It would
+also make a user type a new name, or answer `y` to a removal, before learning it
+could never land. The refusal is worth a key's own line for the same reason the
+removal key below got one: a key that stops working has to say so, and *when* it
+says so is part of saying it.
+
+Where the fact lives is a layout decision. The registry pane is 42 columns and
+already carries slug, count and `default`, so a marker there would clip on a
+narrow terminal — which this gem [refuses to do](/rendering/fit-or-say-so.md).
+The bundle detail says `read-only — linked from @onm` and names the owning file
+on the line under it, beside the other "what can I do with this one" lines.
+
+`Entry#link` and `Group#link` come straight off okf's `listing` and
+`groups_listing` rows, and `test/integration/links_registry_test.rb` asserts that
+agreement directly rather than through a fixture — a rename of that field in okf
+would otherwise leave every refusal here quietly not firing, which is the drift
+[okf-capability-drift](/decisions/okf-capability-drift.md) exists to catch.
+
 # What it excludes
 
 Nothing in `lib/` writes a bundle. There is no `OKF::Bundle::Writer` reference in
@@ -80,7 +107,7 @@ poor place to make an irreversible edit to it by muscle memory.
 # `registry init` is excluded, for a different reason
 
 okf 1.12.0 added `okf registry init`, which creates a project-local
-`.okf-registry.json`. It is registry configuration, so the line above admits it —
+`.okf.json`. It is registry configuration, so the line above admits it —
 and it is still not offered, on mechanics rather than principle.
 
 The registry is resolved **once, at boot**: `Workspace#load_entries` opens it, and

data/.okf/interaction/which-registry.md

@@ -1,7 +1,7 @@
 ---
 type: Constraint
 title: Which Registry a Session Is On
-description: okf resolves a project-local .okf-registry.json before the global $OKF_HOME one; the TUI did not, and being the single verb that disagreed was a silent wrong answer rather than an error.
+description: okf resolves a project-local .okf.json before the global $OKF_HOME one; the TUI did not, and being the single verb that disagreed was a silent wrong answer rather than an error.
 tags: [registry, okf-coupling, discovery]
 generated:
   by: human:maintainer
@@ -22,10 +22,12 @@ sources:
 # Overview
 
 "Which bundles can I see?" has one right answer per directory, and okf decides it:
-`OKF_NO_DISCOVERY` forces the global registry; otherwise a `.okf-registry.json`
+`OKF_NO_DISCOVERY` forces the global registry; otherwise a `.okf.json` — or the
+older `.okf-registry.json`, still discovered so no committed registry breaks —
 found by walking up from the working directory wins; otherwise `$OKF_HOME`
-(default `~/.okf`). Nearest local file wins, and a local registry stores paths
-*relative* to itself so it can be committed and travel with the repo.
+(default `~/.okf`). Both names are checked in each directory before climbing, so
+"nearest local file wins" keeps meaning what it says, and a local registry stores
+paths *relative* to itself so it can be committed and travel with the repo.
 
 The TUI ignored all of that for a release. `Workspace` called
 `OKF::Registry.load(home: home)` with no `cwd:`, and okf only discovers when it is
@@ -45,6 +47,25 @@ This is the shape [okf-capability-drift](/decisions/okf-capability-drift.md)
 describes: okf added a resolution rule, the old call kept working, and "kept
 working" meant "kept answering the wrong question".
 
+# A third input arrived, and the answer stayed one method
+
+okf later gained `okf registry link`: the global registry can point at another
+registry file, and that file's bundles and groups resolve into the set. The TUI
+needed no change to show them — `registry_entries` reads `listing` and
+`registry_groups` reads `groups_listing`, and okf folds the linked half into
+both. That is the point. The rule this concept states is that one question has
+one answer per directory; a linked group listed by a *second* method would have
+put the TUI back where it started, showing a smaller set than its own `@ref`
+resolution could open, with nothing failing to say so.
+
+What the TUI had to add for itself is that a linked bundle is **read-only**. The
+config keys reached okf, which refused, and the message arrived on the status
+line — correct, and too late: the user had already typed a new name or confirmed
+a removal. `d`, `n`, `x` and `+` now refuse before the prompt, and the detail
+pane says where the bundle comes from. That is
+[registry-write-boundary](/decisions/registry-write-boundary.md)'s, not this
+file's — what belongs here is only that the *set* stayed one answer.
+
 # The library keeps okf's own line
 
 `cwd:` is a parameter, not a default of `Dir.pwd`, and that mirrors okf exactly:

data/.okf/log.md

@@ -1,5 +1,39 @@
 # Update Log
 
+## 2026-08-22
+
+* **The project-local registry is `.okf.json`, and the TUI inherits that for
+  free** — [which-registry](interaction/which-registry.md),
+  [registry-write-boundary](decisions/registry-write-boundary.md). okf renamed the
+  file and kept discovering the old `.okf-registry.json`, checking both names in
+  each directory on the way up. `Workspace` needed no change, which is the point
+  of asking okf rather than recomputing: the one method that answers "which
+  registry am I on" answered the new question the moment the kernel did. What the
+  two concepts owed was accuracy — one stated the discovery rule and would have
+  stated half of it, and the other named the file it writes.
+
+## 2026-08-21
+
+* **A linked bundle is read-only, and the four config keys say so before they
+  ask** — [registry-write-boundary](decisions/registry-write-boundary.md),
+  [which-registry](interaction/which-registry.md). okf's registry can now `link`
+  another registry file, whose bundles and groups resolve into the bundles view.
+  They list, load, scope and search like any other — but the file that owns them
+  is elsewhere, so okf refuses every write. `d`, `n`, `x` and `+` reached okf,
+  okf raised, and the message landed on the status line *after* the user had
+  typed a new name or confirmed a removal. They now refuse first, naming the
+  link; the bundle detail carries `read-only — linked from @onm` and the owning
+  file underneath. The registry pane is left alone, because 42 columns cannot
+  take another marker without clipping.
+
+* **Nothing was needed to *show* linked bundles at all.** The entries come from
+  okf's `listing` and the groups from its `groups_listing`, and okf folds the
+  linked half into both rather than into a second method — which is the whole
+  point of [which-registry](interaction/which-registry.md)'s rule, arriving from
+  the kernel's side this time. `Entry#link` and `Group#link` are read off those
+  rows, and an agreement test asserts the field against okf itself, since a
+  rename there would leave every refusal above quietly not firing.
+
 ## 2026-08-19
 
 * **This bundle moved to OKF v0.2.** `timestamp:` became

data/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-22
+
+### Added
+
+- **Linked bundles are marked read-only, and the config keys refuse before the
+  prompt.** okf's global registry can now `link` another registry file, and that
+  file's bundles and groups resolve into the bundles view. Browsing one is
+  browsing a bundle, so they list, load, scope and search like any other — but
+  the file that owns them is elsewhere and okf refuses every write against one.
+
+  `d`, `n`, `x` and `+` now say so *before* asking. Without this the ask went
+  through, okf raised, and the message reached the status line only after the
+  user had typed a new name or confirmed a removal. The bundle detail carries
+  `read-only — linked from @onm` and the owning file underneath; the registry
+  pane is left alone, because 42 columns cannot take another marker without
+  clipping.
+
+  Nothing else changed to show linked bundles at all: the entries come from
+  okf's `listing` and the groups from its `groups_listing`, both of which fold
+  the linked half in. `Entry#link` and `Group#link` are read straight off those
+  rows, and the suite asserts that agreement against okf rather than a fixture.
+
+### Changed
+
+- **The project-local registry is now `.okf.json`.** The TUI reads whichever file
+  okf resolves, so this needed no code change — but it is what the header prints
+  and what the "nothing to show" message names, so the file you see identified
+  there has a new name. The older `.okf-registry.json` is still discovered, both
+  names checked in each directory on the way up, so a repository carrying one
+  keeps working untouched. `okf registry init` writes the short name.
+
+- **The `okf` floor moves to 2.2.0**, the kernel that ships `registry link`
+  (`Registry#links_listing`, and the `link` key on listing and group rows).
+  Against 2.1.1 those read as *nil* rather than raising, so a linked bundle would
+  simply never be marked read-only and the four config keys would stop refusing —
+  silent, which is the drift this gem's floor exists to turn into a resolution
+  failure.
+
 ## [1.0.1] - 2026-08-20
 
 ### Fixed

data/README.md

@@ -124,6 +124,10 @@ In the bundles view: `d` default, `a` add, `n` rename, `x` remove (asks first),
 shows what the file now says. Removing a bundle never touches the bundle on
 disk — the registry is a list of references.
 
+A bundle that arrived through an `okf registry link` is read-only — the registry
+that owns it is another file — so those keys say so instead of asking, and the
+detail pane names the link and the file to edit.
+
 It edits your *configuration*, never your knowledge: there is no bundle writing
 anywhere in this gem. Authoring belongs to `okf` and its companion skill.
 
@@ -151,7 +155,7 @@ Anything that can lose configuration asks first and names what it is about to do
 group goes with it. `+`, `c` and `d` add or reorder, and do not ask.
 
 **Which registry.** The same one every other `okf` verb run from the same
-directory resolves: a project-local `.okf-registry.json` when one is on the path
+directory resolves: a project-local `.okf.json` when one is on the path
 up from here, and `$OKF_HOME` (default `~/.okf`) otherwise. `OKF_NO_DISCOVERY=1`
 forces the global one. The header names the file it read, so there is never a
 question which is in force. A workspace of directories named on the command line

data/lib/okf/tui/app.rb

@@ -996,6 +996,10 @@ module OKF::TUI
       return (@message = "no bundle here to add") if entry.nil?
       return (@message = "no group to add it to — c names the bundles in scope as one") if group.nil?
       return (@message = "@#{group.slug} already names @#{entry.slug}") if group.members.include?(entry.slug)
+      # Both halves: a linked bundle cannot be stored as a member (its name lives
+      # only while its link resolves), and a linked group cannot be written to.
+      return if refused_linked?(entry, "grouping")
+      return if refused_linked?(group, "adding to")
 
       apply_group_edit_keeping_focus do
         keeping_group_scoped(group.slug) { workspace.add_to_group(group.slug, [ entry.slug ]) }
@@ -1434,19 +1438,35 @@ module OKF::TUI
     # cascades across every member list, and one `del` cascade-drops the slug and
     # deletes any group it empties. Nothing here has to know that — it just has to
     # pass the slug the cursor is on rather than assuming it is a bundle's.
+    # A bundle or group an okf registry *link* brought in is read-only: the file
+    # that owns it is another registry, and okf refuses every config write against
+    # one. The refusal belongs here, before the prompt — letting the ask through
+    # makes a user type a new name and confirm it before learning it could never
+    # land, and this view's own rule is that a key which stops working says so.
+    # True when it refused, so a caller reads as `return if refused_linked?(…)`.
+    def refused_linked?(subject, action)
+      return false if subject.nil? || !subject.linked?
+
+      @message = "#{action} @#{subject.slug} is read-only — it comes from the linked registry " \
+                 "@#{subject.link}, so edit it there"
+      true
+    end
+
     def ask_rename
-      slug = selected_slug
-      return if slug.nil?
+      subject = detailing_group? ? selected_group : selected_entry
+      return if subject.nil?
+      return if refused_linked?(subject, "renaming")
 
-      ask(:rename, "rename @#{slug} to:", free_text: true, subject: slug)
+      ask(:rename, "rename @#{subject.slug} to:", free_text: true, subject: subject.slug)
     end
 
     def ask_remove
-      slug = selected_slug
-      return if slug.nil?
+      subject = detailing_group? ? selected_group : selected_entry
+      return if subject.nil?
+      return if refused_linked?(subject, "removing")
 
-      what = detailing_group? ? "group @#{slug}" : "@#{slug}"
-      ask(:remove, "remove #{what} from the registry? (y/n)", free_text: false, subject: slug)
+      what = detailing_group? ? "group @#{subject.slug}" : "@#{subject.slug}"
+      ask(:remove, "remove #{what} from the registry? (y/n)", free_text: false, subject: subject.slug)
     end
 
     # The slug the focused pane has selected — a group's when the groups or member
@@ -1458,6 +1478,7 @@ module OKF::TUI
     def set_default
       entry = selected_entry
       return if entry.nil?
+      return if refused_linked?(entry, "defaulting to")
 
       @message = workspace.make_default(entry.slug)
       # Making a bundle the default moves it to the front, so the list reorders

data/lib/okf/tui/cli.rb

@@ -32,7 +32,7 @@ module OKF
             -v, --version      print the version
             -h, --help         print this message
 
-        The registry is the project-local .okf-registry.json when one is on the
+        The registry is the project-local .okf.json when one is on the
         path up from here, and $OKF_HOME (default ~/.okf) otherwise — whichever
         one every other `okf` verb run from here resolves to. OKF_NO_DISCOVERY=1
         forces the global one.
@@ -87,7 +87,7 @@ module OKF
       # `cwd: Dir.pwd` is the other half of that: it is what opts this run into
       # registry discovery, mirroring okf's own rule that only its CLI passes a
       # cwd while a library caller stays global-only. Without it the TUI would be
-      # the one okf verb that ignores a project-local `.okf-registry.json` sitting
+      # the one okf verb that ignores a project-local `.okf.json` sitting
       # right beside the bundles it is being asked about.
       def start(refs)
         return incompatible_okf("cannot answer a search — OKF::Bundle::Search is missing across/prepare/with") unless

data/lib/okf/tui/refs.rb

@@ -28,7 +28,7 @@ module OKF
     # Resolution is also what opts the TUI into registry discovery: Command's
     # `open_registry` is `OKF::Registry.load(cwd: Dir.pwd)`, so a `@slug` here
     # means the same bundle it means to every other okf verb run from the same
-    # directory — the project-local `.okf-registry.json` when there is one on the
+    # directory — the project-local `.okf.json` when there is one on the
     # path up, the global `$OKF_HOME` registry otherwise.
     class Refs < OKF::CLI::Command
       def self.id

data/lib/okf/tui/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module TUI
-    VERSION = "1.0.1"
+    VERSION = "1.1.0"
   end
 end

data/lib/okf/tui/views.rb

@@ -439,6 +439,7 @@ module OKF::TUI
         r.add("  default", :magenta) if entry.default?
       end
       rows << Ui.line(width) { |r| r.add(entry.dir.to_s, :bright_black) }
+      rows.concat(linked_rows(app, entry, width))
       rows.concat(membership_rows(app, entry, width))
       rows << Ui.blank_line(width)
 
@@ -500,6 +501,20 @@ module OKF::TUI
     # can show one membership, and a bundle can have several. This is the line that
     # answers "did that + land" when the group being edited is scrolled out of the
     # groups pane.
+    # Where a linked bundle comes from, and that the config keys will not touch
+    # it. On the detail rather than the registry row: that pane is 42 columns and
+    # already carries slug, count and `default`, so a marker there would clip on a
+    # narrow terminal — and this is the pane where the other "what can I do with
+    # this one" lines already live.
+    def linked_rows(app, entry, width)
+      return [] unless entry.linked?
+
+      target = app.workspace.link_target(entry.link)
+      rows = [ Ui.line(width) { |r| r.add("read-only — linked from @#{entry.link}", :yellow) } ]
+      rows << Ui.line(width) { |r| r.add(target.to_s, :bright_black) } if target
+      rows
+    end
+
     def membership_rows(app, entry, width)
       groups = app.workspace.groups.select { |group| group.members.include?(entry.slug) }
       return [] if groups.empty?

data/lib/okf/tui/workspace.rb

@@ -16,14 +16,22 @@ module OKF::TUI
     # or unreadable, and `error` says which — so a row explains itself instead of
     # silently vanishing from the list.
     class Entry
-      attr_reader :slug, :dir
+      attr_reader :slug, :dir, :link
       attr_accessor :model, :error
 
-      def initialize(slug:, dir:, default:, registered:)
+      def initialize(slug:, dir:, default:, registered:, link: nil)
         @slug = slug
         @dir = dir
         @default = default
         @registered = registered
+        @link = link
+      end
+
+      # Did this bundle arrive through an okf registry link? Browsing one is
+      # browsing a bundle, so it reads like any other — but the registry that
+      # owns it is another file, and okf refuses every config write against it.
+      def linked?
+        !@link.nil?
       end
 
       def default?
@@ -52,13 +60,21 @@ module OKF::TUI
     # the members are what an edit would change, the leaves are what a search
     # would cover, and for a nested group those are not the same list.
     class Group
-      attr_reader :slug, :members, :bundles
+      attr_reader :slug, :members, :bundles, :link
 
-      def initialize(slug:, members:, bundles:, cyclic:)
+      def initialize(slug:, members:, bundles:, cyclic:, link: nil)
         @slug = slug
         @members = members
         @bundles = bundles
         @cyclic = cyclic
+        @link = link
+      end
+
+      # A group an okf registry link brought in — the link's own set, or one the
+      # linked file curates. Scopable and searchable like any other; writable by
+      # nobody here, since okf persists only the groups this registry owns.
+      def linked?
+        !@link.nil?
       end
 
       # A hand-edited registry can name a cycle, which okf reports by declining to
@@ -81,7 +97,7 @@ module OKF::TUI
     # its CLI passes a cwd and a library caller stays on the global registry. A
     # default here would make the registry an embedding app reads depend on the
     # directory its process happens to be in, and would let the suite discover a
-    # `.okf-registry.json` from wherever `rake` was run.
+    # `.okf.json` from wherever `rake` was run.
     #
     # +ref_slugs+ maps a resolved directory to the slug the @ref named it by, so a
     # session built from refs keeps the names the user typed. See Refs#slugs.
@@ -108,6 +124,15 @@ module OKF::TUI
       (registry || open_registry).path
     end
 
+    # The registry file a link points at — what a refusal has to name, since
+    # "edit it there" is useless without saying where there is. nil when nothing
+    # is linked under that name.
+    def link_target(name)
+      return nil unless registry_backed?
+
+      registry.links_listing.find { |row| row[:slug] == name }&.fetch(:registry)
+    end
+
     def empty?
       entries.empty?
     end
@@ -465,7 +490,7 @@ module OKF::TUI
     def registry_entries
       registry.listing.map do |row|
         build_entry(slug: row[:slug], dir: row[:dir], default: row[:default],
-          registered: true, missing: row[:missing])
+          registered: true, missing: row[:missing], link: row[:link])
       end
     end
 
@@ -482,7 +507,7 @@ module OKF::TUI
         end
 
         Group.new(slug: row[:slug], members: row[:members], bundles: bundles || [],
-          cyclic: bundles.nil?)
+          cyclic: bundles.nil?, link: row[:link])
       end
     end
 
@@ -508,8 +533,8 @@ module OKF::TUI
       end
     end
 
-    def build_entry(slug:, dir:, default:, registered:, missing:)
-      entry = Entry.new(slug: slug, dir: dir, default: default, registered: registered)
+    def build_entry(slug:, dir:, default:, registered:, missing:, link: nil)
+      entry = Entry.new(slug: slug, dir: dir, default: default, registered: registered, link: link)
 
       if missing
         entry.error = "directory is gone"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-tui
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.1
+        version: 2.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.1
+        version: 2.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'