okf 2.1.0 → 2.2.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[init set del list default rename group ungroup].freeze
+      SUBCOMMANDS = %w[init set del list default rename group ungroup link unlink import].freeze
 
       def self.id
         :registry
@@ -20,17 +20,29 @@ module OKF
         :registry
       end
 
+      # One subcommand per row — the table `okf registry --help` prints, and the
+      # single place each subcommand's grammar is written down.
+      SUBCOMMAND_ROWS = [
+        [ "init", "create a project-local .okf.json (nearest one wins)" ],
+        [ "list [--json]", "list registered bundles (* marks the default)" ],
+        [ "set <dir|@slug> [--as SLUG] [--default]", "add or update a bundle (a bare `server` serves them)" ],
+        [ "del <dir|@slug>", "remove a bundle or group from the registry" ],
+        [ "default <@slug>", "move a bundle to the front (the default)" ],
+        [ "rename <@slug> <new>", "rename a bundle or group (<new> is a new name, not a ref)" ],
+        [ "group <slug> <@member…>", "create a group, or add members (search/server can target @slug)" ],
+        [ "ungroup <slug> <@member…>", "remove members from a group (emptying it deletes it)" ],
+        [ "link <name> <file>", "point the global registry at another one (its bundles resolve here)" ],
+        [ "unlink <name>", "drop a link and every bundle that arrived through it" ],
+        [ "import <@slug…> [--from FILE]", "copy bundles out of another registry (global by default) into this one" ]
+      ].freeze
+
+      # The umbrella is one row in `okf help`. Ten made a third of the map about
+      # registry management, which is not a third of what okf does — and the map's
+      # job is to name the verbs, not to be every verb's manual. The subcommands
+      # are one `--help` away, and the row says so rather than leaving a reader to
+      # guess that an umbrella has any.
       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 or group from the registry" ],
-          [ "registry  default <@slug>", "move a bundle to the front (the default)" ],
-          [ "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)" ]
-        ]
+        [ [ "registry  <command> [-g]", "name, group and link your bundles (okf registry --help)" ] ]
       end
 
       def call(argv)
@@ -38,6 +50,7 @@ module OKF
 
         sub = argv.first
         case sub
+        when "--help", "-h" then umbrella_help
         when "init" then registry_init(argv.drop(1))
         when "set" then registry_set(argv.drop(1))
         when "del" then registry_del(argv.drop(1))
@@ -46,6 +59,9 @@ module OKF
         when "rename" then registry_rename(argv.drop(1))
         when "group" then registry_group(argv.drop(1))
         when "ungroup" then registry_ungroup(argv.drop(1))
+        when "link" then registry_link(argv.drop(1))
+        when "unlink" then registry_unlink(argv.drop(1))
+        when "import" then registry_import(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).
@@ -67,7 +83,32 @@ module OKF
 
       private
 
-      # Create a project-local .okf-registry.json in the current directory. Once it
+      # The umbrella's own help: every subcommand, its grammar, and the one flag
+      # they share. A bare `okf registry` is still `registry list` — the shorthand
+      # is documented and predates this — so only an explicit --help lands here.
+      def umbrella_help
+        width = SUBCOMMAND_ROWS.map { |usage, _| usage.length }.max
+        @out.puts "Usage: okf registry <command> [options]"
+        @out.puts ""
+        SUBCOMMAND_ROWS.each { |usage, blurb| @out.puts "  #{usage.ljust(width)}  #{blurb}" }
+        @out.puts ""
+        @out.puts "  -g, --global   act on the global $OKF_HOME registry, ignoring a project-local one"
+        @out.puts "                 (every command but `init`; OKF_NO_DISCOVERY=1 does it for a whole shell)"
+        @out.puts ""
+        @out.puts "A bare `okf registry` lists them, the same as `okf registry list`."
+        @out.puts "`okf registry <command> --help` has that command's own flags."
+        0
+      end
+
+      # `-g/--global` on every subcommand but `init`, whose whole job is to create
+      # a *local* file. One options hash per verb carries it to #open_registry.
+      def global_flag(parser, options)
+        parser.on("-g", "--global", "act on the global $OKF_HOME registry, ignoring a project-local one") do
+          options[:global] = true
+        end
+      end
+
+      # Create a project-local .okf.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
@@ -81,8 +122,11 @@ module OKF
         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)
