gisool 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 changeroa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# gisool
 
-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.
+gisool is a local skill router. One daemon on `127.0.0.1` indexes the `SKILL.md` folders already on your machine,
+serves them to your coding agents over MCP (`search_skills`, `load_skill`, `read_skill_file`), records which skills
+each agent session searched, loaded, and read, and shows that history in a local dashboard.
+
+Supported runtimes: Claude Code, Codex, Gemini CLI, Cursor, OmO, Gajae Code, and OpenClaw.
+
+**Privacy: everything stays on this machine.** The daemon listens on `127.0.0.1` only, every MCP, ingest, and API
+request needs the local bearer token, and nothing is sent to any remote service. Prompts, search queries, and skill
+usage are stored in a SQLite database under `~/.gisool/`.
+
+## Install
+
+Requires Node.js 24.15 or newer on macOS or Linux.
+
+```sh
+npm --prefix local ci && npm --prefix local run build && npm link ./local
+```
+
+This puts the `gisool` command on your `PATH`.
+
+## Connect your agents
+
+Preview what would change, without writing anything:
+
+```sh
+gisool init --dry-run
+```
+
+The dry run prints a diff for every runtime config gisool would touch (MCP registration, OpenTelemetry export to the
+daemon, capture hooks) and the service it would install. Then apply it:
+
+```sh
+gisool init                          # every detected runtime
+gisool init --runtime codex,claude-code
+gisool init --disable-remote         # also turn off a remote gisul registration
+gisool init --no-service             # do not install the LaunchAgent / systemd user unit
+```
+
+Every run backs up the files it changes under `~/.gisool/backups/`. Undo with:
+
+```sh
+gisool init --rollback               # newest run
+gisool init --rollback --all         # every run
+```
+
+## Run
+
+`gisool init` installs a LaunchAgent (macOS) or systemd user unit (Linux) that keeps the daemon running. To run it in
+the foreground instead:
+
+```sh
+gisool serve                         # default port 8799
+gisool serve --port 8800
+```
+
+Open the dashboard (sessions, per-session trace, flow, and weekday-by-hour heatmap):
+
+```sh
+gisool open                          # opens the browser
+gisool open --print                  # prints the URL only
+```
+
+Check the installation:
+
+```sh
+gisool doctor                        # service, daemon, token mode, FTS5, roots, index freshness, hooks, backups
+gisool doctor --json
+```
+
+Measure search quality against recorded or hand-written cases:
+
+```sh
+gisool eval
+gisool eval --cases cases.json --json
+```
+
+## Export and import
+
+Move your gisool setup (skill roots, config, eval cases, aliases) to another machine:
+
+```sh
+gisool export ~/gisool-backup                  # settings only
+gisool export ~/gisool-backup --with-history   # also sessions, events, and loads
+gisool import ~/gisool-backup --dry-run        # preview what would be added
+gisool import ~/gisool-backup                  # merge; existing keys are kept
+```
+
+Import never overwrites existing settings. Run `gisool init` afterwards to connect the runtimes on the new machine.
+
+## Settings
+
+`~/.gisool/config.json` (created on first run, mode 0600; `GISOOL_HOME` moves the whole directory):
+
+```json
+{
+  "port": 8799,
+  "captureLevel": "full",
+  "retentionDays": null,
+  "roots": [{ "id": "agents", "path": "~/.agents/skills" }],
+  "runtimes": {}
+}
+```
+
+- `captureLevel` controls how prompt and search text is stored:
+  - `full` (default): the text as sent.
+  - `redacted`: secrets (tokens, keys, passwords) are masked and the text is cut to 2048 characters.
+  - `metadata`: no text at all, only its SHA-256 digest and length. The dashboard shows "prompt not captured".
+- `retentionDays`: `null` keeps history forever; a number deletes sessions older than that many days at startup and
+  once a day.
+- `roots`: skill folders to index in place. Defaults cover `~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`,
+  `~/.gemini/skills`, `~/.omo/agent/skills`, `~/.gjc/agent/skills`, `~/.openclaw/skills`, and `~/gisul/skills`.
+  gisool never copies or edits skill files.
+
+Restart the daemon after editing the config.
+
+## Files
+
+| Path | Purpose |
+| --- | --- |
+| `~/.gisool/config.json` | settings above |
+| `~/.gisool/token` | bearer token (0600) shared with the runtime configs |
+| `~/.gisool/gisool.db` | SQLite store: skills index, sessions, events, loads |
+| `~/.gisool/logs/daemon.log` | daemon log, rotated at 5 MB |
+| `~/.gisool/backups/` | per-run backups used by `gisool init --rollback` |
+
+## Develop
+
+```sh
+npm --prefix local run build
+npm --prefix local run typecheck
+npm --prefix local test              # unit tests plus test/e2e, which spawns the real daemon in a sandbox HOME
+node local/bench/search.mjs --check
+```
+
+Architecture: [docs/gisool.md](../docs/gisool.md).

package/dist/api/routes.js

@@ -0,0 +1,166 @@
+import { ingestHook, ingestOtlp } from "../ingest/pipeline.js";
+import { isRuntimeId, RUNTIME_IDS } from "../ingest/runtimes.js";
+import { deny } from "./security.js";
+const STATES = ["loaded", "exposed_only", "no_match", "aborted", "not_used"];
+const CLIENT_ERROR_CODES = new Set(["invalid_tz", "bad_filter", "bad_request"]);
+class BadRequest extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function one(value) {
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value))
+        return value.map(String).join(",");
+    return String(value);
+}
+function intParam(q, key, range) {
+    const raw = one(q[key]);
+    if (raw === undefined || raw === "")
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || (range && (n < range[0] || n > range[1])))
+        throw new BadRequest("bad_filter", `${key} must be an integer${range ? ` in ${range[0]}..${range[1]}` : ""}`);
+    return n;
+}
+function listParam(q, key, allowed) {
+    const raw = one(q[key]);
+    if (raw === undefined || raw === "")
+        return undefined;
+    const items = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    if (allowed)
+        for (const item of items)
+            if (!allowed.includes(item))
+                throw new BadRequest("bad_filter", `unknown ${key} value: ${item}`);
+    return items;
+}
+export function parseFilter(q) {
+    const f = {};
+    const from = intParam(q, "from");
+    const to = intParam(q, "to");
+    const runtime = listParam(q, "runtime", RUNTIME_IDS);
+    const skill = listParam(q, "skill");
+    const state = listParam(q, "state", STATES);
+    const dow = intParam(q, "dow", [0, 6]);
+    const hour = intParam(q, "hour", [0, 23]);
+    const hourSpan = intParam(q, "hourSpan", [1, 24]);
+    const text = one(q.q)?.trim();
+    const tz = one(q.tz);
+    if (from !== undefined)
+        f.from = from;
+    if (to !== undefined)
+        f.to = to;
+    if (runtime)
+        f.runtime = runtime;
+    if (skill)
+        f.skill = skill;
+    if (state)
+        f.state = state;
+    if (dow !== undefined)
+        f.dow = dow;
+    if (hour !== undefined)
+        f.hour = hour;
+    if (hourSpan !== undefined)
+        f.hourSpan = hourSpan;
+    if (text)
+        f.q = text;
+    if (tz)
+        f.tz = tz;
+    return f;
+}
+function defaultTz() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+function handle(log, fn) {
+    return (req, res) => {
+        try {
+            fn(req, res);
+        }
+        catch (error) {
+            const code = error.code;
+            if (error instanceof BadRequest || (typeof code === "string" && CLIENT_ERROR_CODES.has(code))) {
+                return deny(res, 400, String(code), { message: error.message });
+            }
+            log(`${req.method} ${req.path} failed: ${error.stack ?? String(error)}`);
+            deny(res, 500, "internal_error");
+        }
+    };
+}
+export function registerRoutes(app, deps) {
+    const { store, catalog, log } = deps;
+    app.get("/healthz", (_req, res) => {
+        res.json({ ok: true, version: deps.version, name: "gisool" });
+    });
+    app.post("/ingest/otlp/v1/logs", (req, res) => {
+        const body = req.body;
+        res.status(202).json({ partialSuccess: {} });
+        queueMicrotask(() => {
+            const result = ingestOtlp(body, deps.ingest);
+            if (result.status !== 200)
+                log(`otlp batch rejected: ${result.body.code}: ${result.body.message}`);
+        });
+    });
+    app.post("/ingest/hook/:runtime", (req, res) => {
+        const runtime = String(req.params.runtime);
+        if (!isRuntimeId(runtime)) {
+            store.countIngest("rejected", "unknown_runtime");
+            return deny(res, 400, "unknown_runtime");
+        }
+        const body = req.body;
+        res.status(202).json({ accepted: true });
+        queueMicrotask(() => {
+            ingestHook(runtime, body, deps.ingest);
+        });
+    });
+    app.get("/api/sessions", handle(log, (req, res) => {
+        res.json(store.sessions(parseFilter(req.query)));
+    }));
+    app.get("/api/sessions/:id/trace", handle(log, (req, res) => {
+        res.json(store.trace(String(req.params.id)));
+    }));
+    app.get("/api/flow", handle(log, (req, res) => {
+        const unit = one(req.query.unit) ?? "first_load";
+        if (unit !== "first_load" && unit !== "all_loads")
+            throw new BadRequest("bad_request", "unit must be first_load or all_loads");
+        const top = Math.min(15, intParam(req.query, "top", [1, 1000]) ?? 7);
+        res.json(store.flow(parseFilter(req.query), unit, top));
+    }));
+    app.get("/api/heatmap", handle(log, (req, res) => {
+        const filter = parseFilter(req.query);
+        const tz = filter.tz ?? defaultTz();
+        const weekStart = intParam(req.query, "weekStart", [0, 1]) ?? 1;
+        const bucket = intParam(req.query, "bucket") ?? 1;
+        if (bucket !== 1 && bucket !== 2 && bucket !== 4)
+            throw new BadRequest("bad_request", "bucket must be 1, 2, or 4");
+        res.json(store.heatmap(filter, tz, weekStart, bucket));
+    }));
+    app.get("/api/skill-week", handle(log, (req, res) => {
+        res.json(store.skillWeek(parseFilter(req.query)));
+    }));
+    app.get("/api/stats", handle(log, (req, res) => {
+        res.json(store.stats(parseFilter(req.query)));
+    }));
+    app.get("/api/skills", handle(log, (_req, res) => {
+        res.json(catalog.list());
+    }));
+    app.post("/api/eval-cases", handle(log, (req, res) => {
+        const body = (req.body ?? {});
+        const query = typeof body.query === "string" ? body.query.trim() : "";
+        if (!query)
+            throw new BadRequest("bad_request", "query is required");
+        for (const key of ["expectedUri", "fromTraceId"]) {
+            if (body[key] !== undefined && typeof body[key] !== "string")
+                throw new BadRequest("bad_request", `${key} must be a string`);
+        }
+        store.addEvalCase({
+            query,
+            ...(typeof body.expectedUri === "string" ? { expectedUri: body.expectedUri } : {}),
+            ...(typeof body.fromTraceId === "string" ? { fromTraceId: body.fromTraceId } : {}),
+        });
+        res.status(201).json({ ok: true });
+    }));
+    app.get("/api/events/stream", (req, res) => deps.sse.handler(req, res));
+}

package/dist/api/security.js

@@ -0,0 +1,86 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const DASH_COOKIE = "gisool_dash";
+export function deny(res, status, error, extra = {}) {
+    res.status(status).json({ error, ...extra });
+}
+export function safeEqual(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+export function dashCookieValue(token) {
+    return createHmac("sha256", token).update("dash").digest("hex");
+}
+export function bearerOf(req) {
+    const header = req.header("authorization") ?? "";
+    return header.startsWith("Bearer ") ? header.slice(7).trim() : "";
+}
+export function cookieOf(req, name) {
+    for (const part of (req.header("cookie") ?? "").split(";")) {
+        const eq = part.indexOf("=");
+        if (eq > 0 && part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return undefined;
+}
+/**
+ * DNS-rebinding and cross-site guard. `port()` is read per request so a server bound to port 0 checks its real port.
+ * Host must be 127.0.0.1:<port> or localhost:<port>; a present Origin must be the matching http origin;
+ * `Sec-Fetch-Site: cross-site` is always refused.
+ */
+export function localOnly(port) {
+    return (req, res, next) => {
+        const p = port();
+        const hosts = [`127.0.0.1:${p}`, `localhost:${p}`];
+        if (!hosts.includes(req.header("host") ?? ""))
+            return deny(res, 403, "host_not_allowed");
+        const origin = req.header("origin");
+        if (origin !== undefined && !hosts.some((h) => origin === `http://${h}`))
+            return deny(res, 403, "origin_not_allowed");
+        if ((req.header("sec-fetch-site") ?? "").toLowerCase() === "cross-site")
+            return deny(res, 403, "cross_site_not_allowed");
+        next();
+    };
+}
+/**
+ * `/mcp` and `/ingest/*` take only the bearer token; `/api/*` also accepts the dashboard cookie; everything else is public.
+ * The path is classified lowercased and percent-decoded so case or encoding variants (`/API/`, `/%61pi/`) cannot
+ * skip the gate even if a router ever matches them; a path that does not decode is refused.
+ */
+export function authGate(token) {
+    const cookie = dashCookieValue(token);
+    return (req, res, next) => {
+        let path;
+        try {
+            path = decodeURIComponent(req.path).toLowerCase();
+        }
+        catch {
+            return deny(res, 400, "bad_path");
+        }
+        const bearerOnly = path === "/mcp" || path.startsWith("/mcp/") || path.startsWith("/ingest/");
+        const api = path === "/api" || path.startsWith("/api/");
+        if (!bearerOnly && !api)
+            return next();
+        if (safeEqual(bearerOf(req), token))
+            return next();
+        if (api) {
+            const presented = cookieOf(req, DASH_COOKIE);
+            if (presented !== undefined && safeEqual(presented, cookie))
+                return next();
+        }
+        deny(res, 401, "unauthorized");
+    };
+}
+const MUTATIONS = new Set(["POST", "PUT", "PATCH"]);
+/** Mutations must declare a JSON body; OTLP protobuf gets a hint to switch the exporter to http/json. */
+export function requireJson(onReject) {
+    return (req, res, next) => {
+        if (!MUTATIONS.has(req.method) || req.is("application/json"))
+            return next();
+        onReject?.(req);
+        const protobuf = req.path.startsWith("/ingest/otlp/") && /protobuf/i.test(req.header("content-type") ?? "");
+        deny(res, 415, "unsupported_media_type", protobuf
+            ? { hint: "gisool accepts OTLP/HTTP JSON only; set OTEL_EXPORTER_OTLP_PROTOCOL=http/json (or OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json)" }
+            : { hint: "send Content-Type: application/json" });
+    };
+}

package/dist/api/sse.js

@@ -0,0 +1,55 @@
+export function createSseHub(lookup, log, heartbeatMs = 25_000) {
+    const clients = new Set();
+    const pending = new Set();
+    let scheduled = false;
+    const flush = () => {
+        scheduled = false;
+        const ids = [...pending];
+        pending.clear();
+        if (clients.size === 0)
+            return;
+        for (const id of ids) {
+            let row;
+            try {
+                row = lookup(id);
+            }
+            catch (error) {
+                log(`sse lookup for session ${id} failed: ${error.message}`);
+                continue;
+            }
+            if (!row)
+                continue;
+            const frame = `event: session\ndata: ${JSON.stringify(row)}\n\n`;
+            for (const res of clients)
+                res.write(frame);
+        }
+    };
+    const heartbeat = setInterval(() => {
+        for (const res of clients)
+            res.write(": ping\n\n");
+    }, heartbeatMs);
+    heartbeat.unref();
+    return {
+        handler(req, res) {
+            res.writeHead(200, { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-store", Connection: "keep-alive", "X-Accel-Buffering": "no" });
+            res.write(": connected\n\n");
+            clients.add(res);
+            req.on("close", () => clients.delete(res));
+        },
+        notify(sessionId) {
+            pending.add(sessionId);
+            if (!scheduled) {
+                scheduled = true;
+                setImmediate(flush);
+            }
+        },
+        clientCount: () => clients.size,
+        close() {
+            clearInterval(heartbeat);
+            for (const res of clients)
+                res.end();
+            clients.clear();
+            pending.clear();
+        },
+    };
+}

package/dist/api/static.js

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import { DASH_COOKIE, dashCookieValue, deny, safeEqual } from "./security.js";
+export function defaultDashboardDir() {
+    return fileURLToPath(new URL("../dashboard/", import.meta.url));
+}
+/**
+ * `GET /?token=<token>` trades the bearer token for the HttpOnly dashboard cookie and redirects to `/`;
+ * `GET /` serves index.html uncached; `/assets/*` serves the built bundle.
+ */
+export function registerStatic(app, opts) {
+    const dir = opts.dir ?? defaultDashboardDir();
+    const cookie = dashCookieValue(opts.token);
+    app.get("/", (req, res) => {
+        const presented = req.query.token;
+        if (presented !== undefined) {
+            if (typeof presented !== "string" || !safeEqual(presented, opts.token))
+                return deny(res, 401, "unauthorized");
+            res.setHeader("Set-Cookie", `${DASH_COOKIE}=${cookie}; HttpOnly; SameSite=Strict; Path=/`);
+            res.setHeader("Cache-Control", "no-store");
+            return res.redirect(302, "/");
+        }
+        const index = join(dir, "index.html");
+        if (!existsSync(index))
+            return deny(res, 503, "dashboard_not_built", { hint: "run npm run build in the gisool package" });
+        res.setHeader("Cache-Control", "no-store");
+        res.sendFile(index);
+    });
+    app.use("/assets", express.static(join(dir, "assets"), { index: false, fallthrough: false }));
+}

package/dist/catalog/fields.js

@@ -0,0 +1,146 @@
+// Ported from server/src/index.ts @48e7955
+import { parse as parseYaml } from "yaml";
+export const BODY_HEAD_MAX = 600;
+/** Splits SKILL.md into YAML frontmatter (object) and body; frontmatter is null when absent or invalid. */
+export function splitSkillMarkdown(input) {
+    const markdown = input.replace(/\r\n/g, "\n");
+    if (!markdown.startsWith("---\n"))
+        return { frontmatter: null, body: markdown };
+    const end = markdown.indexOf("\n---", 4);
+    if (end === -1)
+        return { frontmatter: null, body: markdown };
+    const afterDelimiter = markdown.slice(end + 4, end + 5);
+    if (afterDelimiter !== "" && afterDelimiter !== "\n")
+        return { frontmatter: null, body: markdown };
+    const body = markdown.slice(end + 5);
+    let parsed;
+    try {
+        parsed = parseYaml(markdown.slice(4, end));
+    }
+    catch {
+        return { frontmatter: null, body };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return { frontmatter: null, body };
+    return { frontmatter: parsed, body };
+}
+/** Accepts a YAML list of strings or a comma-separated string; anything else yields []. */
+export function stringList(value) {
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === "string").map((s) => s.trim()).filter(Boolean);
+    if (typeof value === "string")
+        return value.split(",").map((s) => s.trim()).filter(Boolean);
+    return [];
+}
+function explicitGroup(value) {
+    if (typeof value === "string" && value.trim())
+        return { id: value.trim() };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.id !== "string" || !record.id.trim())
+        return undefined;
+    const stage = typeof record.stage === "string" && record.stage.trim() ? record.stage.trim() : typeof record.stage === "number" ? String(record.stage) : undefined;
+    return stage === undefined ? { id: record.id.trim() } : { id: record.id.trim(), stage };
+}
+/** First non-heading paragraph of the body, whitespace-collapsed, at most BODY_HEAD_MAX chars. */
+export function bodyHead(body) {
+    let inFence = false;
+    const paragraphs = [];
+    let current = [];
+    for (const line of body.split("\n")) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            if (current.length) {
+                paragraphs.push(current.join(" "));
+                current = [];
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (!line.trim()) {
+            if (current.length) {
+                paragraphs.push(current.join(" "));
+                current = [];
+            }
+            continue;
+        }
+        if (/^\s{0,3}#/.test(line)) {
+            if (current.length) {
+                paragraphs.push(current.join(" "));
+                current = [];
+            }
+            continue;
+        }
+        current.push(line.trim());
+        if (current.join(" ").length > BODY_HEAD_MAX)
+            break;
+    }
+    if (current.length)
+        paragraphs.push(current.join(" "));
+    const first = paragraphs.find((p) => p.trim()) ?? "";
+    return first.replace(/\s+/g, " ").trim().slice(0, BODY_HEAD_MAX);
+}
+/** Extracts the routing fields; returns null when name or description is missing. */
+export function extractFields(frontmatter, body) {
+    const { name, description } = frontmatter;
+    if (typeof name !== "string" || !name || typeof description !== "string" || !description)
+        return null;
+    const whenRaw = frontmatter.when_to_use ?? frontmatter["when-to-use"];
+    const fields = {
+        name,
+        description,
+        tags: stringList(frontmatter.tags),
+        examples: stringList(frontmatter.examples),
+        aliasesKo: stringList(frontmatter.aliases_ko),
+        invocation: frontmatter["disable-model-invocation"] === true || frontmatter["disable-model-invocation"] === "true" ? "explicit" : "automatic",
+        bodyHead: bodyHead(body),
+    };
+    if (typeof whenRaw === "string" && whenRaw.trim())
+        fields.whenToUse = whenRaw.trim();
+    const group = explicitGroup(frontmatter.group);
+    if (group)
+        fields.group = group;
+    return fields;
+}
+/** Family id derived from a name: the prefix before the first "-" (the whole name when there is none). */
+export function familyPrefix(name) {
+    const index = name.indexOf("-");
+    return index === -1 ? name : name.slice(0, index);
+}
+/**
+ * Assigns derived groups (prefix families with >= 2 distinct names) to entries lacking an explicit group,
+ * and returns every family: explicit groups plus derived prefix families, uris sorted.
+ */
+export function applyFamilies(entries, explicit) {
+    const namesByPrefix = new Map();
+    for (const entry of entries) {
+        if (explicit.get(entry.uri))
+            continue;
+        const prefix = familyPrefix(entry.name);
+        if (!namesByPrefix.has(prefix))
+            namesByPrefix.set(prefix, new Set());
+        namesByPrefix.get(prefix).add(entry.name);
+    }
+    const families = new Map();
+    for (const entry of entries) {
+        const group = explicit.get(entry.uri);
+        if (group) {
+            entry.group = group;
+        }
+        else {
+            const prefix = familyPrefix(entry.name);
+            if ((namesByPrefix.get(prefix)?.size ?? 0) >= 2)
+                entry.group = { id: prefix };
+            else
+                delete entry.group;
+        }
+        if (entry.group) {
+            if (!families.has(entry.group.id))
+                families.set(entry.group.id, []);
+            families.get(entry.group.id).push(entry.uri);
+        }
+    }
+    return [...families.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([id, uris]) => ({ id, uris: uris.sort() }));
+}