@blogmcp/nav-core 0.1.0

package/dist/traverse/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @blogmcp/nav-core — traverse
+ *
+ * Pure read helpers over a resolved tree. Two consumers with opposite needs use
+ * the same functions: the SDK runs them in-memory over a cached tree (zero
+ * round-trips), and the server exposes them as MCP tools (token-efficient).
+ *
+ * All functions are non-mutating. Functions that depend on display order sort
+ * siblings by `order` internally (stable: explicit order ascending, then
+ * undefined-order nodes in their original sequence).
+ */
+import type { FlatNode, LocalizedTree, Locale, NavNode, NavTree } from '../types/index.js';
+/** Stable sort of siblings by `order` (undefined sorts last, ties keep input order). */
+export declare function sortSiblings(nodes: readonly NavNode[]): NavNode[];
+/** Return a new tree with every level's children sorted by `order`. */
+export declare function sortTree(tree: NavTree): NavNode[];
+/** Depth-first pre-order walk. Return `false` from the visitor to stop early. */
+export declare function walk(tree: NavTree, visitor: (node: NavNode, parent: NavNode | null, depth: number) => void | boolean): void;
+/** Find a node by id, or `undefined`. */
+export declare function findNode(tree: NavTree, id: string): NavNode | undefined;
+/** Find a node's parent, or `null` if it is a root (or `undefined` if not found). */
+export declare function getParent(tree: NavTree, id: string): NavNode | null | undefined;
+/**
+ * Ancestor path from root to the node, inclusive of the node itself.
+ * Empty array if not found. This is the basis for breadcrumbs.
+ */
+export declare function getPath(tree: NavTree, id: string): NavNode[];
+/** Ancestors of a node, root → parent (excludes the node itself). */
+export declare function breadcrumbs(tree: NavTree, id: string): NavNode[];
+/** Siblings of a node (same parent), excluding the node itself, in display order. */
+export declare function getSiblings(tree: NavTree, id: string): NavNode[];
+/** The node together with its descendants, or `undefined`. */
+export declare function getSubtree(tree: NavTree, id: string): NavNode | undefined;
+/** Default "navigable" predicate: visible article references only. */
+export declare function isNavigable(node: NavNode): boolean;
+export interface NextPrev {
+    readonly prev: NavNode | null;
+    readonly next: NavNode | null;
+}
+/**
+ * Previous/next navigable node in depth-first display order. By default only
+ * visible `article-ref` nodes participate; pass a predicate to change that.
+ */
+export declare function getNextPrev(tree: NavTree, id: string, predicate?: (node: NavNode) => boolean): NextPrev;
+/** Flatten to FLAT form (parent pointer + index + depth), in display order. */
+export declare function flatten(tree: NavTree): FlatNode[];
+/** Default access-tier ranking (higher = more access). */
+export declare const DEFAULT_TIER_RANK: Readonly<Record<string, number>>;
+/**
+ * Whether a node is visible to a viewer tier. A node with no `visibility.tiers`
+ * is public. Otherwise the viewer must meet (rank ≥) at least one declared tier.
+ * Pure helper; pair with {@link prune} to filter a tree. (Content-level access —
+ * which articles exist at all — is enforced upstream in the data query; this
+ * gates override-declared per-node visibility.)
+ */
+export declare function visibleToTier(node: NavNode, viewerTier: string, ranks?: Readonly<Record<string, number>>): boolean;
+/** Remove every node (and its subtree) for which `keep` returns false. */
+export declare function prune(tree: NavTree, keep: (node: NavNode) => boolean): NavNode[];
+export interface LocalizeOptions {
+    readonly locale: Locale;
+    readonly fallbackLocale?: Locale;
+    /**
+     * Supplies a default label when `labels` has none for the locale — typically
+     * the referenced article's title. nav-core does not know article content, so
+     * the consumer provides this.
+     */
+    readonly labelResolver?: (node: NavNode, locale: Locale) => string | undefined;
+}
+/** Resolve `labels` to a single locale, producing a {@link LocalizedTree}. */
+export declare function localize(tree: NavTree, options: LocalizeOptions): LocalizedTree;

package/dist/traverse/index.js

@@ -0,0 +1,213 @@
+/**
+ * @blogmcp/nav-core — traverse
+ *
+ * Pure read helpers over a resolved tree. Two consumers with opposite needs use
+ * the same functions: the SDK runs them in-memory over a cached tree (zero
+ * round-trips), and the server exposes them as MCP tools (token-efficient).
+ *
+ * All functions are non-mutating. Functions that depend on display order sort
+ * siblings by `order` internally (stable: explicit order ascending, then
+ * undefined-order nodes in their original sequence).
+ */
+/* -------------------------------------------------------------------------- */
+/* ordering                                                                    */
+/* -------------------------------------------------------------------------- */
+/** Stable sort of siblings by `order` (undefined sorts last, ties keep input order). */
+export function sortSiblings(nodes) {
+    return [...nodes].sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity));
+}
+/** Return a new tree with every level's children sorted by `order`. */
+export function sortTree(tree) {
+    return sortSiblings(tree).map((node) => node.children && node.children.length > 0
+        ? { ...node, children: sortTree(node.children) }
+        : node);
+}
+/* -------------------------------------------------------------------------- */
+/* lookup                                                                      */
+/* -------------------------------------------------------------------------- */
+/** Depth-first pre-order walk. Return `false` from the visitor to stop early. */
+export function walk(tree, visitor) {
+    const recur = (nodes, parent, depth) => {
+        for (const node of nodes) {
+            if (visitor(node, parent, depth) === false)
+                return false;
+            if (node.children && !recur(node.children, node, depth + 1))
+                return false;
+        }
+        return true;
+    };
+    recur(tree, null, 0);
+}
+/** Find a node by id, or `undefined`. */
+export function findNode(tree, id) {
+    let found;
+    walk(tree, (node) => {
+        if (node.id === id) {
+            found = node;
+            return false;
+        }
+    });
+    return found;
+}
+/** Find a node's parent, or `null` if it is a root (or `undefined` if not found). */
+export function getParent(tree, id) {
+    let result;
+    walk(tree, (node, parent) => {
+        if (node.id === id) {
+            result = parent;
+            return false;
+        }
+    });
+    return result;
+}
+/**
+ * Ancestor path from root to the node, inclusive of the node itself.
+ * Empty array if not found. This is the basis for breadcrumbs.
+ */
+export function getPath(tree, id) {
+    const path = [];
+    let found = false;
+    const recur = (nodes) => {
+        for (const node of nodes) {
+            path.push(node);
+            if (node.id === id) {
+                found = true;
+                return true;
+            }
+            if (node.children && recur(node.children))
+                return true;
+            path.pop();
+        }
+        return false;
+    };
+    recur(tree);
+    return found ? path : [];
+}
+/** Ancestors of a node, root → parent (excludes the node itself). */
+export function breadcrumbs(tree, id) {
+    const path = getPath(tree, id);
+    return path.slice(0, -1);
+}
+/** Siblings of a node (same parent), excluding the node itself, in display order. */
+export function getSiblings(tree, id) {
+    const parent = getParent(tree, id);
+    if (parent === undefined)
+        return [];
+    const siblings = parent === null ? tree : (parent.children ?? []);
+    return sortSiblings(siblings).filter((n) => n.id !== id);
+}
+/** The node together with its descendants, or `undefined`. */
+export function getSubtree(tree, id) {
+    return findNode(tree, id);
+}
+/* -------------------------------------------------------------------------- */
+/* sequential navigation (prev / next)                                         */
+/* -------------------------------------------------------------------------- */
+/** Default "navigable" predicate: visible article references only. */
+export function isNavigable(node) {
+    return node.type === 'article-ref' && node.hidden !== true;
+}
+/**
+ * Previous/next navigable node in depth-first display order. By default only
+ * visible `article-ref` nodes participate; pass a predicate to change that.
+ */
+export function getNextPrev(tree, id, predicate = isNavigable) {
+    const sequence = [];
+    walk(sortTree(tree), (node) => {
+        if (predicate(node))
+            sequence.push(node);
+    });
+    const idx = sequence.findIndex((n) => n.id === id);
+    if (idx === -1)
+        return { prev: null, next: null };
+    return {
+        prev: idx > 0 ? sequence[idx - 1] : null,
+        next: idx < sequence.length - 1 ? sequence[idx + 1] : null,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* projections of shape                                                        */
+/* -------------------------------------------------------------------------- */
+/** Flatten to FLAT form (parent pointer + index + depth), in display order. */
+export function flatten(tree) {
+    const out = [];
+    const recur = (nodes, parentId, depth) => {
+        sortSiblings(nodes).forEach((node, index) => {
+            out.push({ id: node.id, parentId, type: node.type, index, depth });
+            if (node.children)
+                recur(node.children, node.id, depth + 1);
+        });
+    };
+    recur(tree, null, 0);
+    return out;
+}
+/* -------------------------------------------------------------------------- */
+/* access-tier visibility                                                      */
+/* -------------------------------------------------------------------------- */
+/** Default access-tier ranking (higher = more access). */
+export const DEFAULT_TIER_RANK = {
+    public: 0,
+    premium: 1,
+    partners: 2,
+    internal: 3,
+};
+/**
+ * Whether a node is visible to a viewer tier. A node with no `visibility.tiers`
+ * is public. Otherwise the viewer must meet (rank ≥) at least one declared tier.
+ * Pure helper; pair with {@link prune} to filter a tree. (Content-level access —
+ * which articles exist at all — is enforced upstream in the data query; this
+ * gates override-declared per-node visibility.)
+ */
+export function visibleToTier(node, viewerTier, ranks = DEFAULT_TIER_RANK) {
+    const tiers = node.visibility?.tiers;
+    if (!tiers || tiers.length === 0)
+        return true;
+    const viewerRank = ranks[viewerTier] ?? 0;
+    return tiers.some((t) => viewerRank >= (ranks[t] ?? 0));
+}
+/** Remove every node (and its subtree) for which `keep` returns false. */
+export function prune(tree, keep) {
+    return tree
+        .filter(keep)
+        .map((node) => node.children && node.children.length > 0
+        ? { ...node, children: prune(node.children, keep) }
+        : node);
+}
+/** Resolve `labels` to a single locale, producing a {@link LocalizedTree}. */
+export function localize(tree, options) {
+    const { locale, fallbackLocale, labelResolver } = options;
+    const resolveLabel = (node) => {
+        return (node.labels?.[locale] ??
+            (fallbackLocale ? node.labels?.[fallbackLocale] : undefined) ??
+            labelResolver?.(node, locale) ??
+            (fallbackLocale ? labelResolver?.(node, fallbackLocale) : undefined));
+    };
+    const localizeNode = (node) => {
+        const base = {
+            id: node.id,
+            type: node.type,
+            label: resolveLabel(node),
+            order: node.order,
+            badge: node.badge,
+            icon: node.icon,
+            hidden: node.hidden,
+            visibility: node.visibility,
+            data: node.data,
+            children: node.children ? sortSiblings(node.children).map(localizeNode) : [],
+        };
+        switch (node.type) {
+            case 'article-ref':
+                return { ...base, ref: node.ref, owned: node.owned, slug: node.slug };
+            case 'external-link':
+                return { ...base, href: node.href };
+            case 'generated-section':
+                return { ...base, slug: node.slug };
+            case 'group':
+                return { ...base, link: node.link, collapsed: node.collapsed, collapsible: node.collapsible };
+            case 'separator':
+                return base;
+        }
+    };
+    return sortSiblings(tree).map(localizeNode);
+}
+//# sourceMappingURL=index.js.map

package/dist/traverse/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/traverse/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @blogmcp/nav-core — types
+ *
+ * The framework-agnostic contract for the KB navigation (menu) tree.
+ * See competitor-monitor/docs/internal/navigation-model.md §4 for the design.
+ *
+ * Design invariants encoded here:
+ *  - Stable UUID per node (deep links / anchored comments / moves survive reorder).
+ *  - Discriminated `type` union: article-ref | group | external-link |
+ *    generated-section | separator.
+ *  - Single multilingual tree: per-node `labels` map keyed by locale; the
+ *    referenced article's title is the default (resolved by the consumer via a
+ *    `labelResolver`, since nav-core does not know article content).
+ *  - `badge` and `icon` are typed first-class (Starlight precedent); everything
+ *    else genuinely arbitrary lives in the opaque, size-capped `data` bag.
+ *  - Trees are treated as immutable: every node/collection is `readonly`, and the
+ *    mutate module returns new trees rather than editing in place.
+ */
+/** Discriminator for {@link NavNode}. */
+export type NavNodeType = 'article-ref' | 'group' | 'external-link' | 'generated-section' | 'separator';
+/** All node type discriminators, for runtime validation. */
+export declare const NAV_NODE_TYPES: readonly NavNodeType[];
+/** BCP-47 / language code, e.g. `cs`, `en`, `pt-BR`. */
+export type Locale = string;
+/** Per-locale label overrides. Missing locales fall back (see localize). */
+export type LocaleLabels = Readonly<Record<Locale, string>>;
+/**
+ * Typed first-class presentation hint. Mirrors Astro Starlight's `badge`.
+ * `variant` is intentionally open (`string`) so themes can define their own.
+ */
+export interface BadgeSpec {
+    readonly text: string;
+    readonly variant?: string;
+    readonly class?: string;
+}
+/**
+ * Access-tier gating. nav-core stays policy-free: it only carries the declared
+ * tiers; consumers decide what a viewer may see (e.g. via {@link prune}).
+ * Omitted = inherit from ancestor / public.
+ */
+export interface Visibility {
+    readonly tiers?: readonly string[];
+}
+/**
+ * Opaque, namespaced customer extension bag. The platform stores and round-trips
+ * it but never interprets it. Size/depth-capped by {@link validate}. Renderers
+ * must treat values as untrusted.
+ */
+export type NavData = Readonly<Record<string, unknown>>;
+/** Fields shared by every node type. */
+export interface NavNodeBase {
+    /** Stable UUID. Unique across the whole tree. */
+    readonly id: string;
+    /** Sibling sort key. Fractional, so a node can be inserted between two siblings without renumbering. */
+    readonly order?: number;
+    /** Per-locale label overrides. */
+    readonly labels?: LocaleLabels;
+    /** Typed first-class badge hint. */
+    readonly badge?: BadgeSpec;
+    /** Typed first-class icon hint (icon name/key; renderer maps it). */
+    readonly icon?: string;
+    /** Reachable by direct URL but suppressed from this menu. Distinct from access-tier {@link visibility}. */
+    readonly hidden?: boolean;
+    /** Access-tier gating. */
+    readonly visibility?: Visibility;
+    /** Opaque customer extension bag. */
+    readonly data?: NavData;
+    /** Child nodes. Only `group` and `article-ref` may have children. */
+    readonly children?: readonly NavNode[];
+}
+/** References a `kb_articles.id`. */
+export interface ArticleRefNode extends NavNodeBase {
+    readonly type: 'article-ref';
+    /** `kb_articles.id`. */
+    readonly ref: string;
+    /** Public URL handle (filename without extension) — lets consumers build links without a second lookup. */
+    readonly slug?: string;
+    /**
+     * Exactly one nav location should *own* an article (drives prev/next pagination
+     * and the canonical breadcrumb). Other locations referencing the same article
+     * set `owned: false` (Docusaurus `doc` vs `ref`).
+     */
+    readonly owned?: boolean;
+}
+/** Optional clickable target for a {@link GroupNode} heading. */
+export type GroupLink = {
+    readonly kind: 'article';
+    readonly ref: string;
+} | {
+    readonly kind: 'generated';
+    readonly slug: string;
+};
+/** A section. May be a clickable heading and may collapse. */
+export interface GroupNode extends NavNodeBase {
+    readonly type: 'group';
+    /** Optional clickable section heading (existing article or a generated-section). */
+    readonly link?: GroupLink;
+    /** Default open/closed state. */
+    readonly collapsed?: boolean;
+    /** Whether the group can be collapsed at all. */
+    readonly collapsible?: boolean;
+}
+/** Arbitrary external URL. Override-only — auto-build never emits these. */
+export interface ExternalLinkNode extends NavNodeBase {
+    readonly type: 'external-link';
+    readonly href: string;
+}
+/** Query backing a {@link GeneratedSectionNode}. Open shape; `tag` is the v1 case. */
+export interface GeneratedQuery {
+    readonly tag?: string;
+    readonly [key: string]: unknown;
+}
+/** A section resolved at read time (e.g. "all articles tagged X"). */
+export interface GeneratedSectionNode extends NavNodeBase {
+    readonly type: 'generated-section';
+    /** URL slug of the generated landing page. */
+    readonly slug: string;
+    /** Query that selects the members. */
+    readonly query: GeneratedQuery;
+    readonly title?: string;
+    readonly description?: string;
+}
+/** Pure visual divider. Leaf node. */
+export interface SeparatorNode extends NavNodeBase {
+    readonly type: 'separator';
+}
+/** Any navigation node. */
+export type NavNode = ArticleRefNode | GroupNode | ExternalLinkNode | GeneratedSectionNode | SeparatorNode;
+/** A navigation tree is an ordered list of root nodes. */
+export type NavTree = readonly NavNode[];
+/** Node types that are allowed to have children. */
+export declare const CONTAINER_NODE_TYPES: readonly NavNodeType[];
+/** One node in FLAT form: parent pointer + depth instead of nesting. */
+export interface FlatNode {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly type: NavNodeType;
+    /** 0-based position among siblings (post-sort). */
+    readonly index: number;
+    /** Depth from root (root nodes = 0). */
+    readonly depth: number;
+}
+/** A node with its label resolved to one locale (no `labels` map). */
+export interface LocalizedNode {
+    readonly id: string;
+    readonly type: NavNodeType;
+    /** Resolved label for the requested locale, if any could be determined. */
+    readonly label?: string;
+    readonly order?: number;
+    readonly badge?: BadgeSpec;
+    readonly icon?: string;
+    readonly hidden?: boolean;
+    readonly visibility?: Visibility;
+    readonly data?: NavData;
+    /** Carried through for renderers (ref/href/slug/link/collapsed…). */
+    readonly ref?: string;
+    readonly owned?: boolean;
+    readonly href?: string;
+    readonly slug?: string;
+    readonly link?: GroupLink;
+    readonly collapsed?: boolean;
+    readonly collapsible?: boolean;
+    readonly children: readonly LocalizedNode[];
+}
+export type LocalizedTree = readonly LocalizedNode[];

package/dist/types/index.js

@@ -0,0 +1,29 @@
+/**
+ * @blogmcp/nav-core — types
+ *
+ * The framework-agnostic contract for the KB navigation (menu) tree.
+ * See competitor-monitor/docs/internal/navigation-model.md §4 for the design.
+ *
+ * Design invariants encoded here:
+ *  - Stable UUID per node (deep links / anchored comments / moves survive reorder).
+ *  - Discriminated `type` union: article-ref | group | external-link |
+ *    generated-section | separator.
+ *  - Single multilingual tree: per-node `labels` map keyed by locale; the
+ *    referenced article's title is the default (resolved by the consumer via a
+ *    `labelResolver`, since nav-core does not know article content).
+ *  - `badge` and `icon` are typed first-class (Starlight precedent); everything
+ *    else genuinely arbitrary lives in the opaque, size-capped `data` bag.
+ *  - Trees are treated as immutable: every node/collection is `readonly`, and the
+ *    mutate module returns new trees rather than editing in place.
+ */
+/** All node type discriminators, for runtime validation. */
+export const NAV_NODE_TYPES = [
+    'article-ref',
+    'group',
+    'external-link',
+    'generated-section',
+    'separator',
+];
+/** Node types that are allowed to have children. */
+export const CONTAINER_NODE_TYPES = ['group', 'article-ref'];
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,aAAa;IACb,OAAO;IACP,eAAe;IACf,mBAAmB;IACnB,WAAW;CACZ,CAAC;AA8HF,oDAAoD;AACpD,MAAM,CAAC,MAAM,oBAAoB,GAA2B,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC"}

package/dist/validate/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @blogmcp/nav-core — validate
+ *
+ * Structural validation of a navigation tree. Server-authoritative: the API
+ * layer re-runs this on every mutation (clients can't be trusted not to create
+ * a cycle / oversized data bag). nav-core never *interprets* the `data` bag — it
+ * only enforces size/depth caps so the JSONB-source-of-truth stays a small,
+ * one-row-read, cacheable artifact (see navigation-model.md §2, §4).
+ */
+import { type NavTree } from '../types/index.js';
+/** Default caps. Override per call via {@link ValidateOptions}. */
+export declare const DEFAULT_MAX_DEPTH = 6;
+export declare const DEFAULT_MAX_DATA_BYTES = 4096;
+export declare const DEFAULT_MAX_DATA_DEPTH = 8;
+export interface ValidateOptions {
+    /** Max nesting depth (root nodes are depth 0). */
+    readonly maxDepth?: number;
+    /** Max serialized byte size of a single node's `data` bag. */
+    readonly maxDataBytes?: number;
+    /** Max nesting depth of a single node's `data` bag. */
+    readonly maxDataDepth?: number;
+}
+export type ValidationCode = 'DUPLICATE_ID' | 'MISSING_ID' | 'UNKNOWN_TYPE' | 'MAX_DEPTH_EXCEEDED' | 'CHILDREN_NOT_ALLOWED' | 'MISSING_REQUIRED_FIELD' | 'INVALID_ORDER' | 'MULTIPLE_OWNERS' | 'DATA_TOO_LARGE' | 'DATA_TOO_DEEP' | 'INVALID_OVERRIDES';
+export interface ValidationError {
+    readonly code: ValidationCode;
+    readonly message: string;
+    readonly nodeId?: string;
+}
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+}
+/**
+ * Validate a navigation tree. Returns all errors found (does not throw); callers
+ * that prefer to throw can use {@link assertValid}.
+ */
+export declare function validate(tree: NavTree, options?: ValidateOptions): ValidationResult;
+/** Throwing variant. */
+export declare function assertValid(tree: NavTree, options?: ValidateOptions): void;
+/** Error thrown by {@link assertValid}. */
+export declare class NavValidationError extends Error {
+    readonly errors: readonly ValidationError[];
+    constructor(message: string, errors: readonly ValidationError[]);
+}