@north-light/crouter 0.3.154

package/dist/core/log.js

@@ -0,0 +1,27 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const MAX_ROTATING_RECORD_BYTES = 65_536;
+const MAX_ACTIVE_BYTES = 5 * 1024 * 1024;
+/** Synchronously appends one complete NDJSON record, retaining active + .1 + .2. */
+export function appendRotatingRecord(path, recordWithoutLf) {
+    if (recordWithoutLf.includes('\n') || recordWithoutLf.includes('\r'))
+        return false;
+    const lineBytes = Buffer.byteLength(recordWithoutLf, 'utf8') + 1;
+    if (lineBytes > MAX_ROTATING_RECORD_BYTES)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const currentBytes = existsSync(path) ? statSync(path).size : 0;
+        if (currentBytes + lineBytes > MAX_ACTIVE_BYTES && currentBytes > 0) {
+            rmSync(`${path}.2`, { force: true });
+            if (existsSync(`${path}.1`))
+                renameSync(`${path}.1`, `${path}.2`);
+            renameSync(path, `${path}.1`);
+        }
+        appendFileSync(path, `${recordWithoutLf}\n`, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,5 @@
+import type { MarketplaceManifest, PluginManifest } from '../types.js';
+export declare function pluginManifestPath(pluginRoot: string): string;
+export declare function marketplaceManifestPath(mktRoot: string): string;
+export declare function readPluginManifest(pluginRoot: string): PluginManifest | null;
+export declare function readMarketplaceManifest(mktRoot: string): MarketplaceManifest | null;

package/dist/core/manifest.js

@@ -0,0 +1,15 @@
+import { join } from 'node:path';
+import { MARKETPLACE_MANIFEST_DIR, MARKETPLACE_MANIFEST_FILE, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE, } from '../types.js';
+import { readJsonIfExists } from './fs-utils.js';
+export function pluginManifestPath(pluginRoot) {
+    return join(pluginRoot, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
+}
+export function marketplaceManifestPath(mktRoot) {
+    return join(mktRoot, MARKETPLACE_MANIFEST_DIR, MARKETPLACE_MANIFEST_FILE);
+}
+export function readPluginManifest(pluginRoot) {
+    return readJsonIfExists(pluginManifestPath(pluginRoot));
+}
+export function readMarketplaceManifest(mktRoot) {
+    return readJsonIfExists(marketplaceManifestPath(mktRoot));
+}

package/dist/core/memory/inline-ref-grammar.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A candidate slash token found in free text by `findRefTokens`. This is the
+ * NORMATIVE, trimmed span used for resolution and highlighting.
+ */
+export interface RefToken {
+    /** Character index of the leading `/`. */
+    start: number;
+    /** Character index just past the last kept name character (post-trim). */
+    end: number;
+    /** The surface token including `/`, trailing punctuation already trimmed. */
+    raw: string;
+    /** Decoded canonical name (`:` → `/`); never empty (empty candidates are omitted). */
+    candidate: string;
+}
+/**
+ * The in-progress token touching a caret position, as reported by
+ * `findRefTokenAtCaret`. Its `[start, end)` range is the COMPLETE captured
+ * replacement range (the maximal, UNTRIMMED `[A-Za-z0-9_:-]` run) — not the
+ * trimmed `RefToken` span — so a completion accept can replace an
+ * in-progress token like `/taste:` (no trailing name segment yet) or a token
+ * the caret sits in the middle of (suffix-inclusive). The normative resolved
+ * span for highlighting/guidance always remains `findRefTokens`' trimmed span;
+ * this helper exists only to drive completion UX.
+ */
+export interface RefCaretToken {
+    /** Character index of the leading `/`. */
+    start: number;
+    /** Character index just past the last character of the maximal (untrimmed) run. */
+    end: number;
+    /** The slash/name prefix from `start` through the caret (`text.slice(start, caret)`). */
+    surfacePrefix: string;
+}
+/**
+ * Find every resolved-ref CANDIDATE in `text` per the §4.1 grammar. Does not
+ * consult any inventory — callers resolve a token by testing
+ * `token.candidate` against a `Set<string>` of visible canonical names.
+ */
+export declare function findRefTokens(text: string): RefToken[];
+/**
+ * Render a canonical name back into its surface slash-token form:
+ * `'dev' -> '/dev'`, `'taste/foo' -> '/taste:foo'`.
+ */
+export declare function formatRefToken(canonicalName: string): string;
+/**
+ * Classify the in-progress token (if any) touching `caret` in `text`, for
+ * completion UX. Reuses the same whitespace/name-char predicates as
+ * `findRefTokens`, but reports the UNTRIMMED maximal run so an incomplete
+ * prefix (`/taste:` with nothing typed after the colon yet) or a caret sitting
+ * mid-token (with more valid characters after it) both produce a full,
+ * suffix-inclusive replacement range. Returns `null` when the caret is not
+ * touching a token-shaped run.
+ */
+export declare function findRefTokenAtCaret(text: string, caret: number): RefCaretToken | null;

package/dist/core/memory/inline-ref-grammar.js

@@ -0,0 +1,99 @@
+// inline-ref-grammar.ts — the single source of truth for the inline
+// memory-reference token grammar (spec §4.1). Zero imports, pure string ops,
+// browser-safe: the broker, the terminal attach viewer, and the web composer
+// all import THIS module (directly, or via the browser barrel re-export in
+// `src/web/index.ts`) rather than each re-implementing `[A-Za-z0-9_:-]`,
+// trimming, boundary detection, or `:` decoding. Divergence between the
+// viewer's highlight rule and the broker's resolution rule would let a
+// highlighted token yield no guidance (or vice versa) — see the spec and
+// `/Users/silasrhyneer/.crouter/canvas/nodes/3zl47w7d-mrxwyqvr-73569670/context/design-inline-memory-references.md`.
+//
+// This module never resolves anything: `findRefTokens` and
+// `findRefTokenAtCaret` return candidate tokens; a caller decides a token is a
+// *resolved ref* only when `candidate` is an exact, case-sensitive member of
+// the broker-supplied inventory `Set<string>` of visible canonical names.
+// §4.1 step 2: the maximal run captured after a token-starting `/`.
+const NAME_CHAR = /[A-Za-z0-9_:-]/;
+// §4.1 step 3: a run must trim down to end on one of these to survive.
+const KEEP_CHAR = /[A-Za-z0-9]/;
+// §4.1 step 1: "ASCII whitespace" only — not the broader Unicode `\s` class.
+const ASCII_WHITESPACE = /[ \t\n\r\f\v]/;
+function isNameChar(ch) {
+    return NAME_CHAR.test(ch);
+}
+function isAsciiWhitespace(ch) {
+    return ASCII_WHITESPACE.test(ch);
+}
+// A `/` at `index` is a valid token start iff it is at the very start of the
+// string or immediately preceded by an ASCII whitespace character. This is
+// what makes `http://x`, `and/or`, and `/usr/local/bin`'s later segments
+// non-triggers by construction (§4.1 step 1).
+function isTokenStart(text, index) {
+    return index === 0 || isAsciiWhitespace(text[index - 1]);
+}
+/**
+ * Find every resolved-ref CANDIDATE in `text` per the §4.1 grammar. Does not
+ * consult any inventory — callers resolve a token by testing
+ * `token.candidate` against a `Set<string>` of visible canonical names.
+ */
+export function findRefTokens(text) {
+    const tokens = [];
+    const len = text.length;
+    for (let i = 0; i < len; i++) {
+        if (text[i] !== '/' || !isTokenStart(text, i))
+            continue;
+        // Step 2: capture the maximal run of [A-Za-z0-9_:-] after the slash.
+        let j = i + 1;
+        while (j < len && isNameChar(text[j]))
+            j++;
+        if (j === i + 1)
+            continue; // nothing captured at all
+        // Step 3: trim trailing characters that are not [A-Za-z0-9].
+        let end = j;
+        while (end > i + 1 && !KEEP_CHAR.test(text[end - 1]))
+            end--;
+        if (end === i + 1)
+            continue; // nothing survives the trim
+        const raw = text.slice(i, end);
+        // Step 4: decode ':' -> '/'.
+        const candidate = raw.slice(1).replace(/:/g, '/');
+        tokens.push({ start: i, end, raw, candidate });
+    }
+    return tokens;
+}
+/**
+ * Render a canonical name back into its surface slash-token form:
+ * `'dev' -> '/dev'`, `'taste/foo' -> '/taste:foo'`.
+ */
+export function formatRefToken(canonicalName) {
+    return '/' + canonicalName.replace(/\//g, ':');
+}
+/**
+ * Classify the in-progress token (if any) touching `caret` in `text`, for
+ * completion UX. Reuses the same whitespace/name-char predicates as
+ * `findRefTokens`, but reports the UNTRIMMED maximal run so an incomplete
+ * prefix (`/taste:` with nothing typed after the colon yet) or a caret sitting
+ * mid-token (with more valid characters after it) both produce a full,
+ * suffix-inclusive replacement range. Returns `null` when the caret is not
+ * touching a token-shaped run.
+ */
+export function findRefTokenAtCaret(text, caret) {
+    const len = text.length;
+    const pos = Math.max(0, Math.min(caret, len));
+    // Walk backward from the caret to the start of the contiguous name-char
+    // run it sits in (or after); the token's slash must sit immediately
+    // before that run.
+    let nameStart = pos;
+    while (nameStart > 0 && isNameChar(text[nameStart - 1]))
+        nameStart--;
+    const slashPos = nameStart - 1;
+    if (slashPos < 0 || text[slashPos] !== '/' || !isTokenStart(text, slashPos))
+        return null;
+    // The maximal run from the slash is a single scan forward — equivalent to
+    // walking both directions from the caret, since the run is contiguous by
+    // construction (NAME_CHAR excludes '/' and whitespace).
+    let end = slashPos + 1;
+    while (end < len && isNameChar(text[end]))
+        end++;
+    return { start: slashPos, end, surfacePrefix: text.slice(slashPos, pos) };
+}

package/dist/core/memory/inline-ref-guidance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve every slash token in `text` against `names` (a
+ * `buildRefInventory().names` set), collapse duplicates, and return one
+ * directive line per distinct resolved ref in FIRST-APPEARANCE order.
+ * Returns `null` when no token resolves, so the broker sends no guidance
+ * message for prose with no refs.
+ */
+export declare function buildGuidance(text: string, names: Set<string>): string | null;

package/dist/core/memory/inline-ref-guidance.js

@@ -0,0 +1,35 @@
+// inline-ref-guidance.ts — builds the single hidden directive message the
+// broker hands the model when a human submission contains one or more
+// resolved inline memory references (spec §4.6, design "Guidance builder").
+//
+// Pure over its inputs: given the verbatim frame text and the inventory's
+// resolution `Set<string>`, this module never re-resolves scope, never
+// touches the filesystem, and never depends on which viewer sent the text.
+// The broker (src/core/runtime/broker.ts) is the only caller — it wraps the
+// returned string in a `{ role: 'custom', customType: 'crtr-memory-refs',
+// display: false, ... }` message and delivers it alongside the human turn.
+import { findRefTokens } from './inline-ref-grammar.js';
+const GUIDANCE_HEADER = 'The human explicitly referenced these memory documents. Before acting on the portion of their message that references each document, run the corresponding command and treat its returned content as authoritative context:';
+/**
+ * Resolve every slash token in `text` against `names` (a
+ * `buildRefInventory().names` set), collapse duplicates, and return one
+ * directive line per distinct resolved ref in FIRST-APPEARANCE order.
+ * Returns `null` when no token resolves, so the broker sends no guidance
+ * message for prose with no refs.
+ */
+export function buildGuidance(text, names) {
+    const seen = new Set();
+    const resolved = [];
+    for (const token of findRefTokens(text)) {
+        if (seen.has(token.candidate))
+            continue;
+        if (!names.has(token.candidate))
+            continue;
+        seen.add(token.candidate);
+        resolved.push(token.candidate);
+    }
+    if (resolved.length === 0)
+        return null;
+    const lines = resolved.map((name) => `- crtr memory read ${name}`);
+    return [GUIDANCE_HEADER, ...lines].join('\n');
+}

package/dist/core/memory/inline-ref-inventory.d.ts

@@ -0,0 +1,13 @@
+import type { RefMeta } from '../runtime/broker-protocol.js';
+/**
+ * Build the inline memory-reference inventory: every referenceable document
+ * in this node's corpus, precedence-deduped first-wins by canonical name,
+ * both kinds, no gate/rung/`slash` filtering, INDEX docs folded to their bare
+ * directory name. Returns display metadata (`refs`, stably sorted by winning
+ * scope then name) plus the resolution set (`names`) that both the broker's
+ * per-submission resolver and `buildGuidance` test tokens against.
+ */
+export declare function buildRefInventory(): {
+    refs: RefMeta[];
+    names: Set<string>;
+};

package/dist/core/memory/inline-ref-inventory.js

@@ -0,0 +1,79 @@
+// inline-ref-inventory.ts — the authoritative, broker-side inventory of
+// referenceable memory documents for inline memory references (design:
+// inline memory references, D2). Built from the SAME resolver + parse path
+// as every other memory surface (`listAllMemoryDocs` + `parseSubstrateDoc`,
+// via the session parse cache), reused verbatim rather than re-walked or
+// shelled out.
+//
+// This is deliberately NOT `crtr memory list`'s inventory:
+//   • listAllMemoryDocs() is called with NO scope arg, so inside a running
+//     node (CRTR_NODE_ID set) the corpus already includes node > project
+//     stack > profile > user > builtin, nearest first.
+//   • Dedup is first-wins by NAME alone (not `scope/name`) — a slash token
+//     maps to exactly one `crtr memory read <name>`, so two same-named docs
+//     at different scopes must collapse to one inventory row, and the
+//     winning (nearest) doc supplies the display fields.
+//   • No gate / visibility-rung / `slash` filtering. Referenceability is
+//     "resolves in this node's corpus," full stop — gates/rungs govern
+//     automatic boot/on-read surfacing only (spec §7.1), and `slash` governs
+//     command registration only (spec §4.3). An explicit human reference
+//     outranks both.
+//   • A directory's INDEX doc folds to its bare directory name (`taste`, not
+//     `taste/INDEX`), matching what `crtr memory read taste` accepts.
+//   • A malformed doc (no valid `kind`) is already dropped by
+//     `parseSubstrateDoc` returning null, so it never reaches the winners map.
+//
+// `buildRefInventory` is called fresh per read-op / per submission by the
+// broker (src/core/runtime/broker.ts), which memoizes it and rebuilds on
+// `/reload` — this module itself holds no cache beyond the session parse
+// cache it reads through.
+import { listAllMemoryDocs } from '../memory-resolver.js';
+import { parseSubstrateDoc } from '../substrate/schema.js';
+import { displayName } from '../substrate/ceiling.js';
+import { cachedSubstrateDocsInclusive } from '../substrate/session-cache.js';
+// Display-sort weight matching resolution precedence (node > project >
+// profile > user > builtin) — display-only; resolution itself is
+// name-only (`names.has(candidate)`), never scope-aware.
+const SCOPE_SORT_RANK = {
+    node: 0,
+    project: 1,
+    profile: 2,
+    user: 3,
+    builtin: 4,
+};
+/**
+ * Build the inline memory-reference inventory: every referenceable document
+ * in this node's corpus, precedence-deduped first-wins by canonical name,
+ * both kinds, no gate/rung/`slash` filtering, INDEX docs folded to their bare
+ * directory name. Returns display metadata (`refs`, stably sorted by winning
+ * scope then name) plus the resolution set (`names`) that both the broker's
+ * per-submission resolver and `buildGuidance` test tokens against.
+ */
+export function buildRefInventory() {
+    const docs = cachedSubstrateDocsInclusive(listAllMemoryDocs, parseSubstrateDoc);
+    // First-wins by canonical (INDEX-folded) name: docs arrive already in
+    // precedence order (listAllMemoryDocs' nearest-first source ordering), so
+    // the first doc seen for a name is the winner.
+    const winners = new Map();
+    for (const doc of docs) {
+        const name = displayName(doc.name);
+        // A root INDEX folds to '' (no bare-directory token exists for it) and
+        // has no other nonempty canonical identity in this corpus, so it has
+        // no inline token to offer — omit it rather than expose `name: ''`.
+        if (name === '')
+            continue;
+        if (!winners.has(name))
+            winners.set(name, doc);
+    }
+    const refs = [];
+    for (const [name, doc] of winners) {
+        refs.push({ name, kind: doc.kind, scope: doc.scope, shortForm: doc.shortForm });
+    }
+    refs.sort((a, b) => {
+        const scopeDelta = SCOPE_SORT_RANK[a.scope] - SCOPE_SORT_RANK[b.scope];
+        if (scopeDelta !== 0)
+            return scopeDelta;
+        return a.name.localeCompare(b.name);
+    });
+    return { refs, names: new Set(refs.map((r) => r.name)) };
+}

package/dist/core/memory-resolver.d.ts

@@ -0,0 +1,106 @@
+import { type InstalledPlugin, type Scope } from '../types.js';
+/**
+ * Thin memory-document resolver for the document substrate. Precedence is the
+ * OUTER loop, not a global scan: scopes/sources are tried NEAREST-FIRST
+ * (node > project stack nearest > ... > profile > user > builtin), and WITHIN each
+ * source, in order: (1) exact substrate-identity match (`doc.name === query`
+ * — the explicit frontmatter `name`, or its path-derived fallback), (2) direct
+ * `memory/<name>.md` physical-path lookup (plus the bare-dir/bare-plugin-name
+ * → `INDEX.md` convenience neither identity nor a literal path expresses),
+ * (3) bare leaf-name fallback (final path segment only). The first hit wins,
+ * so a nearer source's match of ANY kind always beats a farther source's
+ * match of any kind — a farther-scope identity can never shadow a
+ * nearer-scope physical file. It returns the raw parsed frontmatter + body;
+ * it does NOT interpret the schema, kind, gate, or rungs — that is the
+ * schema/gate layer's job (callers filter by `frontmatter.kind`). Project
+ * resolution is a nearest-first stack of every ancestor `.crouter/` (widened by
+ * a selected profile's `projects` manifest entries — see `findProjectScopeRoots`
+ * in scope.ts), profile is the selected profile's own singleton `memory/` store
+ * (from `CRTR_PROFILE_ID`), and user/builtin remain singleton scopes.
+ */
+export interface MemoryDoc {
+    /** Resolver identity: the doc's explicit frontmatter `name` when present,
+     *  otherwise its normalized path under the scope's memory/ root — e.g.
+     *  memory/taste/foo.md → "taste/foo". */
+    name: string;
+    scope: MemoryScope;
+    /** Absolute path to the resolved .md file. */
+    path: string;
+    /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
+    frontmatter: Record<string, unknown> | null;
+    /** Document body, with the frontmatter block stripped. */
+    body: string;
+    /** Set to the owning plugin's name when this doc is mounted from an installed
+     *  plugin (under `<pluginName>/`), undefined for a native scope doc. Plugin
+     *  docs surface within a source scope but live under the plugins dir and are
+     *  managed by `crtr pkg`, not writable/deletable as scope docs — consumers
+     *  that mutate the store gate on this. */
+    plugin?: string;
+}
+/** The memory-only scope union: the global `Scope` (`user|project|builtin`)
+ *  plus `profile` and `node`. Confined to the memory resolver/list/read/write/
+ *  render paths — deliberately NOT folded into the global `Scope` union, because
+ *  that would leak these into config, plugin, marketplace, view, and doctor/
+ *  sys-config surfaces the spec does not extend. `node` is the this-node store
+ *  (`nodes/<id>/context/memory/`), available only inside a running node
+ *  (`CRTR_NODE_ID`), and it is the NEAREST scope — a node doc overrides a
+ *  same-named doc at any wider scope. */
+export type MemoryScope = Scope | 'profile' | 'node';
+export interface MemoryResolutionOpts {
+    /** Restrict resolution to a single scope. Conflicts with a scope prefix on
+     *  the identifier (e.g. `user/foo` with scope=project) throw. */
+    scope?: MemoryScope;
+    /** Restrict resolution to docs whose resolved kind matches. Threaded INTO
+     *  precedence, not applied as a post-resolution filter: within each source,
+     *  a doc whose kind doesn't match is skipped (not returned), so a nearer
+     *  source's wrong-kind doc can no longer shadow a farther source's
+     *  matching-kind doc into a false not_found — resolution simply continues
+     *  to the next source. See `effectiveDocKind` for the kind coercion. */
+    kind?: string;
+}
+/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
+export declare function memoryDocId(doc: MemoryDoc): string;
+/** 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 declare function listMemoryDocs(scope: MemoryScope, quiet?: boolean): MemoryDoc[];
+/** 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 declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: MemoryScope, quiet?: boolean): MemoryDoc[];
+/** 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 declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean): MemoryDoc[];
+/**
+ * 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 declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;