@any-nav/core
v0.2.0
Published
Any-Nav SDK: read-only core that scans Markdown folders into navigation, decides exposure within a context budget, renders injection fragments, and answers list/search/read. Adapters own all writes, processes, and protocols.
Maintainers
Readme
@any-nav/core
The Any-Nav SDK: scan a Markdown folder, guard it against a context budget, render navigation fragments, and answer list / search / read.
@any-nav/core is the read-only SDK behind Any-Nav. It composes the
zero-dependency scan engine (@any-nav/scan — its full face is re-exported
here) with: strict any-nav.toml config parsing, curation of default
expansion via the config's local list, the budget-guard engine, rendering
of the canonical navigation fragment for registered formats, and the query
faces — list(path) with its rows / markdown renderings and JSON
serialization, the search kernel, read, and the candidate feed.
Install
npm install @any-nav/coreUsage
The one-call face — list a folder under its nearest governing config (pure defaults when there is none):
import { listFolder, routingViewJson } from '@any-nav/core';
const listing = await listFolder('docs'); // optional query: { configPath, depth, commandRunner }
const machine = routingViewJson(listing); // the routing projection as a pure JSON stringThe full facade:
import { createAnyNav } from '@any-nav/core';
const app = await createAnyNav({ configPath: 'any-nav.toml' }); // or { config, cwd }
const sources = app.sources(); // the config root as the single implicit source
const exposure = app.decideExposure(sources[0]); // budget-guard reading — warns, never collapses
const fragment = app.render(exposure, 'agents-md');
const next = app.materialize(current, fragment); // pure splice — the caller writes the fileConfig
any-nav.toml states only exceptions; every key defaults:
local— curation list: paths expanded into the default listing.budget— the context-budget guard (over budget warns, never silently collapses).scan— scan boundary policy (excludeDirs/excludeFiles/excludeDotEntries/respectGitignore/maxFiles), additive over the engine's built-in floor.
Boundaries this SDK keeps
- Read-only over the filesystem: no writes, no processes, no network, no
transport or LLM-client imports.
materialize()returns new text — every write belongs to the adapter. - The unified list model:
list(path)is the product face; governance and expansion live here, adapters only transport. NavItem { name, description, locator }(from@any-nav/scan) is the only knowledge model.- Embedders that only need the scan engine can depend on
@any-nav/scandirectly and carry no SDK dependencies (smol-toml, fast-bm25 live on this package's config and search paths, not the engine's).
License
MIT
