@any-nav/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 — 2026-10-21
+
+First registry release.
+
+- Public SDK surface: the `createAnyNav` / `listFolder` facade, config
+  (`loadConfigFile` / `parseConfig` / `ConfigError`), the budget-guard
+  engine, render / `materialize` with built-in `agents-md` and
+  `generic-markdown` formats, and the query faces (`routingView`,
+  `curatedView`, `candidateFeed`, the search kernel, `readSource`).
+- `routingViewJson` — the routing projection serialized as pure JSON, the
+  machine face for CLI `--json` and library consumers.
+- Scanning now composes the split-out zero-dependency `@any-nav/scan`
+  package and re-exports its full face; embedders who only need the engine
+  can depend on `@any-nav/scan` directly.
+- Listings compose the structure-only walk — depth-bounded views hydrate
+  only the rows they render, not every file under the root.
+- Budget cuts surface as lower bounds: the routing face carries
+  `countIncompletePaths`; rendered rows show ≥N floors with the
+  `count-truncated-at-limit` diagnostic.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatheadOwl
+
+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,70 @@
-# Temporary Holding Version
+# @any-nav/core
 
-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.
+> 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
+
+```sh
+npm install @any-nav/core
+```
+
+## Usage
+
+The one-call face — list a folder under its nearest governing config (pure
+defaults when there is none):
+
+```ts
+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 string
+```
+
+The full facade:
+
+```ts
+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 file
+```
+
+## Config
+
+`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/scan`
+  directly and carry no SDK dependencies (smol-toml, fast-bm25 live on this
+  package's config and search paths, not the engine's).
+
+## License
+
+MIT

package/dist/bindings.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bindings: passive-push declarations (mode ④).
+ *
+ * Interface only — the harness extracts paths from prompts and tool
+ * calls and calls resolve(); core never triggers. Glob support is a
+ * small in-house matcher (** across separators, * and ? within one).
+ */
+import type { NavSource, PushResolution } from './types.ts';
+export declare function globToRegExp(pattern: string): RegExp;
+export declare function resolvePush(sources: NavSource[], path: string): PushResolution;

package/dist/bindings.js

