@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/core/scope.js

@@ -12,6 +12,26 @@ export function builtinSkillsRoot() {
     const pkgDir = dirname(coreDir); // src/ or dist/
     return join(pkgDir, 'builtin-skills');
 }
+export function builtinViewsRoot() {
+    // Resolved relative to this file exactly like builtinSkillsRoot — sibling of
+    // builtin-skills: dist/core/scope.js → dist/builtin-views/ (src/ at dev time).
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-views');
+}
+export function builtinMemoryRoot() {
+    // The substrate's shipped built-in documents live in their OWN package dir,
+    // a sibling of builtin-skills — resolved relative to this file exactly like
+    // builtinSkillsRoot/builtinViewsRoot: dist/core/scope.js → dist/builtin-memory/
+    // (src/ at dev time). This is a HARD special case (design verdict m2): builtin
+    // memory is NOT scopeRoot('builtin')/memory, which would land under
+    // builtin-skills/ — builtin's scopeRoot is builtinSkillsRoot().
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-memory');
+}
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
@@ -77,6 +97,25 @@ export function scopeSkillsDir(scope) {
     const root = scopeRoot(scope);
     return root ? join(root, 'skills') : null;
 }
+/** Where substrate memory documents live per scope. Builtin memory is the
+ *  special case — its own package dir (builtinMemoryRoot, a sibling of
+ *  builtin-skills), NOT scopeRoot('builtin')/memory — mirroring viewsDir's
+ *  builtin handling. User and project memory live at scopeRoot(scope)/memory. */
+export function scopeMemoryDir(scope) {
+    if (scope === 'builtin')
+        return builtinMemoryRoot();
+    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
+    return root ? join(root, 'memory') : null;
+}
+/** Where view definition dirs live per scope. Builtin views sit directly under
+ *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
+ *  matching the loader's `<root>/<name>/view.mjs` resolution. */
+export function viewsDir(scope) {
+    if (scope === 'builtin')
+        return builtinViewsRoot();
+    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
+    return root ? join(root, 'views') : null;
+}
 export function resolveScopeArg(scopeArg) {
     if (scopeArg === undefined)
         return 'all';

package/dist/core/spawn.d.ts

@@ -11,6 +11,11 @@ export declare function countPanesInCurrentWindow(): number;
  *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
  *  False outside tmux / on error. */
 export declare function paneAlive(pane: string): boolean;
+/** Resolve a tmux pane id to its `session:window_index` — the target form
+ *  `new-window -t` accepts. tmux REJECTS a pane id for new-window ("can't
+ *  specify pane here"); only split-window -t takes a pane. null outside tmux /
+ *  on a bad pane id / on error / empty. */
+export declare function paneWindowTarget(pane: string): string | null;
 /** The active pane of the user's attached tmux client — where they are looking
  *  right now. `list-clients` first attached client, then its current pane. Used
  *  to surface a human prompt in the user's view when nothing in the asking

package/dist/core/spawn.js

@@ -41,6 +41,19 @@ export function paneAlive(pane) {
     });
     return r.status === 0 && r.stdout.trim() !== '';
 }
+/** Resolve a tmux pane id to its `session:window_index` — the target form
+ *  `new-window -t` accepts. tmux REJECTS a pane id for new-window ("can't
+ *  specify pane here"); only split-window -t takes a pane. null outside tmux /
+ *  on a bad pane id / on error / empty. */
+export function paneWindowTarget(pane) {
+    if (!isInTmux() || !/^%\d+$/.test(pane))
+        return null;
+    const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{session_name}:#{window_index}'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    const t = r.stdout.trim();
+    return t !== '' ? t : null;
+}
 /** The active pane of the user's attached tmux client — where they are looking
  *  right now. `list-clients` first attached client, then its current pane. Used
  *  to surface a human prompt in the user's view when nothing in the asking
@@ -101,8 +114,13 @@ export function spawnAndDetach(opts) {
         if (opts.detached === true)
             splitArgs.push('-d'); // don't switch the client to it
         if (opts.targetPane !== undefined && opts.targetPane !== '') {
-            // -a = insert after target window; -t <pane> resolves to that pane's window.
-            splitArgs.push('-a', '-t', opts.targetPane);
+            // new-window -t REJECTS a pane id (tmux exits 1: "can't specify pane
+            // here") — only split-window -t accepts a pane. Resolve the target pane to
+            // its session:window first; -a then inserts the new window right after it.
+            // If the pane can't be resolved, fall back to no -t (tmux uses current).
+            const winTarget = paneWindowTarget(opts.targetPane);
+            if (winTarget !== null)
+                splitArgs.push('-a', '-t', winTarget);
         }
     }
     else {

package/dist/core/substrate/gate.d.ts

@@ -0,0 +1,13 @@
+import type { SubstrateDoc } from './schema.js';
+import type { NodeConfigSubject } from './subject.js';
+/** Does `doc` pass its gate for `subject`?
+ *
+ *  - No gate (field absent) ⇒ `true`: always eligible (the common case).
+ *  - A gate present ⇒ the matcher engine's verdict. An empty `gate: {}` is inert
+ *    and returns `false` (never matches) per design §4 — so an author cannot
+ *    write an always-eligible-via-empty-predicate doc.
+ *
+ *  Eligibility only. A failing gate excludes the doc from BOTH automatic hooks
+ *  for this node; it remains findable by `crtr memory find` (search ignores
+ *  gate + rung). */
+export declare function gatePasses(doc: SubstrateDoc, subject: NodeConfigSubject): boolean;

package/dist/core/substrate/gate.js

@@ -0,0 +1,21 @@
+// gate.ts — gate evaluation. A document's optional `gate` predicate decides
+// whether it is ELIGIBLE to surface at all for a given node (orthogonal to the
+// rung, which decides how much). See design-substrate.md §4 + §6. Pure function
+// over (parsed doc, assembled subject); the matcher engine in predicate.ts does
+// the actual matching — we do NOT reimplement it here.
+import { evalCondition } from '../predicate.js';
+/** Does `doc` pass its gate for `subject`?
+ *
+ *  - No gate (field absent) ⇒ `true`: always eligible (the common case).
+ *  - A gate present ⇒ the matcher engine's verdict. An empty `gate: {}` is inert
+ *    and returns `false` (never matches) per design §4 — so an author cannot
+ *    write an always-eligible-via-empty-predicate doc.
+ *
+ *  Eligibility only. A failing gate excludes the doc from BOTH automatic hooks
+ *  for this node; it remains findable by `crtr memory find` (search ignores
+ *  gate + rung). */
+export function gatePasses(doc, subject) {
+    if (doc.gate === undefined)
+        return true;
+    return evalCondition(doc.gate, subject);
+}

package/dist/core/substrate/index.d.ts

@@ -0,0 +1,7 @@
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, KIND_DEFAULT_RUNGS, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
+export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
+export type { NodeConfigSubject } from './subject.js';
+export { gatePasses } from './gate.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -0,0 +1,18 @@
+// substrate/ — the unified document-substrate keystone: the frontmatter schema,
+// the 4-rung visibility ladder, the kind→default-rungs table, the node-config
+// subject assembly, and gate evaluation. Pure + well-typed; the shared base the
+// CLI verbs, boot render, on-read render, and migrator all build on. See
+// design-substrate.md §4/§9 + plan-substrate.md §2.
+export { 
+// kinds
+KINDS, isDocKind, 
+// ladder
+RUNGS, rungRank, rungAtLeast, 
+// defaults
+KIND_DEFAULT_RUNGS, 
+// parse + render-shared helpers
+parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
+export { gatePasses } from './gate.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/on-read.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Render the substrate docs that should surface alongside a just-read file.
+ *
+ * @param nodeId        the canvas node whose subject gates the docs.
+ * @param readFilePath  the path the `read` tool returned (absolute or not — it
+ *                      is resolved to a realpath internally).
+ * @param seen          the CALLER-owned, per-session set of already-injected
+ *                      doc realpaths. Docs already present are skipped; newly
+ *                      injected docs are added. Pass the same set across reads
+ *                      within a session (clear it on session_start) to get the
+ *                      once-per-session dedup; omit it for a standalone render.
+ * @returns the `<auto-loaded-context>` envelope, or '' when nothing surfaces.
+ */
+export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: Set<string>): string;

package/dist/core/substrate/on-read.js

@@ -0,0 +1,292 @@
+// on-read.ts — the file-read-visibility render for the document substrate.
+//
+// When a `read` tool call returns, the canvas-doc-substrate pi extension calls
+// renderOnReadDocs() to surface the substrate docs that should appear ALONGSIDE
+// the file just read — each at its FILE-READ-VISIBILITY rung (NOT the
+// system-prompt rung the boot render uses). Two independent triggers decide
+// which docs surface (design §4/§6; plan-substrate.md track D1):
+//
+//   • POSITIONAL — walk the read file's ancestor dirs; any doc living in an
+//     ancestor's `.crouter/memory/` surfaces (a doc surfaces when a file
+//     beside/under its own scope dir is read). This mirrors nested-context's
+//     `.claude/rules` ancestor walk, but keyed on `.crouter/memory/`.
+//   • applies-to GLOB — any RESOLVED substrate doc (user/project/builtin scope)
+//     whose `appliesTo` glob matches the read file path surfaces, regardless of
+//     where the read file sits relative to the doc.
+//
+// Each candidate runs the substrate pipeline at its fileReadVisibility rung:
+//   parse → gatePasses(doc, assembleNodeSubject(nodeId)) → render
+//   (content → body, preview → previewLine, name → bare tag, none → skip).
+// The result is the faithful envelope (verdict n1):
+//   <auto-loaded-context file="…">
+//   <doc kind="…" name="…" src="…" triggered-by="…">…body/preview…</doc>
+//   </auto-loaded-context>
+// Returns '' when nothing surfaces.
+//
+// Pure + defensive: reads disk + the resolver + canvas-db subject assembly; no
+// writes, no side effects. Every disk/parse/glob step is wrapped so one bad doc
+// can never throw the whole render (the extension is additionally inert on
+// error). The CALLER owns the per-session `seen` realpath set (cleared on
+// session_start) and threads it in, so a given doc is injected at most once per
+// session across repeated reads.
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, matchesGlob, parse, relative, sep } from 'node:path';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { pathExists, readText, walkFiles } from '../fs-utils.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { listAllMemoryDocs } from '../memory-resolver.js';
+import { assembleNodeSubject, gatePasses, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
+import { cachedSubstrateDocs } from './session-cache.js';
+// Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
+// file may live under a build/dependency tree; `.crouter` is NOT junk here — it
+// is the segment we explicitly join onto each surviving ancestor).
+const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
+// ---------------------------------------------------------------------------
+// Small path helpers (mirror the on-read precedent — nested-context /
+// frontmatter-rules — so the injected envelope matches their faithful shape).
+// ---------------------------------------------------------------------------
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Escape a value for an XML-ish attribute in the injected envelope. */
+function attr(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/** Nearest enclosing git repo root for a path (walk up looking for `.git`). */
+function gitRootOf(p) {
+    let d = p;
+    const root = parse(d).root;
+    while (true) {
+        if (pathExists(join(d, '.git')))
+            return d;
+        if (d === root)
+            return null;
+        const parent = dirname(d);
+        if (parent === d)
+            return null;
+        d = parent;
+    }
+}
+/** Display a path relative to its nearest git repo root, else absolute. */
+function disp(p) {
+    const root = gitRootOf(p);
+    if (!root)
+        return p;
+    const rel = relative(root, p);
+    return rel === '' ? '.' : rel;
+}
+function isJunkAncestor(dir) {
+    return dir.split(sep).some((seg) => JUNK_DIRS.has(seg));
+}
+/** Load one positionally-discovered `.crouter/memory/` file into a SubstrateDoc,
+ *  or null when it is not a substrate doc / unreadable. `scope` is cosmetic here
+ *  (gate eval keys off the NODE subject, render off name/body/rung). */
+function loadPositionalDoc(file, memDir, scope) {
+    try {
+        const name = relative(memDir, file)
+            .replace(/\.md$/i, '')
+            .split(sep)
+            .join('/');
+        if (name === '')
+            return null;
+        const { data, body } = parseFrontmatterGeneric(readText(file));
+        const schema = parseSubstrateFrontmatter(data);
+        if (schema === null)
+            return null;
+        return { ...schema, name, scope, path: file, body };
+    }
+    catch {
+        return null;
+    }
+}
+function safeWalkMd(dir) {
+    try {
+        return walkFiles(dir, (n) => n.toLowerCase().endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/** POSITIONAL trigger: every substrate doc in an ancestor dir's
+ *  `.crouter/memory/`, walking from the read file up to $HOME (or the
+ *  filesystem root for a read outside $HOME), skipping junk ancestors. */
+function positionalCandidates(absReadFile) {
+    const out = [];
+    const seenDocPaths = new Set();
+    const home = homedir();
+    const fsRoot = parse(absReadFile).root;
+    let dir = dirname(absReadFile);
+    let depth = 0;
+    while (true) {
+        if (!isJunkAncestor(dir)) {
+            const memDir = join(dir, CRTR_DIR_NAME, 'memory');
+            if (pathExists(memDir)) {
+                const scope = dir === home ? 'user' : 'project';
+                for (const file of safeWalkMd(memDir)) {
+                    const real = realpathOrSelf(file);
+                    if (seenDocPaths.has(real))
+                        continue;
+                    seenDocPaths.add(real);
+                    const doc = loadPositionalDoc(file, memDir, scope);
+                    if (doc)
+                        out.push({ doc, realpath: real, order: depth });
+                }
+            }
+        }
+        if (dir === home || dir === fsRoot)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        depth += 1;
+    }
+    return out;
+}
+/** The user/project scope root that owns a resolved doc: `<root>/.crouter/memory/…`
+ *  → `<root>`. Builtin docs (no `.crouter` segment) return null. Used to test an
+ *  `appliesTo` glob against a read path RELATIVE to the doc's own project root. */
+function owningRootOf(doc) {
+    const parts = doc.path.split(sep);
+    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
+    if (idx <= 0)
+        return null;
+    return parts.slice(0, idx).join(sep) || sep;
+}
+function globMatches(glob, absReadFile, owningRoot) {
+    const targets = [absReadFile, basename(absReadFile)];
+    if (owningRoot)
+        targets.push(relative(owningRoot, absReadFile));
+    return targets.some((t) => {
+        try {
+            return matchesGlob(t, glob);
+        }
+        catch {
+            return false; // an invalid glob never matches
+        }
+    });
+}
+/** applies-to GLOB trigger: every RESOLVED substrate doc whose `appliesTo` glob
+ *  matches the read path. `taken` carries the realpaths already claimed by the
+ *  positional pass, so a doc found both ways is not double-counted.
+ *  Uses the per-session cache so the corpus is not re-walked+re-parsed on every
+ *  read tool call (O(reads × corpus) without the cache). */
+function appliesToCandidates(absReadFile, taken) {
+    let docs;
+    try {
+        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const doc of docs) {
+        const globs = doc.appliesTo;
+        if (!globs || globs.length === 0)
+            continue;
+        const real = realpathOrSelf(doc.path);
+        if (taken.has(real))
+            continue;
+        if (!globs.some((g) => globMatches(g, absReadFile, owningRootOf(doc))))
+            continue;
+        taken.add(real);
+        out.push({ doc, realpath: real, order: -1 });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Per-doc envelope render.
+// ---------------------------------------------------------------------------
+/** One doc as a `<doc …>` element at its fileReadVisibility rung, or null when
+ *  that rung is `none`. `content` → full body; `preview` → the routing line;
+ *  `name` → a bare self-closed tag (the `name=` attribute IS the surface). */
+function renderDocEnvelope(doc, absReadFile) {
+    const rung = doc.fileReadVisibility;
+    if (rung === 'none')
+        return null;
+    let body = '';
+    if (rung === 'content')
+        body = doc.body.trim();
+    else if (rung === 'preview')
+        body = previewLine(doc);
+    // 'name' → body stays '' (the tag's name attribute is the whole surface).
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" ` +
+        `src="${attr(disp(doc.path))}" triggered-by="${attr(disp(absReadFile))}"`;
+    return body === '' ? `<doc ${attrs} />` : `<doc ${attrs}>\n${body}\n</doc>`;
+}
+// ---------------------------------------------------------------------------
+// Public entry point.
+// ---------------------------------------------------------------------------
+/**
+ * Render the substrate docs that should surface alongside a just-read file.
+ *
+ * @param nodeId        the canvas node whose subject gates the docs.
+ * @param readFilePath  the path the `read` tool returned (absolute or not — it
+ *                      is resolved to a realpath internally).
+ * @param seen          the CALLER-owned, per-session set of already-injected
+ *                      doc realpaths. Docs already present are skipped; newly
+ *                      injected docs are added. Pass the same set across reads
+ *                      within a session (clear it on session_start) to get the
+ *                      once-per-session dedup; omit it for a standalone render.
+ * @returns the `<auto-loaded-context>` envelope, or '' when nothing surfaces.
+ */
+export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
+    let subject;
+    try {
+        subject = assembleNodeSubject(nodeId);
+    }
+    catch {
+        return '';
+    }
+    if (subject === null)
+        return '';
+    const absReadFile = realpathOrSelf(readFilePath);
+    let candidates;
+    try {
+        const positional = positionalCandidates(absReadFile);
+        const taken = new Set(positional.map((c) => c.realpath));
+        const byGlob = appliesToCandidates(absReadFile, taken);
+        candidates = [...positional, ...byGlob];
+    }
+    catch {
+        return '';
+    }
+    // Outermost-first: the nearest/most-specific doc reads last — closest to the
+    // file content that follows it (the applies-to set, order -1, trails).
+    candidates.sort((a, b) => b.order - a.order);
+    const rendered = [];
+    for (const c of candidates) {
+        // Never re-surface the doc the agent is literally reading.
+        if (c.realpath === absReadFile)
+            continue;
+        // Once-per-session dedup (caller-owned set).
+        if (seen.has(c.realpath))
+            continue;
+        let block;
+        try {
+            if (!gatePasses(c.doc, subject))
+                continue; // gated out for this node
+            block = renderDocEnvelope(c.doc, absReadFile);
+        }
+        catch {
+            continue; // a single bad doc never breaks the read
+        }
+        if (block === null)
+            continue; // fileReadVisibility 'none' — not a read surface
+        seen.add(c.realpath); // mark injected only once it actually surfaces
+        rendered.push(block);
+    }
+    if (rendered.length === 0)
+        return '';
+    return `<auto-loaded-context file="${attr(disp(absReadFile))}">\n${rendered.join('\n')}\n</auto-loaded-context>`;
+}

package/dist/core/substrate/render.d.ts

@@ -0,0 +1,25 @@
+/** The `## Skills` system-prompt section: every eligible `kind: skill` doc,
+ *  rendered at its `system-prompt-visibility`. `name`-rung skills collapse into
+ *  one compact catalog (group-collapsed, unioned with plugin/marketplace
+ *  skills); `preview`/`content`-rung skills each get a `###` sub-section.
+ *  Returns '' when nothing is eligible. */
+export declare function renderSkillsSection(nodeId: string): string;
+/** The `## Preferences` system-prompt section: every eligible `kind: preference`
+ *  doc as its own `###` sub-section, at its `system-prompt-visibility` (the
+ *  preference default rung is `preview` → the routing line). Returns '' when
+ *  nothing is eligible. */
+export declare function renderPreferencesSection(nodeId: string): string;
+/** The `## References` block embedded INSIDE the `<crtr-context>` session_start
+ *  message (the bearings caller pushes the returned string into the block, or
+ *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
+ *  `system-prompt-visibility` (reference boot default is `none`, so only
+ *  author-promoted references show) PLUS the node-local memory docs (any kind),
+ *  each a `###` sub-section. Replaces the old `<memory>` block. Returns '' when
+ *  nothing is eligible.
+ *
+ *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
+ *  doc drops only itself (with a loud stderr warning naming the offending path),
+ *  never silently swallowing the entire block (identity included).  Per the CTO
+ *  ruling, strictness lives at the COLLECTION layer (memory-resolver.ts); this
+ *  catch is error ISOLATION at the render layer, not a fallback parser. */
+export declare function renderReferencesBlock(nodeId: string): string;