@north-light/crouter 0.3.154

package/dist/core/memory-resolver.js

@@ -0,0 +1,422 @@
+import { join, relative, sep } from 'node:path';
+import { readdirSync } from 'node:fs';
+import { CRTR_DIR_NAME } from '../types.js';
+import { pathExists, readText, walkFiles } from './fs-utils.js';
+import { parseFrontmatterGeneric } from './frontmatter.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier } from './resolver.js';
+import { ambiguous, notFound, usage } from './errors.js';
+import { warn } from './output.js';
+import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
+import { effectiveDocKind, normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
+import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
+import { memoryDir as nodeMemoryDir } from './runtime/memory.js';
+/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
+export function memoryDocId(doc) {
+    return `${doc.scope}/${doc.name}`;
+}
+/** The selected profile id from the process env, or '' when none. The single
+ *  seam every profile-aware memory/config path reads through — see the plan's
+ *  synthesis decision on why this is process env, not a threaded parameter. */
+function selectedProfileId() {
+    return process.env['CRTR_PROFILE_ID'] || '';
+}
+/** The current node id from the process env, or '' when not running inside a
+ *  node. The seam the `node` scope resolves through — its memory dir is
+ *  `nodeMemoryDir(id)` (`nodes/<id>/context/memory/`). */
+function selectedNodeId() {
+    return process.env['CRTR_NODE_ID'] || '';
+}
+/** The memory scopes in resolution precedence: node > project stack > profile >
+ *  user > builtin. Node is included only inside a running node (`CRTR_NODE_ID`)
+ *  and ranks NEAREST — a node doc overrides any wider scope. Project is included
+ *  only when a project scope exists for the cwd (or the selected profile's
+ *  project stack); profile is included only when a profile is selected. A single
+ *  `scope` narrows to just that scope. */
+function scopesInPrecedence(scope) {
+    if (scope)
+        return [scope];
+    const out = [];
+    if (selectedNodeId() !== '')
+        out.push('node');
+    if (projectScopeRoot())
+        out.push('project');
+    if (selectedProfileId() !== '')
+        out.push('profile');
+    out.push('user');
+    out.push('builtin');
+    return out;
+}
+/** Memory loads project scopes as a stack, not a single nearest root: every
+ *  ancestor `.crouter/` from cwd upward (widened by a selected profile's
+ *  `projects`) contributes, nearest first. Profile is a singleton store
+ *  resolved through the centralized `loadProfileManifest` — never a raw path
+ *  join — and drops out silently (never throws the resolver) when the
+ *  selected profile id no longer resolves to a manifest. User and builtin
+ *  remain singleton scopes after that. */
+function memorySourcesInPrecedence(scope) {
+    const out = [];
+    for (const s of scopesInPrecedence(scope)) {
+        if (s === 'project') {
+            for (const root of projectScopeRoots()) {
+                out.push({
+                    scope: 'project',
+                    memoryDir: join(root, 'memory'),
+                    plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
+                });
+            }
+        }
+        else if (s === 'profile') {
+            const profileId = selectedProfileId();
+            if (profileId !== '') {
+                try {
+                    const { profileId: resolvedId } = loadProfileManifest(profileId);
+                    out.push({ scope: 'profile', memoryDir: profileMemoryDir(resolvedId), plugins: [] });
+                }
+                catch {
+                    // Missing/deleted/invalid selected profile: no profile memory source.
+                }
+            }
+        }
+        else if (s === 'node') {
+            // The this-node store — a singleton dir in the node's context, no plugins.
+            // Silently absent when not running inside a node (CRTR_NODE_ID unset).
+            const nodeId = selectedNodeId();
+            if (nodeId !== '')
+                out.push({ scope: 'node', memoryDir: nodeMemoryDir(nodeId), plugins: [] });
+        }
+        else {
+            out.push({
+                scope: s,
+                memoryDir: scopeMemoryDir(s),
+                plugins: listInstalledPlugins(s).filter((p) => p.enabled),
+            });
+        }
+    }
+    return out;
+}
+function loadMemoryDoc(scope, path, fallbackName) {
+    const { data, body } = parseFrontmatterGeneric(readText(path));
+    return { name: resolveDocName(data, fallbackName), scope, path, frontmatter: data, body };
+}
+/** All memory docs in one memory/ dir, scanned recursively for *.md (topical
+ *  subdirs supported), sorted by resolver identity (explicit frontmatter name
+ *  when present, else path-derived). SKILL.md bundles are legacy Agent Skills
+ *  and are ignored; crouter memory docs are plain .md files under memory/. */
+function listMemoryDocsInDir(scope, dir, quiet = false) {
+    if (!dir || !pathExists(dir))
+        return [];
+    const docs = [];
+    const found = [];
+    const stack = [dir];
+    while (stack.length) {
+        const d = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            // Enumeration stops at store boundaries: a nested `.crouter/` is another
+            // scope's mount point (e.g. a dir-scoped store inside a dir that is itself
+            // a store, like builtin-memory in the crouter repo), never this store's
+            // own content — walking into it would register a different tier's docs.
+            if (e.isDirectory()) {
+                if (e.name !== CRTR_DIR_NAME)
+                    stack.push(join(d, e.name));
+            }
+            else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'SKILL.md') {
+                const file = join(d, e.name);
+                const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+                const name = normalizeDocName(raw);
+                if (name)
+                    found.push({ path: file, name });
+            }
+        }
+    }
+    for (const { path, name } of found) {
+        // COLLECTION layer: the strict frontmatter parser throws on invalid YAML.
+        // Isolate one malformed doc with a clear scoped notice + skip, so a single
+        // bad file can't brick `memory list`/`find` or the substrate boot render.
+        // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
+        // where another doc's health is irrelevant noise before the result.
+        try {
+            docs.push(loadMemoryDoc(scope, path, name));
+        }
+        catch (e) {
+            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+            if (!quiet)
+                warn(`invalid frontmatter in ${path}: ${msg}`);
+        }
+    }
+    return docs.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** All native memory docs for a scope. Project scope is a nearest-first stack of
+ *  every ancestor `.crouter/memory/` (widened by a selected profile's project
+ *  stack); profile is the selected profile's own singleton store, resolved
+ *  through `loadProfileManifest`; user and builtin are singleton stores. */
+export function listMemoryDocs(scope, quiet = false) {
+    if (scope === 'project') {
+        return projectScopeRoots().flatMap((root) => listMemoryDocsInDir('project', join(root, 'memory'), quiet));
+    }
+    if (scope === 'profile') {
+        const profileId = selectedProfileId();
+        if (profileId === '')
+            return [];
+        try {
+            const { profileId: resolvedId } = loadProfileManifest(profileId);
+            return listMemoryDocsInDir('profile', profileMemoryDir(resolvedId), quiet);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (scope === 'node') {
+        const nodeId = selectedNodeId();
+        if (nodeId === '')
+            return [];
+        return listMemoryDocsInDir('node', nodeMemoryDir(nodeId), quiet);
+    }
+    return listMemoryDocsInDir(scope, scopeMemoryDir(scope), quiet);
+}
+/** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
+ *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
+ *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
+ *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
+export function listPluginMemoryDocs(plugin, scope, quiet = false) {
+    const dir = pluginMemoryDir(plugin);
+    if (!pathExists(dir))
+        return [];
+    const docs = [];
+    for (const file of walkFiles(dir, (n) => n.endsWith('.md') && n !== 'SKILL.md', (d) => d === CRTR_DIR_NAME)) {
+        const derived = normalizeDocName(relative(dir, file).replace(/\.md$/i, '').split(sep).join('/'));
+        if (!derived)
+            continue;
+        const name = `${plugin.name}/${derived}`;
+        try {
+            docs.push({ ...loadMemoryDoc(scope, file, name), plugin: plugin.name });
+        }
+        catch (e) {
+            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+            if (!quiet)
+                warn(`invalid frontmatter in ${file}: ${msg}`);
+        }
+    }
+    return docs.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** All docs belonging to a single resolved source: native docs first, then
+ *  enabled-plugin docs — native wins on a first-wins dedup within the source.
+ *  Shared by `listAllMemoryDocs` (flattens every source) and `resolveMemoryDoc`
+ *  (consults one source's docs at a time, nearest source first). */
+function sourceMemoryDocs(source, quiet = false) {
+    return [
+        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
+        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
+    ];
+}
+/** All memory docs across the resolved sources, in precedence order: each
+ *  ancestor project `.crouter/` from nearest to farthest, then the selected
+ *  profile's memory (if any), then user, then builtin. Within each source,
+ *  native docs are emitted before enabled-plugin docs, so native wins on the
+ *  caller's first-wins dedup. */
+export function listAllMemoryDocs(scope, quiet = false) {
+    return memorySourcesInPrecedence(scope).flatMap((source) => sourceMemoryDocs(source, quiet));
+}
+/** Find the direct child of `dir` — a `.md` file (matched on name minus
+ *  extension) or a directory — whose NORMALIZED display name equals
+ *  `segment`. An exact literal match (no prefix to strip) wins over a
+ *  normalized match, so a `spine` dir sitting beside a `01-spine` dir (a
+ *  malformed corpus) never masks the literal one; a well-formed corpus has at
+ *  most one candidate either way. Returns the absolute child path, or null. */
+function matchNormalizedChild(dir, segment, want) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    let normalizedHit = null;
+    for (const e of entries) {
+        if (want === 'dir') {
+            if (!e.isDirectory())
+                continue;
+            if (e.name === segment)
+                return join(dir, e.name);
+            if (normalizedHit === null && normalizeNameSegment(e.name) === segment) {
+                normalizedHit = join(dir, e.name);
+            }
+        }
+        else {
+            if (!(e.isFile() && e.name.endsWith('.md')))
+                continue;
+            const base = e.name.slice(0, -3);
+            if (base === segment)
+                return join(dir, e.name);
+            if (normalizedHit === null && normalizeNameSegment(base) === segment) {
+                normalizedHit = join(dir, e.name);
+            }
+        }
+    }
+    return normalizedHit;
+}
+/** Resolve a NORMALIZED (numeric-prefix-stripped) segment path against a
+ *  physical memory dir: walk intermediate segments matching each as a
+ *  directory by normalized name, then resolve the final segment as either a
+ *  `.md` file or a directory (the bare-dir -> INDEX.md fallback needs the dir
+ *  match even when a same-named file also exists). Either half is null when
+ *  the segment path does not resolve that way. This is what makes
+ *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
+ *  findable as `spine/has-manager` — the physical path keeps its pins, only
+ *  lookup is prefix-blind. */
+function resolveNormalizedPath(baseDir, segments) {
+    let curDir = baseDir;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const next = matchNormalizedChild(curDir, segments[i], 'dir');
+        if (!next)
+            return { filePath: null, dirPath: null };
+        curDir = next;
+    }
+    const last = segments[segments.length - 1];
+    return {
+        filePath: matchNormalizedChild(curDir, last, 'file'),
+        dirPath: matchNormalizedChild(curDir, last, 'dir'),
+    };
+}
+/** Direct full-path lookup of memory/<name>.md within ONE source. Returns that
+ *  source's single hit, or undefined — a source can produce at most one direct
+ *  match (native wins over plugin within the source, and at most one plugin's
+ *  name can match).
+ *
+ *  A directory INDEX is the cleaner contract: when `<name>.md` is absent but
+ *  `<name>/INDEX.md` exists, the bare dir name (`taste`) resolves to the dir's
+ *  INDEX doc — carrying the dir name as its identity. (`taste/INDEX` still
+ *  resolves directly as the file path.)
+ *
+ *  `name`'s segments are already normalized (a caller-supplied identifier is
+ *  never authored with a numeric prefix); resolution against the physical tree
+ *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
+ *  `NN-`-pinned physical file/dir. */
+function findMemoryMatchInSource(name, segments, source) {
+    const isLegacySkillDoc = segments.at(-1) === 'SKILL';
+    // Native memory dir first inside this source (native-before-plugin
+    // precedence), then its enabled plugins.
+    const dir = source.memoryDir;
+    if (dir) {
+        const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
+        if (!isLegacySkillDoc && filePath !== null)
+            return loadMemoryDoc(source.scope, filePath, name);
+        if (dirPath !== null) {
+            const indexPath = join(dirPath, 'INDEX.md');
+            if (pathExists(indexPath))
+                return loadMemoryDoc(source.scope, indexPath, name);
+        }
+    }
+    // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
+    // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
+    // enumerates — `read` must resolve what `list` shows). A BARE plugin name
+    // (no slash) resolves the plugin-root INDEX.md, mirroring the native
+    // bare-dir-name -> INDEX.md contract for the plugin mount root.
+    const slash = name.indexOf('/');
+    const pluginName = slash > 0 ? name.slice(0, slash) : name;
+    const rest = slash > 0 ? name.slice(slash + 1) : '';
+    for (const p of source.plugins) {
+        if (p.name !== pluginName)
+            continue;
+        const pdir = pluginMemoryDir(p);
+        const restSegments = rest ? rest.split('/') : [];
+        if (rest) {
+            const { filePath } = resolveNormalizedPath(pdir, restSegments);
+            if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
+                return loadMemoryDoc(source.scope, filePath, name);
+        }
+        // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
+        const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
+        if (pIndexDir !== null) {
+            const pindex = join(pIndexDir, 'INDEX.md');
+            if (pathExists(pindex))
+                return loadMemoryDoc(source.scope, pindex, name);
+        }
+    }
+    return undefined;
+}
+function formatLeafAmbiguous(leaf, matches) {
+    const ids = matches.map(memoryDocId).join(', ');
+    return `ambiguous memory document: ${leaf} matches multiple documents: ${ids}`;
+}
+/**
+ * Resolve a memory document name to a single memory document.
+ *
+ * Accepted identifier forms:
+ *   <name>            — bare name; resolved by scope precedence project>user>builtin
+ *   <scope>/<name>    — pinned to one scope (user|project)
+ * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
+ * back to a last-segment match within the resolved scopes.
+ *
+ * Precedence is the outer loop: sources are visited nearest-first, and the
+ * FIRST source with any hit wins outright — a farther source is never even
+ * consulted once a nearer one matches. Within each source, in order: (1)
+ * exact substrate-identity match (`doc.name === query` — the explicit
+ * frontmatter `name`, else its normalized path-derived fallback, the SAME
+ * identity `listAllMemoryDocs` reports); (2) direct `memory/<name>.md`
+ * physical-path lookup (the bare-dir → INDEX.md and bare-plugin-name → plugin
+ * root INDEX.md conveniences neither identity nor a literal path expresses);
+ * (3) bare leaf-name fallback (final path segment), ambiguous only when two
+ * DIFFERENT identities in the SAME source share a leaf.
+ *
+ * `opts.kind`, when given, is a resolution CONSTRAINT, not a post-filter: at
+ * each of the three steps above, a candidate whose `effectiveDocKind` doesn't
+ * match is skipped rather than accepted, so a nearer source's wrong-kind doc
+ * no longer shadows a farther source's matching-kind doc — resolution simply
+ * keeps walking outward. A source only counts as having "an answer" once a
+ * kind-matching candidate is found.
+ */
+export function resolveMemoryDoc(rawName, opts = {}) {
+    const parsed = parseSkillQualifier(rawName);
+    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
+        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
+    }
+    const effectiveScope = opts.scope ?? parsed.scope;
+    const name = parsed.segments.join('/');
+    if (name === '')
+        throw usage(`memory document name required`);
+    const segments = name.split('/');
+    const isLeafQuery = !name.includes('/');
+    for (const source of memorySourcesInPrecedence(effectiveScope)) {
+        // Quiet: a targeted read must not spew other docs' frontmatter warnings
+        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
+        const docs = sourceMemoryDocs(source, true);
+        const kindOk = (d) => opts.kind === undefined || effectiveDocKind(d) === opts.kind;
+        const identity = docs.find((d) => d.name === name);
+        if (identity && kindOk(identity))
+            return identity;
+        const direct = findMemoryMatchInSource(name, segments, source);
+        if (direct && kindOk(direct))
+            return direct;
+        if (isLeafQuery) {
+            const leafMatches = docs.filter((d) => (d.name.split('/').pop() ?? d.name) === name && kindOk(d));
+            if (leafMatches.length > 0) {
+                // Same path-derived name within this source → precedence wins (return
+                // first); genuinely different docs sharing a leaf → ambiguous. Either
+                // way this source has an answer — a farther source is never checked.
+                const distinctNames = new Set(leafMatches.map((d) => d.name));
+                if (distinctNames.size === 1)
+                    return leafMatches[0];
+                throw ambiguous(formatLeafAmbiguous(name, leafMatches), {
+                    memory: name,
+                    candidates: leafMatches.map((d) => ({
+                        id: memoryDocId(d),
+                        scope: d.scope,
+                        path: d.path,
+                    })),
+                    next: 'Multiple documents share this leaf name. Re-run with one of the full names in candidates.',
+                });
+            }
+        }
+    }
+    throw notFound(`memory document not found: ${rawName}`, {
+        memory: name,
+        scope: parsed.scope,
+    });
+}