@@ -0,0 +1,51 @@
+export function globToRegExp(pattern) {
+    const segments = pattern.replace(/\\/g, '/').split('/');
+    let source = '';
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        const isLast = i === segments.length - 1;
+        if (segment === '**') {
+            // Trailing ** matches any tail; mid-pattern ** matches whole directories.
+            source += isLast ? '.*' : '(?:.*/)?';
+            continue;
+        }
+        source += segment
+            .split('')
+            .map((ch) => (ch === '*' ? '[^/]*' : ch === '?' ? '[^/]' : escapeRegExp(ch)))
+            .join('');
+        if (!isLast)
+            source += '/';
+    }
+    return new RegExp(`^${source}$`);
+}
+export function resolvePush(sources, path) {
+    const normalized = path.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    const items = [];
+    for (const source of sources) {
+        for (const binding of source.config.bind ?? []) {
+            if (!globToRegExp(binding.match).test(normalized))
+                continue;
+            for (const itemPath of binding.items) {
+                const item = findItem(source.tree, itemPath.replace(/\\/g, '/').replace(/^\.\//, ''));
+                if (item !== null)
+                    items.push(item);
+            }
+        }
+    }
+    return { matched: items.length > 0, items };
+}
+function findItem(tree, relPath) {
+    const segments = relPath.split('/').filter((s) => s !== '');
+    let node = tree;
+    for (const segment of segments) {
+        const next = node.children?.find((c) => c.name === segment || (c.kind === 'file' && `${c.name}.md` === segment.toLowerCase()));
+        if (!next)
+            return null;
+        node = next;
+    }
+    return node.kind === 'file' ? node.item ?? null : null;
+}
+function escapeRegExp(ch) {
+    return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+//# sourceMappingURL=bindings.js.map

package/dist/bindings.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import type { ScanConfig } from '@any-nav/scan';
+export interface BudgetConfig {
+    /** Share of the context budget navigation may occupy, 0 < share ≤ 1. */
+    share?: number;
+    /** Hard cap in estimated tokens. */
+    maxTokens?: number;
+}
+export interface AnyNavConfig {
+    /**
+     * Curated default-expansion list (the `local` kind family; external /
+     * command members are parked in a trigger unit). Entries are
+     * config-root-relative folder paths; a listed folder's row expands to
+     * its direct children. Membership says expansion, not existence —
+     * folders off the list stay addressable by path. Optional; default = no
+     * expansion (depth-0 everywhere).
+     */
+    local?: string[];
+    budget?: BudgetConfig;
+    scan?: ScanConfig;
+    /**
+     * Declared entry commands (2026-10-16): full CLI command lines an agent
+     * runs once when starting here, e.g. "coggit instructions". Pure
+     * declarations — any-nav never executes them and never reads their
+     * output; the list faces render one leading procedure line. Optional;
+     * default = none.
+     */
+    commands?: string[];
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function parseConfig(text: string): AnyNavConfig;
+export declare function loadConfigFile(configPath: string): Promise<AnyNavConfig>;
+/**
+ * Normalize one local entry to a clean config-root-relative POSIX path.
+ * The unit is the path — no globs, no numeric depths (Any principle: an
+ * entry states "expand this folder", containment merges trees for free).
+ */
+export declare function normalizeLocalPath(entry: string, where: string): string;

package/dist/config.js

@@ -0,0 +1,177 @@
+/**
+ * Config: parse and strictly validate any-nav.toml.
+ *
+ * The file only states exceptions — scan / local / budget / commands are
+ * the whole key set (framework decision 9, unified list model; commands
+ * joined 2026-10-16, entry-procedures argumentation): scan bounds the
+ * subtree, local curates default expansion, budget guards size, commands
+ * declares entry procedure. Unknown keys are rejected rather than ignored.
+ */
+import { readFile } from 'node:fs/promises';
+import { parse } from 'smol-toml';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+export function parseConfig(text) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch (err) {
+        throw new ConfigError(`TOML syntax error: ${err.message}`);
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ConfigError('config must be a TOML table');
+    }
+    const obj = raw;
+    const unknownTop = Object.keys(obj).filter((k) => k !== 'local' && k !== 'budget' && k !== 'scan' && k !== 'commands');
+    if (unknownTop.length > 0) {
+        throw new ConfigError(`unknown top-level keys: ${unknownTop.join(', ')}`);
+    }
+    const local = obj.local === undefined ? undefined : parseLocal(obj.local);
+    const budget = obj.budget === undefined ? undefined : parseBudget(obj.budget);
+    const scan = obj.scan === undefined ? undefined : parseScan(obj.scan);
+    const commands = obj.commands === undefined ? undefined : parseCommands(obj.commands);
+    const config = {};
+    if (local !== undefined)
+        config.local = local;
+    if (budget !== undefined)
+        config.budget = budget;
+    if (scan !== undefined)
+        config.scan = scan;
+    if (commands !== undefined)
+        config.commands = commands;
+    return config;
+}
+export async function loadConfigFile(configPath) {
+    const text = await readFile(configPath, 'utf8');
+    return parseConfig(text);
+}
+/**
+ * Normalize one local entry to a clean config-root-relative POSIX path.
+ * The unit is the path — no globs, no numeric depths (Any principle: an
+ * entry states "expand this folder", containment merges trees for free).
+ */
+export function normalizeLocalPath(entry, where) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+        throw new ConfigError(`${where} must be a non-empty path string`);
+    }
+    if (/[*?[\]]/.test(entry)) {
+        throw new ConfigError(`${where} must be a plain path, not a glob: ${entry}`);
+    }
+    const normalized = entry.replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+    if (normalized === '' || normalized === '.') {
+        throw new ConfigError(`${where} must name a folder under the config root, not the root itself: ${entry}`);
+    }
+    const segments = normalized.split('/');
+    if (segments.some((s) => s === '' || s === '.')) {
+        throw new ConfigError(`${where} is not a clean relative path: ${entry}`);
+    }
+    if (segments.includes('..')) {
+        throw new ConfigError(`${where} must stay under the config root: ${entry}`);
+    }
+    if (/^[a-zA-Z]:/.test(normalized) || normalized.startsWith('/')) {
+        throw new ConfigError(`${where} must be config-root-relative, not absolute: ${entry}`);
+    }
+    return segments.join('/');
+}
+function parseLocal(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new ConfigError('local must be a non-empty array of folder paths (omit the key for no expansion)');
+    }
+    const seen = new Set();
+    const out = [];
+    raw.forEach((entry, i) => {
+        const normalized = normalizeLocalPath(entry, `local[${i}]`);
+        if (seen.has(normalized)) {
+            throw new ConfigError(`local lists the same path twice: ${normalized}`);
+        }
+        seen.add(normalized);
+        out.push(normalized);
+    });
+    return out;
+}
+function parseScan(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ConfigError('scan must be a table');
+    }
+    const obj = raw;
+    const known = ['excludeDirs', 'excludeFiles', 'excludeDotEntries', 'respectGitignore', 'maxFiles'];
+    const unknown = Object.keys(obj).filter((k) => !known.includes(k));
+    if (unknown.length > 0) {
+        throw new ConfigError(`unknown keys in scan: ${unknown.join(', ')}`);
+    }
+    const scan = {};
+    for (const key of ['excludeDirs', 'excludeFiles']) {
+        const value = obj[key];
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value) || !value.every((s) => typeof s === 'string' && s.trim() !== '')) {
+            throw new ConfigError(`scan.${key} must be an array of non-empty strings`);
+        }
+        if (value.length === 0) {
+            throw new ConfigError(`scan.${key} must not be empty — omit the key to keep just the built-in defaults (it appends, never replaces)`);
+        }
+        scan[key] = value;
+    }
+    for (const key of ['excludeDotEntries', 'respectGitignore']) {
+        const value = obj[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'boolean') {
+            throw new ConfigError(`scan.${key} must be a boolean`);
+        }
+        scan[key] = value;
+    }
+    if (obj.maxFiles !== undefined) {
+        if (typeof obj.maxFiles !== 'number' || !Number.isInteger(obj.maxFiles) || obj.maxFiles <= 0) {
+            throw new ConfigError('scan.maxFiles must be a positive integer');
+        }
+        scan.maxFiles = obj.maxFiles;
+    }
+    return scan;
+}
+function parseCommands(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new ConfigError('commands must be a non-empty array of CLI command lines (omit the key for none)');
+    }
+    const seen = new Set();
+    raw.forEach((entry, i) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            throw new ConfigError(`commands[${i}] must be a non-empty command line string`);
+        }
+        if (seen.has(entry)) {
+            throw new ConfigError(`commands lists the same command twice: ${entry}`);
+        }
+        seen.add(entry);
+    });
+    return raw;
+}
+function parseBudget(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ConfigError('budget must be a table');
+    }
+    const obj = raw;
+    const unknown = Object.keys(obj).filter((k) => k !== 'share' && k !== 'maxTokens');
+    if (unknown.length > 0) {
+        throw new ConfigError(`unknown keys in budget: ${unknown.join(', ')}`);
+    }
+    const budget = {};
+    if (obj.share !== undefined) {
+        if (typeof obj.share !== 'number' || !(obj.share > 0 && obj.share <= 1)) {
+            throw new ConfigError('budget.share must be a number in (0, 1]');
+        }
+        budget.share = obj.share;
+    }
+    if (obj.maxTokens !== undefined) {
+        if (typeof obj.maxTokens !== 'number' || !Number.isInteger(obj.maxTokens) || obj.maxTokens <= 0) {
+            throw new ConfigError('budget.maxTokens must be a positive integer');
+        }
+        budget.maxTokens = obj.maxTokens;
+    }
+    return budget;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/description.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One-line description extraction, ported verbatim from the routes module
+ * (dsh-plugin-dev/extras/modules/routes/src/description.ts, ADR-0010:
+ * absorption is porting — every boundary handling here is tuition already
+ * paid on production corpora; do not "simplify" it).
+ *
+ * Priority: ① frontmatter `description:`, ② an explicit `description:` line
+ * in the document head, ③ the first substantive body line as a fallback.
+ * Returns null when none match.
+ */
+/**
+ * Extracts a one-line route description from Markdown, in priority order:
+ * ① frontmatter `description:`, ② an explicit `description:` line in the document
+ * head, ③ the first substantive body line as a fallback. Returns `null` when none match.
+ */
+export declare function extractDescription(content: string): string | null;
+/**
+ * Directory sidecar read (2026-10-07): `_category_.yml/.yaml/.json` carry a
+ * folder's description so release-face READMEs stay untouched. YAML reuses
+ * the frontmatter ① key reader — the sidecar is frontmatter without the
+ * document (an indented `link.description:` therefore reads too, covering
+ * Docusaurus-shaped files for free); JSON parses properly and accepts the
+ * top-level `description` or the Docusaurus `link.description` shape.
+ * `{ description: null }` means the file carries no description key.
+ */
+export type SidecarRead = {
+    description: string | null;
+} | {
+    error: string;
+};
+export declare function extractSidecarDescription(fileName: string, content: string): SidecarRead;