@fluid-app/fluid-cli-genealogy 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @fluid-app/fluid-cli-genealogy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fluid CLI plugin for genealogy trees: parents, children, legs, placements and
+moves, over the company genealogy API (v2026-10).
+
+```bash
+npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-genealogy
+fluid login
+fluid genealogy trees
+fluid genealogy show --member <member-id>            # seat in the placement tree, with counts
+fluid genealogy ancestors <node> --as-of 2026-09-01T00:00:00Z
+fluid genealogy children <node> --limit 50           # prints next_cursor if more remain
+fluid genealogy grandchildren <node>
+fluid genealogy legs <node>                          # legs ranked by headcount
+fluid genealogy strong-leg <node>
+fluid genealogy tree <node> --depth 3                # indented text downline
+fluid genealogy move <node> --to <parent> --dry-run  # preview only
+fluid genealogy move <node> --to <parent> --yes
+```
+
+A node is a member's seat in one tree. Commands take a node UUID, or
+`--member <member-id>` with `--tree <key-or-id>` (default `placement`) to use
+that member's seat. A member with no seat, or several, in the tree is an error.
+
+Reads: `show`, `counts`, `parent`, `root`, `ancestors`, `sponsor`, `enroller`,
+`children`, `siblings`, `frontline`, `personally-enrolled`, `grandchildren`,
+`level --depth N`, `descendants --depth N`, `subtree --depth N`,
+`level-counts --depth N`, `relation <node> <other> [--kind]`, `placements`,
+`holding-tank`, `trees`. Deeper reads take depths 1-7. Lists follow every page;
+`--limit` caps the total and the output's `next_cursor` resumes with
+`--cursor`.
+
+Legs are measured by headcount only: each leg counts the child's seat plus its
+`downline_count`. The API has no leg volume. Counts include retained seats of
+discarded members. The API has no per-leg count endpoint, so `legs`,
+`strong-leg` and `weak-leg` read each direct child's counts with its own
+request. They refuse a node with more than 200 direct children; pass
+`--limit <n>` to count up to `n`. The children read leaves out a direct child
+whose member was discarded, while the node's own counts keep it. There is no
+single read of a node's children with their counts, so `legs` reads the node's
+counts, then the children and each child's counts twice, then the node's counts
+again, and uses them only when every read agrees; otherwise it reads again (up
+to three times). When the node has more children than were listed, the output
+carries `unlisted` (`children`, `seats`, `ranked`, `unknown_empty_legs`). A
+single unlisted child is ranked with its exact size and `unlisted: true`, in the
+named leg left free when there is only one. Empty named legs are not listed
+when they cannot be told from an unlisted child's leg. `strong-leg` and
+`weak-leg` name a leg only when the unlisted children cannot change it; a
+strong leg that has more seats than all of them together still holds.
+Otherwise they return `leg: null` with `best_listed`, the pick among the listed
+legs.
+
+Reads need a company admin with `members.view` (or the legacy `users.view`);
+a company API token (`C-...`) with that permission works too. Naming a tree
+by key, including the default `placement`, looks it up with
+`GET /api/company/v2026-10/genealogy/tree-keys`, which lists only each tree's
+id, key and name and needs the same `members.view`; without it, the key is
+looked up in the tree definitions, which need `developer.view`. An API
+without the `tree-keys` endpoint (it answers 404) falls back the same way. Only `fluid genealogy
+trees`, which prints the full tree definitions, needs `developer.view`, because
+those definitions carry company configuration. `legs` reads a tree's leg names
+from those definitions too: without `developer.view` it still ranks the
+occupied legs but cannot list empty named legs, so `weak-leg` returns
+`leg: null` with `best_listed` (an unseen empty leg may be the weak one) and
+the report carries `leg_names_known: false`.
+
+Writes: `place`, `move`, `move-requests approve|reject`. They need an admin
+user's login: run `fluid login` as a company admin with `members.manage` (for
+`place` and `move`) or `team_moves.approve` (for `move-requests
+approve|reject`). A company API token (`C-...`) is refused with 403 "A company
+admin identity is required ...". Writes change the live
+tree, so they ask for confirmation unless you pass `--yes`. `move --validate`
+(or `--dry-run`) previews without writing. `move-requests list|show` and
+`move-jobs list|show` read move receipts.
+
+Tree definitions: `trees create`, `trees update <tree>` and `trees delete
+<tree>` (a key or UUID) write the company's tree registry. They need an admin
+login with `developer.update` (a company API token works only if its role
+grants it). Every writable field is a flag: `--key`, `--name`, `--kind
+unilevel|binary|matrix`, `--role`, `--leg-names left,right`,
+`--placement-rule`, `--movement-approval immediate|require_approval`,
+`--holding-tank-days`, `--max-depth`, `--max-movement-levels`,
+`--movement-window-days`, `--volume-on-move`, `--volume-key`,
+`--allow-multiple-positions true|false`, `--authority
+authoritative|replica|unconfigured`, `--owning-company-integration-id`,
+`--upstream-tree-ref` and `--external-integration-market-id`; `none` clears a
+nullable field. Create needs `--key`, `--name`, `--kind` and `--authority`;
+binary and matrix trees also need `--volume-on-move`. Binary and matrix trees accept the default rules `exact`, `first_empty`,
+`left`, `right` and `defer`; unilevel trees `exact`, `under_enroller` and
+`mirror_enrollment` (other rules are refused with a typed error). `place
+--parent` with neither `--leg` nor `--rule` uses the tree's default rule. Only an authoritative
+tree takes placements, and placing in a binary or matrix tree also needs the
+company's `GENEALOGY_LEGGED_TREES` flag. Update sends only the flags given, at
+the tree's current `lock_version` unless `--lock-version` pins one; an
+occupied tree can only be renamed. Delete fails with `tree_has_nodes` while
+the tree holds any seat, and the default `enrollment` and `placement` trees
+can't be deleted. Each write shows the request and asks first unless `--yes`;
+`--dry-run` prints it and sends nothing.
+
+```bash
+fluid genealogy trees create --key team-binary --name "Team Binary" --kind binary \
+  --authority authoritative --volume-on-move follows_structure --dry-run
+fluid genealogy trees update team-binary --movement-approval require_approval --yes
+fluid genealogy trees delete team-binary --yes
+```
+
+`trees mirror [tree]` (default `placement`) backfills the placement tree
+from the enrollment tree for a company whose placement tree uses
+`mirror_enrollment` and has no legacy placement tree: every enrolled member
+without a placement seat is seated under their enroller's seat, roots
+first, and unpinned seats that no longer match are re-parented. Pinned
+seats stay. It is idempotent and needs an admin login with
+`members.manage`. Member writes keep the trees mirrored afterwards.
+
+`--dry-run` reports the counts at once and writes nothing (up to 5,000
+enrollment seats). A real run asks first unless `--yes`, then queues a
+background run with no seat limit and prints it (`mirror_run`, plus
+`started: false` when the company already had a run queued or running;
+there is one at a time). `--wait` follows the run, printing a progress line
+per reading on stderr (every `--interval` seconds, default 2), then prints
+the finished run and exits non-zero if it `failed` or `halted`. A halted
+run kept the batches it wrote; run the mirror again to finish.
+
+```bash
+fluid genealogy trees mirror --dry-run
+fluid genealogy trees mirror --yes --wait
+fluid genealogy trees mirror-runs list --status running
+fluid genealogy trees mirror-runs show <run-id>
+```
+
+Every command except `tree` prints JSON. Failures print a JSON `error` (with the
+API's `type` when there is one) on stderr and exit non-zero.

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+import { CommandContext, FluidPlugin } from "@fluid-app/fluid-cli";
+import { Command } from "commander";
+
+//#region src/index.d.ts
+/**
+ * Placements and moves change the live tree and need an explicit yes.
+ * Scripts and agents pass `--yes`; an interactive terminal is asked. With
+ * neither, nothing runs.
+ */
+declare function confirmChange(question: string, yes: boolean, interactive?: boolean): Promise<void>;
+declare function registerGenealogyCommands(parent: Command, ctx: CommandContext): void;
+declare const plugin: FluidPlugin;
+//#endregion
+export { confirmChange, plugin as default, registerGenealogyCommands };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAwEA;;;iBAAsB,aAAA,CACpB,QAAA,UACA,GAAA,WACA,WAAA,aACC,OAAA;AAAA,iBAyWa,yBAAA,CACd,MAAA,EAAQ,OAAA,EACR,GAAA,EAAK,cAAA;AAAA,cA+dD,MAAA,EAAQ,WAAA"}