package/dist/core/output.d.ts

@@ -0,0 +1,35 @@
+import { CrtrError } from './errors.js';
+export declare const stdoutColor: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare const stderrColor: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare function out(line: string): void;
+export declare function err(line: string): void;
+export declare function hint(line: string): void;
+export declare function warn(line: string): void;
+export declare function info(line: string): void;
+export declare function jsonOut(obj: unknown): void;
+export declare function jsonError(error: CrtrError | Error): void;
+export declare function isTTY(): boolean;
+export declare function isJsonRequested(opts: {
+    json?: boolean;
+} | undefined): boolean;
+export declare function handleError(error: unknown, opts?: {
+    json?: boolean;
+}): never;

package/dist/core/output.js

@@ -0,0 +1,99 @@
+import { CrtrError } from './errors.js';
+import { ExitCode, SCHEMA_VERSION } from '../types.js';
+const ANSI = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function shouldColor(stream) {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(stream.isTTY);
+}
+function paint(stream, code, text) {
+    return shouldColor(stream) ? `${code}${text}${ANSI.reset}` : text;
+}
+export const stdoutColor = {
+    dim: (s) => paint(process.stdout, ANSI.dim, s),
+    bold: (s) => paint(process.stdout, ANSI.bold, s),
+    red: (s) => paint(process.stdout, ANSI.red, s),
+    green: (s) => paint(process.stdout, ANSI.green, s),
+    yellow: (s) => paint(process.stdout, ANSI.yellow, s),
+    blue: (s) => paint(process.stdout, ANSI.blue, s),
+    cyan: (s) => paint(process.stdout, ANSI.cyan, s),
+    gray: (s) => paint(process.stdout, ANSI.gray, s),
+};
+export const stderrColor = {
+    dim: (s) => paint(process.stderr, ANSI.dim, s),
+    bold: (s) => paint(process.stderr, ANSI.bold, s),
+    red: (s) => paint(process.stderr, ANSI.red, s),
+    green: (s) => paint(process.stderr, ANSI.green, s),
+    yellow: (s) => paint(process.stderr, ANSI.yellow, s),
+    blue: (s) => paint(process.stderr, ANSI.blue, s),
+    cyan: (s) => paint(process.stderr, ANSI.cyan, s),
+    gray: (s) => paint(process.stderr, ANSI.gray, s),
+};
+export function out(line) {
+    process.stdout.write(line.endsWith('\n') ? line : line + '\n');
+}
+export function err(line) {
+    process.stderr.write(line.endsWith('\n') ? line : line + '\n');
+}
+export function hint(line) {
+    err(stderrColor.dim(`# ${line}`));
+}
+export function warn(line) {
+    err(stderrColor.yellow(`crtr: ${line}`));
+}
+export function info(line) {
+    err(stderrColor.gray(`crtr: ${line}`));
+}
+export function jsonOut(obj) {
+    const enriched = typeof obj === 'object' && obj !== null && !Array.isArray(obj)
+        ? { schema_version: SCHEMA_VERSION, ...obj }
+        : { schema_version: SCHEMA_VERSION, data: obj };
+    process.stdout.write(JSON.stringify(enriched, null, 2) + '\n');
+}
+export function jsonError(error) {
+    const e = error instanceof CrtrError ? error : new CrtrError('error', error.message, ExitCode.GENERAL);
+    process.stdout.write(JSON.stringify({
+        schema_version: SCHEMA_VERSION,
+        error: true,
+        code: e.code,
+        message: e.message,
+        ...(e.details ?? {}),
+    }, null, 2) + '\n');
+}
+export function isTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+export function isJsonRequested(opts) {
+    return Boolean(opts?.json);
+}
+export function handleError(error, opts = {}) {
+    if (error instanceof CrtrError) {
+        if (opts.json) {
+            jsonError(error);
+        }
+        else {
+            err(stderrColor.red(`crtr: ${error.message}`));
+        }
+        process.exit(error.exitCode);
+    }
+    const e = error;
+    if (opts.json) {
+        jsonError(e);
+    }
+    else {
+        err(stderrColor.red(`crtr: ${e.message ?? String(e)}`));
+    }
+    process.exit(ExitCode.GENERAL);
+}

package/dist/core/pagination.d.ts

@@ -0,0 +1,33 @@
+/** Encodes a stable sort key into an opaque base64url cursor token. */
+export declare function encodeCursor(key: string): string;
+/** Decodes an opaque cursor token back to the sort key it encodes.
+ *  Throws `CrtrError` with code `'invalid_cursor'` on malformed input. */
+export declare function decodeCursor(token: string): string;
+export interface PaginateResult<T> {
+    items: T[];
+    next_cursor: string | null;
+    total: number | null;
+}
+export interface PaginateOpts<T> {
+    /** Default page size when `params.limit` is absent. */
+    defaultLimit: number;
+    /** Hard cap; `params.limit` is clamped to [1, maxLimit]. */
+    maxLimit: number;
+    /** Returns the stable sort key for an item. Must match the sort order of the
+     *  input array — ascending by this key. */
+    keyOf: (item: T) => string;
+    /** 'count' → compute and return `total`; 'omit' → return `null`. */
+    total: 'count' | 'omit';
+}
+/**
+ * Returns one page of items from a pre-sorted list, with a stable opaque
+ * cursor for resumption.
+ *
+ * @param allItemsSortedAscByKey - Full dataset, sorted ascending by `keyOf`.
+ * @param params - Agent-supplied `{ limit?, cursor? }` from stdin.
+ * @param opts - Caller-supplied configuration (limits, key extractor, total).
+ */
+export declare function paginate<T>(allItemsSortedAscByKey: T[], params: {
+    limit?: number;
+    cursor?: string;
+}, opts: PaginateOpts<T>): PaginateResult<T>;