+        # Either name is "already initialized": the legacy one is still
+        # discovered, so writing a second registry beside it would shadow a file
+        # the user still thinks is in force — the trap, not the fix.
+        existing = OKF::Registry::LOCAL_FILES.find { |name| File.exist?(File.join(Dir.pwd, name)) }
+        return usage_error("already initialized: ./#{existing}") if existing
 
         # The parent it would shadow, if any — a courtesy, not a barrier: nested
         # registries resolve nearest-first, so creating one here is legitimate.
@@ -90,7 +134,7 @@ module OKF
         @err.puts "note: a parent registry at #{parent} — the nearest one wins" if parent
 
         OKF::Registry.new(target).save
-        @out.puts "initialized #{display}"
+        @out.puts "initialized ./#{OKF::Registry::LOCAL_FILE}"
         0
       rescue OptionParser::ParseError => e
         @err.puts e.message
@@ -104,11 +148,12 @@ module OKF
       # path already registered refreshes its title in place, and --as renames it. A
       # new path is added, slugged by directory basename unless --as says otherwise.
       def registry_set(argv)
-        options = { as: nil, default: false }
+        options = { as: nil, default: false, global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry set <dir|@slug> [--as SLUG] [--default]"
+          o.banner = "Usage: okf registry set <dir|@slug> [--as SLUG] [--default] [-g]"
           o.on("--as SLUG", "slug to register under (default: directory basename)") { |v| options[:as] = v }
           o.on("--default", "put it first — the bundle a bare `okf server` opens") { options[:default] = true }
+          global_flag(o, options)
           help_flag(o)
         end
         # No no_extras? here: positional_dir has already refused a trailing
@@ -116,7 +161,7 @@ module OKF
         # positional through `positional`, which does not check.
         dir = positional_dir(parser, argv) or return 2
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         # 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) }
@@ -135,14 +180,16 @@ module OKF
 
       # Remove a bundle from the persistent registry by slug or by its directory.
       def registry_del(argv)
+        options = { global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry del <dir|@slug>"
+          o.banner = "Usage: okf registry del <dir|@slug> [-g]"
+          global_flag(o, options)
           help_flag(o)
         end
         slug = positional(parser, argv) or return 2
         no_extras?(argv) or return 2
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         slug = registry_slug(slug, reg) or return 2
         removed = reg.remove(slug)
         return usage_error("no such bundle: #{slug}") unless removed
@@ -154,11 +201,12 @@ module OKF
       end
 
       def registry_list(argv)
-        options = { json: false }
+        options = { json: false, global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry list [--json] [--pretty]\n       " \
+          o.banner = "Usage: okf registry list [--json] [--pretty] [-g]\n       " \
                      "okf registry set <dir|@slug> | del <dir|@slug> | default <@slug> | rename <@slug> <new>"
           json_flags(o, options, "emit the registry as JSON")
+          global_flag(o, options)
           help_flag(o)
         end
         begin
@@ -169,13 +217,14 @@ module OKF
         end
         no_extras?(argv) or return 2
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         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)
+          extra = { "groups" => reg.groups_listing.map { |row| stringify(row) },
+                    "links" => reg.links_listing.map { |row| stringify(row) } }
+          return emit_list_json({ "registry" => reg.path }, "bundles", reg.listing.map { |row| stringify(row) }, options, extra)
         end
 
-        print_registry(reg)
+        print_registry(reg, global: options[:global])
         0
       rescue OKF::Error => e
         usage_error(e.message)
@@ -186,15 +235,17 @@ module OKF
       # meant to be hand-editable, so the move is stated rather than left to be
       # discovered from a reordered file.
       def registry_default(argv)
+        options = { global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry default <@slug>\n       " \
+          o.banner = "Usage: okf registry default <@slug> [-g]\n       " \
                      "moves it to the front — the first registered bundle is the default until you do"
+          global_flag(o, options)
           help_flag(o)
         end
         slug = positional(parser, argv) or return 2
         no_extras?(argv) or return 2
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         slug = registry_slug(slug, reg) or return 2
         reg.default = slug
         @out.puts "default bundle → #{reg.default.slug} (now first)"
@@ -225,8 +276,10 @@ module OKF
 
       # Rename a registered bundle's slug — its mount path and switcher name.
       def registry_rename(argv)
+        options = { global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry rename <@slug> <new>"
+          o.banner = "Usage: okf registry rename <@slug> <new> [-g]"
+          global_flag(o, options)
           help_flag(o)
         end
         parser.parse!(argv)
@@ -237,7 +290,7 @@ module OKF
         end
         no_extras?(argv) or return 2
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         # 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)
@@ -256,8 +309,10 @@ module OKF
       # 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)
+        options = { global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry group <slug> <@member…>"
+          o.banner = "Usage: okf registry group <slug> <@member…> [-g]"
+          global_flag(o, options)
           help_flag(o)
         end
         parser.parse!(argv)
@@ -267,7 +322,7 @@ module OKF
           return 2
         end
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         group = reg.set_group(slug, argv)
         count = reg.expand(group.slug).size
         @out.puts "grouped #{group.slug} → #{group.members.map { |m| "@#{m}" }.join(", ")} " \
@@ -283,8 +338,10 @@ module OKF
       # 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)
+        options = { global: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf registry ungroup <slug> <@member…>"
+          o.banner = "Usage: okf registry ungroup <slug> <@member…> [-g]"
+          global_flag(o, options)
           help_flag(o)
         end
         parser.parse!(argv)
@@ -294,7 +351,7 @@ module OKF
           return 2
         end
 
-        reg = open_registry
+        reg = open_registry(global: options[:global])
         removed, emptied = reg.unset_group_members(slug, argv)
         name = OKF::Registry.normalize(slug)
         if emptied
@@ -312,39 +369,241 @@ module OKF
         usage_error(e.message)
       end
 
-      def print_registry(reg)
+      # Point the global registry at another registry file. Refused from a
+      # project-local one rather than silently retargeting: `link` writes, and a
+      # write that lands in a file the user is not standing in is the one surprise
+      # worth an error. -g is the way to say it on purpose.
+      def registry_link(argv)
+        options = { global: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry link <name> <file> [-g]"
+          global_flag(o, options)
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        name, file = argv.shift(2)
+        if name.nil? || file.nil?
+          @err.puts parser.banner
+          return 2
+        end
+        no_extras?(argv) or return 2
+
+        reg = open_registry(global: options[:global])
+        return links_are_global(reg) if local_registry?(reg)
+
+        link = reg.link(name, file)
+        count = reg.links_listing.find { |row| row[:slug] == link.slug }[:bundles]
+        @out.puts "linked #{link.slug} → #{link.registry} (#{count} #{pluralize(count, "bundle")})"
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # Drop a link and every bundle that arrived through it. The bundles
+      # themselves are untouched — a link never owned them.
+      def registry_unlink(argv)
+        options = { global: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry unlink <name> [-g]"
+          global_flag(o, options)
+          help_flag(o)
+        end
+        name = positional(parser, argv) or return 2
+        no_extras?(argv) or return 2
+
+        reg = open_registry(global: options[:global])
+        return links_are_global(reg) if local_registry?(reg)
+
+        removed = reg.unlink(name)
+        return usage_error("no such link: #{name}") unless removed
+
+        @out.puts "unlinked #{removed.slug}"
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # Copy chosen bundles — and the groups that hold them — out of another
+      # registry file into the one in force. The counterpart to `link`, not a
+      # variant of it: a link is live, whole-file and read-only, and an import
+      # copies the reference and hands over ownership.
+      #
+      # Two registries are named here, and only one flag names each. `-g` goes on
+      # meaning what it means on every sibling subcommand — the registry written
+      # *to* — and `--from` names the one read, defaulting to the global registry,
+      # which inside a repo is the only other one there is. Overloading `-g` into
+      # a source flag on this verb alone would make it mean "write here" nine
+      # times and "read there" once.
+      def registry_import(argv)
+        options = { from: nil, as: nil, global: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry import <@slug…> [--from FILE] [--as SLUG] [-g]"
+          o.on("--from FILE", "registry file to copy from (default: the global $OKF_HOME one)") do |v|
+            options[:from] = v
+          end
+          o.on("--as SLUG", "slug to import under, renaming one bundle or group") { |v| options[:as] = v }
+          global_flag(o, options)
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        if argv.empty?
+          @err.puts parser.banner
+          return 2
+        end
+        # --as names *one* thing. Applying it to a list would either rename them
+        # all to the same slug (a collision the user did not ask for) or pick one
+        # silently, and there is no reading of "import a b --as c" worth guessing.
+        return usage_error("--as names one bundle or group, and #{argv.length} were asked for") if options[:as] && argv.length > 1
+
+        # Expanded for the report as `link` expands its target: a relative --from
+        # is the shorthand, and the file it actually read is the answer.
+        from = OKF::Registry.expand(options[:from] || OKF::Registry.path)
+        reg = open_registry(global: options[:global])
+        print_imported(reg.import(argv, from: from, as: options[:as]), from)
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # What landed: a count against the file it came from, then a row per bundle
+      # in `set`'s shape (with its concept count, the signal that says whether it
+      # was the right bundle), then a row per group. Groups print after the
+      # bundles they hold, which is the order they were planned in.
+      def print_imported(imported, from)
+        bundles = imported[:bundles]
+        @out.puts "imported #{bundles.length} #{pluralize(bundles.length, "bundle")} from #{from}"
+        bundles.each do |entry|
+          folder = OKF::Bundle::Folder.load(entry.path)
+          report_skipped(folder)
+          count = folder.graph(minimal: true).nodes.size
+          @out.puts "  #{entry.slug} → #{entry.path} (#{count} #{pluralize(count, "concept")})"
+        end
+        imported[:groups].each do |group|
+          @out.puts "  #{group.slug} → #{group.members.map { |member| "@#{member}" }.join(", ")} (group)"
+        end
+      end
+
+      # The one refusal both link verbs share: a project-local registry is in
+      # force, and links are the global one's alone — which is what keeps a linked
+      # file's own links unread, and so keeps depth at one with nothing to enforce.
+      def links_are_global(reg)
+        usage_error("links live in the global registry, and #{registry_display(reg)} is a project-local one " \
+                    "(okf registry link … --global)")
+      end
+
+      def print_registry(reg, global: false)
         # 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)
+        # Named whenever the answer could have been the other file: a discovered
+        # local registry, or a -g that just overrode one. The bare global case
+        # stays headerless — nothing was chosen, so there is nothing to disclose.
+        @out.puts "registry: #{registry_display(reg)}" if local_registry?(reg) || global
+        # groups_listing carries the linked groups too; here they print under
+        # their link rather than among the ones `group`/`ungroup` can touch.
         groups = reg.groups_listing
-        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty? && groups.empty?
+        own, linked = groups.partition { |group| group[:link].nil? }
+        links = reg.links_listing
+        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty? && groups.empty? && links.empty?
 
         rows = reg.listing
-        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}"
+        width = width_of(rows)
+        rows.reject { |row| row[:link] }.each { |row| @out.puts bundle_row(row, width) }
+        print_groups(own, rows) unless own.empty?
+        print_links(links, linked, rows, width) unless links.empty?
+      end
+
+      # Why a link contributed nothing, when it did: a target that is gone, or one
+      # that is there and cannot be parsed. Both are reported, never raised.
+      def link_state(link)
+        return "  (missing)" if link[:missing]
+        return "  (unreadable)" if link[:unreadable]
+
+        ""
+      end
+
+      def width_of(rows)
+        rows.empty? ? 0 : rows.map { |row| row[:slug].length }.max
+      end
+
+      def bundle_row(row, width)
+        marker = row[:default] ? "*" : " "
+        missing = row[:missing] ? "  (missing)" : ""
+        # The slug it *had* in the file it came from, shown only when this
+        # registry had to move it — the one place a ref that shifted is visible.
+        moved = row[:origin] && row[:origin] != row[:slug] ? "  [#{row[:origin]}]" : ""
+        "#{marker} #{row[:slug].ljust(width)}  #{row[:title]}  (#{row[:dir]})#{missing}#{moved}"
+      end
+
+      # The links section: one heading per link naming the file it points at, then
+      # the bundles that arrived through it, then any groups that came with them. A
+      # target that is gone or unreadable says so instead of listing nothing.
+      def print_links(links, groups, rows, width)
+        @out.puts ""
+        @out.puts "links:"
+        links.each do |link|
+          state = link_state(link)
+          @out.puts "  #{link[:slug]}  → #{link[:registry]}  " \
+                    "(#{link[:bundles]} #{pluralize(link[:bundles], "bundle")})#{state}"
+          rows.select { |row| row[:link] == link[:slug] }.each { |row| @out.puts "  #{bundle_row(row, width)}" }
+          groups.select { |group| group[:link] == link[:slug] && group[:slug] != link[:slug] }.each do |group|
+            @out.puts "    #{group[:slug]}  #{group[:members].map { |m| "@#{m}" }.join(", ")}"
           end
         end
-        print_groups(groups, rows) unless groups.empty?
+      end
+
+      # Every registry read this verb makes, with the filename note attached. The
+      # note is the `registry` umbrella's alone: this is the one verb whose
+      # *subject* is a registry file, and the one nobody runs in a loop or pipes
+      # into something else. `lint` and `search` are both, and a note there is
+      # noise people learn to redirect away rather than act on.
+      #
+      # Once per invocation, not once per read — `registry set @slug` opens the
+      # registry twice (the ref, then the write), and saying it twice reads as
+      # two problems.
+      def open_registry(global: false)
+        reg = super
+        note_legacy_name(reg) unless @named_registry
+        @named_registry = true
+        reg
+      end
+
+      # Two things worth saying about a project-local registry's filename, and
+      # nothing at all about the global one (which is `registry.json` and always
+      # was). A legacy file that is *in force* gets the move that retires it. A
+      # legacy file sitting beside the `.okf.json` that beat it gets named too:
+      # reading one while the other lies there unread is a silent wrong answer
+      # unless somebody says so.
+      def note_legacy_name(reg)
+        return unless local_registry?(reg)
+
+        legacy = OKF::Registry::LEGACY_LOCAL_FILE
+        if File.basename(reg.path) == legacy
+          @err.puts "note: #{legacy} is the old name — git mv #{legacy} #{OKF::Registry::LOCAL_FILE}"
+        elsif File.file?(File.join(File.dirname(reg.path), legacy))
+          @err.puts "note: #{legacy} is ignored — #{OKF::Registry::LOCAL_FILE} beside it wins (delete the old one)"
+        end
       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).
+      # .okf.json, or the legacy .okf-registry.json).
       def local_registry?(reg)
-        File.basename(reg.path) == OKF::Registry::LOCAL_FILE
+        OKF::Registry::LOCAL_FILES.include?(File.basename(reg.path))
       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
+        File.dirname(reg.path) == Dir.pwd ? "./#{File.basename(reg.path)}" : reg.path
       end
 
       # The groups section under the bundle listing: one row per group, its members

data/lib/okf/cli.rb

@@ -45,7 +45,7 @@ module OKF
       "references" => %w[path dir kind referenced_by],
       "directories" => %w[dir ancestor index_path present synthesized count types tags subdirs body listing],
       "dirs" => %w[dir ancestor count subtree subdirs],
-      "bundles" => %w[slug title dir mount default missing]
+      "bundles" => %w[slug title dir mount default missing link origin]
     }.freeze
 
     # Runs a Rack app under WEBrick until interrupted. Injected into the CLI so