okf 2.1.1 → 2.2.0

data/lib/okf/server/hub.rb

@@ -507,11 +507,15 @@ module OKF
       # than by slug: a rename in the file changes the slug and nothing else,
       # and a row that lost its identity over a rename is the bug this avoids.
       def manager_rows
-        return @bundles.map { |bundle| hosted_row(bundle, bundle.slug) } if registry.nil?
+        return @bundles.map { |bundle| hosted_row(bundle, bundle.slug).merge(link: nil) } if registry.nil?
 
         registry.listing.map do |entry|
           hosted = @bundles.find { |bundle| bundle.folder.root == entry[:dir] }
-          hosted ? hosted_row(hosted, entry[:slug], entry[:dir]) : unhosted_row(entry)
+          row = hosted ? hosted_row(hosted, entry[:slug], entry[:dir]) : unhosted_row(entry)
+          # A bundle that arrived through a link is read-only here, and the page
+          # has to know: the registry refuses every write against one, so a row
+          # offering the menu would offer three actions that can only fail.
+          row.merge(link: entry[:link])
         end
       end
 

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

@@ -2,7 +2,9 @@
 
 Kind: reference. Answers: which file a registry op writes and how okf finds it,
 which verbs key on a path and which on a slug, what a group is and which two
-verbs consume one, and why the default is a position rather than a stored slug.
+verbs consume one, why the default is a position rather than a stored slug, and
+what a link brings in from another registry file — against what an import copies
+out of one.
 
 The *persistent registry* is a plain JSON file under `$OKF_HOME` (default
 `~/.okf`), managed by the `okf registry` umbrella — like git's `remote` family,
@@ -11,18 +13,28 @@ and split by what each verb keys on. It is what every `@slug` resolves through
 ([serve.md](serve.md)).
 
 **`okf registry init`** creates a *project-local* registry instead: a
-`.okf-registry.json` in the current directory, which okf discovers by walking up
+`.okf.json` in the current directory, which okf discovers by walking up
 from the working directory and uses in place of the global one while you are
 inside its tree (the nearest wins, so nested registries resolve nearest-first).
 Every registry op — and every `@slug` — then resolves through it, so a bare
 `okf server` inside a repo serves that repo's bundles with no `$OKF_HOME` setup;
 `okf registry list` names the local file it found. `OKF_NO_DISCOVERY=1` forces
-the global registry — the escape hatch for a fixed-cwd caller (CI, a tool). A
+the global registry — the escape hatch for a fixed-cwd caller (CI, a tool) — and
+**`-g`/`--global` says the same thing for one command**, on every subcommand but
+`init` (whose whole job is to create a local file). So `okf registry list -g`
+reads the global registry from inside a repo, and `okf registry set <dir> -g`
+registers there without leaving. `list` names the file it read whenever either
+lever is in play, so which registry answered is never a guess. A
 local registry stores **portable** paths: a bundle inside its tree is written
-relative to the `.okf-registry.json`, so committing the file lets it travel with
+relative to the `.okf.json`, so committing the file lets it travel with
 the repo (a checkout elsewhere, a container mounting it) and resolve unchanged;
 a bundle outside the tree stays absolute, since it cannot travel. Paths still read
 back absolute wherever the CLI reports them.
+The file okf writes is `.okf.json`; the older `.okf-registry.json` is still
+discovered, both names checked in each directory on the way up so "nearest wins"
+keeps its shape, and `okf registry` — that verb alone, never `lint` or `search` —
+notes the old name once so it can be retired with a `git mv`.
+
 **Entry verbs** take a path: `okf registry set <dir>` adds it
 (slug from the basename, or `--as`, which errors on a collision; `--default`
 puts it first), and because the entry is keyed by path, `set` on an
@@ -61,10 +73,41 @@ and `okf server` consume**: every single-bundle verb (`lint`, `index`, …) refu
 a `@group` with exit 2, the same rule that refuses a second bundle. `@all` is
 unchanged — it still names every registered *bundle*, groups being named subsets
 of that.