package/dist/core/pagination.js

@@ -0,0 +1,89 @@
+// Pagination helper for agent-facing paginated list leaves.
+//
+// Precondition: `allItemsSortedAscByKey` MUST be sorted ascending by the value
+// `keyOf` returns. Sort order is part of each leaf's contract — this module
+// trusts the caller. Violating the precondition produces silently wrong pages.
+//
+// Cursor design: encodes the stable sort key of the last-emitted item as
+// base64url JSON `{k: <sortKey>}`. Resumption seeks the first item whose key
+// is strictly greater than the cursor key — stable under inserts and deletes
+// between pages (a deleted cursor key simply doesn't stall the scan; the next
+// item after it is returned correctly).
+import { CrtrError } from './errors.js';
+import { ExitCode } from '../types.js';
+// ---------------------------------------------------------------------------
+// Cursor encoding / decoding
+// ---------------------------------------------------------------------------
+/** Encodes a stable sort key into an opaque base64url cursor token. */
+export function encodeCursor(key) {
+    const json = JSON.stringify({ k: key });
+    return Buffer.from(json, 'utf8').toString('base64url');
+}
+/** Decodes an opaque cursor token back to the sort key it encodes.
+ *  Throws `CrtrError` with code `'invalid_cursor'` on malformed input. */
+export function decodeCursor(token) {
+    let json;
+    try {
+        json = Buffer.from(token, 'base64url').toString('utf8');
+    }
+    catch {
+        throw new CrtrError('invalid_cursor', 'cursor could not be decoded.', ExitCode.USAGE, {
+            received: token,
+            next: 'Omit cursor to restart from the beginning.',
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new CrtrError('invalid_cursor', 'cursor payload is not valid JSON.', ExitCode.USAGE, {
+            received: token,
+            next: 'Omit cursor to restart from the beginning.',
+        });
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('k' in parsed) ||
+        typeof parsed.k !== 'string') {
+        throw new CrtrError('invalid_cursor', 'cursor payload is missing required key field.', ExitCode.USAGE, {
+            received: token,
+            next: 'Omit cursor to restart from the beginning.',
+        });
+    }
+    return parsed.k;
+}
+/**
+ * Returns one page of items from a pre-sorted list, with a stable opaque
+ * cursor for resumption.
+ *
+ * @param allItemsSortedAscByKey - Full dataset, sorted ascending by `keyOf`.
+ * @param params - Agent-supplied `{ limit?, cursor? }` from stdin.
+ * @param opts - Caller-supplied configuration (limits, key extractor, total).
+ */
+export function paginate(allItemsSortedAscByKey, params, opts) {
+    // Resolve effective limit: clamp to [1, maxLimit], default when absent.
+    const rawLimit = params.limit !== undefined ? params.limit : opts.defaultLimit;
+    const effectiveLimit = Math.min(Math.max(1, rawLimit), opts.maxLimit);
+    // Resolve start position from cursor.
+    let startIndex = 0;
+    if (params.cursor !== undefined) {
+        const cursorKey = decodeCursor(params.cursor); // throws CrtrError on bad cursor
+        // Find the first item whose key is strictly greater than cursorKey.
+        // Linear scan; callers with large datasets should pre-filter upstream.
+        startIndex = allItemsSortedAscByKey.findIndex((item) => opts.keyOf(item) > cursorKey);
+        if (startIndex === -1) {
+            // All items are at or before the cursor key — list is exhausted.
+            startIndex = allItemsSortedAscByKey.length;
+        }
+    }
+    const page = allItemsSortedAscByKey.slice(startIndex, startIndex + effectiveLimit);
+    // next_cursor: null is the ONLY end-of-list signal.
+    let next_cursor = null;
+    if (page.length === effectiveLimit && startIndex + effectiveLimit < allItemsSortedAscByKey.length) {
+        const lastKey = opts.keyOf(page[page.length - 1]);
+        next_cursor = encodeCursor(lastKey);
+    }
+    const total = opts.total === 'count' ? allItemsSortedAscByKey.length : null;
+    return { items: page, next_cursor, total };
+}