+**Link verbs** point the *global* registry at another registry file, so its
+bundles resolve here without being copied. `okf registry link <name> <file>`
+adds the pointer (the target must exist); its bundles then answer to their own
+slugs, or to `<name>-<slug>` when a name is already taken here, and `@<name>`
+resolves as a group over them. Nothing is written but the pointer — the target
+keeps owning its rows, so an edit there shows here on the next read, and every
+write aimed at a linked bundle (`rename`, `del`, `default`, `set --as`, `group`)
+is refused naming the file that does own it. `okf registry unlink <name>` drops
+the pointer and its bundles. Links are the **global** registry's alone: a
+project-local one parses them and does not resolve them, which is why a linked
+file's own links are never followed and there is no chain to cycle. A target
+that is gone or unparseable is listed `(missing)`/`(unreadable)` and resolves to
+nothing — one dead pointer never takes down the registry holding it.
+<!-- rule:okf-registry-links-global-only -->
+**`okf registry import <@slug…>`** is the opposite trade: it *copies* chosen rows
+out of another registry file into the one in force, and they become yours —
+editable, renameable, groupable, and untouched when the source changes. The
+source is `--from FILE`, defaulting to the global registry, because `-g` goes on
+meaning the registry written *to*. A group ask brings its members, and any group
+nested inside it, recreated under the same names. Slugs are preserved, so a
+collision **refuses** rather than being minted around the way a link's is — you
+typed this name, and the gem may not substitute one you chose (`--as` renames a
+single ask). A bundle already registered here under another name refuses first.
+Every ask is checked before anything is written, so an import either lands whole
+or leaves the file byte-for-byte alone.
+<!-- rule:okf-registry-import-all-or-nothing -->
 `okf registry list` (or a bare
 `okf registry`) stars the default and flags vanished dirs `(missing)` — the
 server skips those with a note — and lists any groups with their members and
 resolved leaf count; `--json` answers
 `{ registry: <file>, count, bundles: [{ slug, title, dir, mount, default,
-missing }], groups: [{ slug, members, resolved }] }`, naming the file it read so a
-`$OKF_HOME` mismatch is visible.
+missing, link, origin }], groups: [{ slug, members, resolved, link }], links:
+[{ slug, registry, bundles, missing, unreadable }] }`, naming the file it read so a
+`$OKF_HOME` mismatch is visible. On a bundle row `link` names the link it arrived
+through (null when the registry owns it) and `origin` the slug it carries in that
+file — the two differ only where a collision moved the name. `groups` lists both
+kinds, own first, each carrying the same `link` key, since a linked group
+resolves as a ref like any other.

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

@@ -20,7 +20,7 @@ when it has one.
 | [cli/map.md](cli/map.md) | `index` `dirs` | orientation: the §8 directory map and the cluster sizes, how `--dir`/`--depth`/ancestors compose, what a synthesized listing means, how not to page the bundle |
 | [cli/views.md](cli/views.md) | `catalog` `files` `tags` `types` `stats` | the browser panels as text — per-concept metadata, the folder tree, tag and type rollups, bundle totals, and the JSON each emits |
 | [cli/serve.md](cli/serve.md) | `server` `render` | the interactive page and its static twin — what renders, what is fetched live, many bundles behind one hub, the trust boundary both share |
-| [cli/registry.md](cli/registry.md) | `registry` (`init` `set` `del` `default` `rename` `group` `ungroup` `list`) | naming bundles once: which file is written and how it is found, path-keyed vs slug-keyed verbs, groups, why the default is a position |
+| [cli/registry.md](cli/registry.md) | `registry` (`init` `set` `del` `default` `rename` `group` `ungroup` `link` `unlink` `list`) | naming bundles once: which file is written and how it is found, path-keyed vs slug-keyed verbs, groups, why the default is a position |
 | [cli/graph.md](cli/graph.md) | `graph` | the raw node/edge dump and what it costs, plus the two rankings [refine](../playbooks/refine.md) reads — `--hubs` by concept, `--traffic` by directory |
 
 A question that ends in *what does the spec actually say* leaves the CLI

data/lib/okf/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura