@north-light/crouter 0.3.318 → 0.3.320

package/dist/commands/memory/read.js

@@ -1,232 +1,6 @@
-import { envNodeId } from '../../shared/env.js';
-import { CrtrClient } from '../../api/index.js';
-import { defineLeaf } from '../../core/command.js';
-import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
-import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
-import { ambientMemoryTarget, createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, loadMemoryTargetView, readMemoryDocContent, resolveMemoryDocs, } from '../../core/memory-resolver.js';
-import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
-import { emptyContextExposureState, exposureTarget, loadContextExposureState, registerDocumentExposure, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
-import { dirDedupKey, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
-import { contentReadAttachments } from '../../core/substrate/on-read.js';
-import { renderResult } from '../../core/render.js';
-import { effectiveDocKind } from '../../core/substrate/schema.js';
-import { canonicalSegments } from '../../core/memory/identity.js';
-import { MEMORY_KINDS, requireMountedStore, resolveReadSelector, selectorParam } from './shared.js';
-export { createMemoryDocSnapshot, readMemoryDocContent, resolveMemoryDocs };
-/** The node-config subject for memory-read-event gate evaluation. A CLI
- * process cannot take it from canvas-db (V-1); one `/v1` request supplies it.
- * With no node identity or no reachable daemon the answer is null — gated
- * docs then skip while ungated docs still deliver. Never autostarts a daemon:
- * a memory read must not boot the runtime as a side effect. */
-async function fetchSubject(nodeId) {
-    if (nodeId === undefined)
-        return null;
-    try {
-        // This optional gate lookup must not hold a memory read while a daemon is unavailable: an absent subject simply skips gated docs.
-        return await CrtrClient.forLocalSocket({ autostart: false, coldStartPollWindowMs: 0 }).nodeSubject(nodeId);
-    }
-    catch {
-        return null;
-    }
-}
-function corpusDocs() {
-    try {
-        return listAllMemoryDocs(undefined, true, true);
-    }
-    catch {
-        return [];
-    }
-}
-/** One physical document sharing a canonical identity, as the path-aware
- *  surfaces report it. `--dir <its project>` is how a non-winner is reached. */
-export function candidateRow(doc, winner) {
-    return {
-        winner: doc === winner,
-        scope: doc.scope,
-        store_root: doc.root,
-        physical_relative_path: doc.physicalRelativePath,
-        path: doc.path,
-    };
-}
-export const readLeaf = defineLeaf({
-    name: 'read',
-    description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its canonical name — read it before improvising. Resolution is exact and takes the full canonical name (a project document is `<namespace>/<local name>`); among documents sharing one name the winner is the nearest scope (node > project stack > profile > user > builtin). A directory name is a valid target too: it answers with that directory\u2019s own document, when it has one, together with its immediate listing, and walking directories is the sanctioned browse move. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
-    help: {
-        name: 'memory read',
-        summary: 'resolve an exact canonical name to its document body (frontmatter stripped unless --frontmatter), plus the directory listing when that name has members',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical memory name — a project document is `<namespace>/<local name>`, every other store\u2019s local names are already canonical, where a nested store\'s namespace includes its path under the repository root. Resolution is exact: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A name that carries members returns its listing alongside its body; a name that is only a directory returns the listing alone.' },
-            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
-            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
-            selectorParam('scope-read'),
-            selectorParam('dir', {}, 'Reads that store alone: the name resolves against its documents only, and the listing shows its members only.'),
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Resolved canonical document name, or the directory name on a directory read.' },
-            { name: 'local_name', type: 'string', required: false, constraint: 'Store-local identity, before the store namespace composed the canonical name. Absent on a directory read.' },
-            { name: 'kind', type: 'string', required: false, constraint: 'Resolved kind: knowledge or preference. Absent on a directory read.' },
-            { name: 'scope', type: 'string', required: false, constraint: 'Scope the document was resolved from: node, project, profile, user, or builtin. Absent on a directory read.' },
-            { name: 'path', type: 'string', required: false, constraint: 'Absolute path to the document on disk. Revise it with `crtr memory edit`, never by editing this file — an edit records why the change happened and lands in the doc’s revision history. Absent on a directory read.' },
-            { name: 'store_root', type: 'string', required: false, constraint: 'Absolute memory store root the document loaded from. Absent on a directory read.' },
-            { name: 'physical_relative_path', type: 'string', required: false, constraint: 'Store-relative physical markdown path, ordering prefixes and any `INDEX.md` kept. Absent on a directory read.' },
-            { name: 'representation', type: 'string', required: false, constraint: 'Physical representation of this identity: leaf-file or directory-index. Absent on a directory read.' },
-            { name: 'candidates', type: 'object[]', required: false, constraint: 'Present only when several physical documents share this canonical name: one row per candidate in source order, {winner, scope, store_root, physical_relative_path, path}. The winner is what this read returned; reach a non-winning one with `--dir <its project>`.' },
-            { name: 'content', type: 'string', required: false, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text. May be preceded by one `<auto-loaded-context>` block carrying the doc\u2019s neighborhood listings and any docs routed to this read. Absent on a directory read.' },
-            { name: 'listing', type: 'string[]', required: false, constraint: 'Present when the name has members — a directory document returns its body AND this listing, a bare directory returns the listing alone: one `[[name]]: <when-and-why>` line per member doc, one bare `[[name]]` per subdirectory. Follow any line with `crtr memory read <name>`.' },
-            { name: 'extensions', type: 'object', required: false, constraint: 'Effective valid plugin-owned metadata, keyed by plugin namespace then field. Includes enabled declaration defaults without writing them to frontmatter; disabled and unresolved namespaces are omitted. Present only on a document read.' },
-            { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. A directory link returns that directory\u2019s listing. Omitted when the body carries no resolvable links.' },
-            { name: 'follow_up', type: 'string', required: false, constraint: 'Present whenever the read returned a listing or resolvable body links.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Reads the document. A document that embeds shell (`!`cmd`` or a ```! block) runs those commands once, in the current working directory.',
-            'Records a content delivery for this node: a document whose profile project caps automatic boot and workspace-open disclosure below content is still returned whole here, and unsolicited channels stay quiet about it afterwards.',
-        ],
-    },
-    run: async (input) => {
-        const nameRaw = input['name'];
-        const kindFilter = input['kind'];
-        const includeFrontmatter = input['frontmatter'];
-        // The selector decides the corpus: a scope filter over the target view, or
-        // the one exact store `--dir` names. --kind is threaded INTO resolution
-        // (not a post-filter): a nearer wrong-kind doc is skipped so a farther
-        // matching-kind doc is found instead of shadowing it into a false
-        // not_found.
-        const selector = resolveReadSelector({
-            scope: input['scope'],
-            dir: input['dir'],
-        });
-        const kindOpts = kindFilter === undefined ? {} : { kind: kindFilter };
-        let set = null;
-        // Re-runs the throwing resolve when nothing answered, so the canonical
-        // not-found (with its spelling guidance) is the resolver's, not a copy.
-        let fail;
-        let listingByName;
-        let linkByName;
-        if (selector.store !== null) {
-            // `--dir` reads ONE exact store: its documents alone decide what resolves
-            // and what the listings show. Links stay corpus-wide — a body legitimately
-            // points at another store — with the selected store first so it wins its
-            // own names.
-            const view = loadMemoryStoreView(requireMountedStore(selector.store), true);
-            listingByName = docsByName(view.docs);
-            linkByName = docsByName([...view.docs, ...corpusDocs()]);
-            set = view.candidates(nameRaw, kindOpts);
-            fail = () => view.resolve(nameRaw, kindOpts);
-        }
-        else {
-            const resolveOpts = {
-                ...kindOpts,
-                ...(selector.scope === undefined ? {} : { scope: selector.scope }),
-                includeDescendants: true,
-            };
-            // A named read keeps unrelated malformed documents quiet, but a timed
-            // discovery leaves its corpus incomplete and must remain visible before
-            // this branch can report not_found.
-            const view = loadMemoryTargetView(ambientMemoryTarget(), {
-                ...resolveOpts,
-                quiet: true,
-                reportDiscovery: true,
-            });
-            listingByName = linkByName = docsByName(view.docs);
-            set = view.candidates(nameRaw, kindOpts);
-            fail = () => view.resolve(nameRaw, kindOpts);
-        }
-        const nodeId = envNodeId() || undefined;
-        if (set === null) {
-            // No document answers this name — a directory with no document of its own
-            // still does, through its listing. An explicit dir read is a deliberate
-            // act, so every line renders (unlisted excluded), never dedup-filtered;
-            // rendered members still record at preview so unsolicited channels stay
-            // quiet about them later.
-            const dirName = canonicalSegments(nameRaw.trim()).join('/');
-            if (dirName !== '' && isDirName(listingByName, dirName)) {
-                const contextExposure = nodeId !== undefined ? loadContextExposureState(nodeId) : null;
-                const target = contextExposure === null ? null : exposureTarget(contextExposure, 'transcript');
-                const listing = renderDirListing(listingByName, dirName, target, false);
-                if (nodeId !== undefined && contextExposure !== null && target !== null) {
-                    registerExposure(target, dirDedupKey(dirName), 'preview');
-                    saveContextExposureState(nodeId, contextExposure);
-                }
-                return {
-                    name: dirName,
-                    listing,
-                    follow_up: 'Each line is readable with `crtr memory read <name>` — a `[[name]]: <line>` entry is a doc, a bare `[[name]]` is a subdirectory whose read browses deeper. Browse the whole inventory with `crtr memory list`.',
-                };
-            }
-            fail();
-        }
-        const doc = set.winner;
-        const kind = effectiveDocKind(doc);
-        const raw = readMemoryDocContent(doc.path, includeFrontmatter);
-        // A read is an explicit act by an agent that can already run shell, so a
-        // document's embedded commands run here and their output lands inline —
-        // the same contract as invoking the document as a slash command. Nothing
-        // executes on the auto-load path, which never reaches this leaf.
-        const content = hasShellBlocks(raw)
-            ? await expandShellBlocks(raw, makeNodeShellRunner({ cwd: process.cwd() }))
-            : raw;
-        // `[[name]]` doc links are pointers, never transclusion: surface which
-        // linked names actually resolve so the reader can follow one when the
-        // task needs that depth, without ever auto-loading a linked body. A link
-        // is an exact canonical address — a directory name included, which browses
-        // to its listing.
-        const links = docLinkNames(doc.body).filter((linkName) => linkByName.has(linkName) || isDirName(linkByName, linkName));
-        // Reading a doc discloses where it sits (its directory's listing and each
-        // ancestor's, once per loaded context) and fires the memory-read event
-        // (corpus docs whose `memory-read` entries match the resolved name).
-        // Both prepend in one <auto-loaded-context> block. Without a node
-        // identity the call is stateless: listings render undeduped and nothing
-        // records.
-        const contextExposure = nodeId !== undefined
-            ? loadContextExposureState(nodeId)
-            : emptyContextExposureState();
-        const target = exposureTarget(contextExposure, 'transcript');
-        const subject = await fetchSubject(nodeId);
-        // An explicit read is itself content delivery. Register it before shared
-        // attachments, so the directory tree and companion routes dedupe against
-        // the body just returned exactly as every automatic content delivery does.
-        registerDocumentExposure(target, doc.path, doc.body, 'content');
-        const attachments = contentReadAttachments(doc, {
-            subject,
-            target,
-            byName: listingByName,
-            memoryTarget: ambientMemoryTarget(),
-            listings: 'blocks',
-            explicit: true,
-        });
-        if (nodeId !== undefined)
-            saveContextExposureState(nodeId, contextExposure);
-        const finalContent = attachments.blocks.length === 0 ? content : `<auto-loaded-context>\n${attachments.blocks.join('\n')}\n</auto-loaded-context>\n\n${content}`;
-        const listing = attachments.listing;
-        const hasListing = listing !== undefined && listing.length > 0;
-        const followUp = hasListing
-            ? links.length > 0
-                ? 'Each `[[name]]` line in `listing` is one of this directory’s immediate members, and the `[[name]]` links in the body are further reading — follow either with `crtr memory read <name>` only when the task needs that depth.'
-                : 'Each `[[name]]` line in `listing` is one of this directory’s immediate members, readable with `crtr memory read <name>` — follow one only when the task needs that depth.'
-            : links.length > 0
-                ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth.'
-                : null;
-        return {
-            name: doc.name,
-            local_name: doc.localName,
-            kind,
-            scope: doc.scope,
-            path: doc.path,
-            store_root: doc.root,
-            physical_relative_path: doc.physicalRelativePath,
-            representation: doc.representation,
-            ...(set.candidates.length > 1 ? { candidates: set.candidates.map((c) => candidateRow(c, doc)) } : {}),
-            content: finalContent,
-            ...(hasListing ? { listing } : {}),
-            extensions: projectEffectiveMemoryExtensions(doc.frontmatter?.['extensions'], memoryExtensionEffectiveCatalog(doc)),
-            ...(links.length > 0 ? { links } : {}),
-            ...(followUp === null ? {} : { follow_up: followUp }),
-        };
-    },
-    render: (result) => {
-        const { extensions: _extensions, ...withoutExtensions } = result;
-        return renderResult(withoutExtensions, readLeaf.help);
-    },
-});
+var B=Object.defineProperty;var i=(e,r)=>B(e,"name",{value:r,configurable:!0});import{envNodeId as F}from"../../shared/env.js";import{CrtrClient as I}from"../../api/index.js";import{defineLeaf as O}from"../../core/command.js";import{memoryExtensionEffectiveCatalog as K,projectEffectiveMemoryExtensions as Y}from"../../core/memory/extensions.js";import{docLinkNames as U}from"../../core/memory/doc-link-grammar.js";import{ambientMemoryTarget as E,createMemoryDocSnapshot as V,listAllMemoryDocs as W,loadMemoryStoreView as X,loadMemoryTargetView as $,readMemoryDocContent as R,resolveMemoryDocs as z}from"../../core/memory-resolver.js";import{expandShellBlocks as G,hasShellBlocks as H,makeNodeShellRunner as J}from"../../core/runtime/shell-expansion.js";import{emptyContextExposureState as Q,exposureTarget as S,loadContextExposureState as _,registerDocumentExposure as Z,registerExposure as ee,saveContextExposureState as D}from"../../core/substrate/injected-store.js";import{dirDedupKey as te,docsByName as g,isDirName as j,renderDirListing as ne}from"../../core/substrate/listings.js";import{contentReadAttachments as re}from"../../core/substrate/on-read.js";import{renderResult as oe}from"../../core/render.js";import{effectiveDocKind as ae}from"../../core/substrate/schema.js";import{canonicalSegments as ie}from"../../core/memory/identity.js";import{MEMORY_KINDS as se,requireMountedStore as de,resolveReadSelector as ce,selectorParam as M}from"./shared.js";async function le(e){if(e===void 0)return null;try{return await I.forLocalSocket({autostart:!1,coldStartPollWindowMs:0}).nodeSubject(e)}catch{return null}}i(le,"fetchSubject");function me(){try{return W(void 0,!0,!0)}catch{return[]}}i(me,"corpusDocs");function he(e,r){return{winner:e===r,scope:e.scope,store_root:e.root,physical_relative_path:e.physicalRelativePath,path:e.path}}i(he,"candidateRow");const ue=O({name:"read",description:"load a memory document body by name",whenToUse:"a task in front of you matches a stored document and you already know its canonical name \u2014 read it before improvising. Resolution is exact and takes the full canonical name (a project document is `<namespace>/<local name>`); among documents sharing one name the winner is the nearest scope (node > project stack > profile > user > builtin). A directory name is a valid target too: it answers with that directory\u2019s own document, when it has one, together with its immediate listing, and walking directories is the sanctioned browse move. You name the document by its crtr identifier, never a file path \u2014 do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.",help:{name:"memory read",summary:"resolve an exact canonical name to its document body (frontmatter stripped unless --frontmatter), plus the directory listing when that name has members",params:[{kind:"positional",name:"name",required:!0,constraint:"Full canonical memory name \u2014 a project document is `<namespace>/<local name>`, every other store\u2019s local names are already canonical, where a nested store's namespace includes its path under the repository root. Resolution is exact: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A name that carries members returns its listing alongside its body; a name that is only a directory returns the listing alone."},{kind:"flag",name:"kind",type:"enum",choices:[...se],required:!1,constraint:"Narrows resolution when the name is ambiguous across kinds."},{kind:"flag",name:"frontmatter",type:"bool",required:!1,constraint:"When present, includes the YAML frontmatter in the returned body. Off by default \u2014 only the body is returned."},M("scope-read"),M("dir",{},"Reads that store alone: the name resolves against its documents only, and the listing shows its members only.")],output:[{name:"name",type:"string",required:!0,constraint:"Resolved canonical document name, or the directory name on a directory read."},{name:"local_name",type:"string",required:!1,constraint:"Store-local identity, before the store namespace composed the canonical name. Absent on a directory read."},{name:"kind",type:"string",required:!1,constraint:"Resolved kind: knowledge or preference. Absent on a directory read."},{name:"scope",type:"string",required:!1,constraint:"Scope the document was resolved from: node, project, profile, user, or builtin. Absent on a directory read."},{name:"path",type:"string",required:!1,constraint:"Absolute path to the document on disk. Revise it with `crtr memory edit`, never by editing this file \u2014 an edit records why the change happened and lands in the doc\u2019s revision history. Absent on a directory read."},{name:"store_root",type:"string",required:!1,constraint:"Absolute memory store root the document loaded from. Absent on a directory read."},{name:"physical_relative_path",type:"string",required:!1,constraint:"Store-relative physical markdown path, ordering prefixes and any `INDEX.md` kept. Absent on a directory read."},{name:"representation",type:"string",required:!1,constraint:"Physical representation of this identity: leaf-file or directory-index. Absent on a directory read."},{name:"candidates",type:"object[]",required:!1,constraint:"Present only when several physical documents share this canonical name: one row per candidate in source order, {winner, scope, store_root, physical_relative_path, path}. The winner is what this read returned; reach a non-winning one with `--dir <its project>`."},{name:"content",type:"string",required:!1,constraint:"Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text. May be preceded by one `<auto-loaded-context>` block carrying the doc\u2019s neighborhood listings and any docs routed to this read. Absent on a directory read."},{name:"listing",type:"string[]",required:!1,constraint:"Present when the name has members \u2014 a directory document returns its body AND this listing, a bare directory returns the listing alone: one `[[name]]: <when-and-why>` line per member doc, one bare `[[name]]` per subdirectory. Follow any line with `crtr memory read <name>`."},{name:"extensions",type:"object",required:!1,constraint:"Effective valid plugin-owned metadata, keyed by plugin namespace then field. Includes enabled declaration defaults without writing them to frontmatter; disabled and unresolved namespaces are omitted. Present only on a document read."},{name:"links",type:"string[]",required:!1,constraint:"Canonical names this document links to via `[[name]]` that resolve in the current corpus \u2014 further reading, loaded only on demand with `crtr memory read <name>`. A directory link returns that directory\u2019s listing. Omitted when the body carries no resolvable links."},{name:"follow_up",type:"string",required:!1,constraint:"Present whenever the read returned a listing or resolvable body links."}],outputKind:"object",effects:["Reads the document. A document that embeds shell (`!`cmd`` or a ```! block) runs those commands once, in the current working directory.","Records a content delivery for this node: a document whose profile project caps automatic boot and workspace-open disclosure below content is still returned whole here, and unsolicited channels stay quiet about it afterwards."]},run:i(async e=>{const r=e.name,l=e.kind,N=e.frontmatter,m=ce({scope:e.scope,dir:e.dir}),d=l===void 0?{}:{kind:l};let s=null,p,c,h;if(m.store!==null){const t=X(de(m.store),!0);c=g(t.docs),h=g([...t.docs,...me()]),s=t.candidates(r,d),p=i(()=>t.resolve(r,d),"fail")}else{const t={...d,...m.scope===void 0?{}:{scope:m.scope},includeDescendants:!0},a=$(E(),{...t,quiet:!0,reportDiscovery:!0});c=h=g(a.docs),s=a.candidates(r,d),p=i(()=>a.resolve(r,d),"fail")}const o=F()||void 0;if(s===null){const t=ie(r.trim()).join("/");if(t!==""&&j(c,t)){const a=o!==void 0?_(o):null,b=a===null?null:S(a,"transcript"),T=ne(c,t,b,!1);return o!==void 0&&a!==null&&b!==null&&(ee(b,te(t),"preview"),D(o,a)),{name:t,listing:T,follow_up:"Each line is readable with `crtr memory read <name>` \u2014 a `[[name]]: <line>` entry is a doc, a bare `[[name]]` is a subdirectory whose read browses deeper. Browse the whole inventory with `crtr memory list`."}}p()}const n=s.winner,C=ae(n),y=R(n.path,N),k=H(y)?await G(y,J({cwd:process.cwd()})):y,u=U(n.body).filter(t=>h.has(t)||j(h,t)),v=o!==void 0?_(o):Q(),x=S(v,"transcript"),P=await le(o);Z(x,n.path,n.body,"content");const f=re(n,{subject:P,target:x,byName:c,memoryTarget:E(),listings:"blocks",explicit:!0});o!==void 0&&D(o,v);const L=f.blocks.length===0?k:`<auto-loaded-context>
+${f.blocks.join(`
+`)}
+</auto-loaded-context>
+
+${k}`,w=f.listing,q=w!==void 0&&w.length>0,A=q?u.length>0?"Each `[[name]]` line in `listing` is one of this directory\u2019s immediate members, and the `[[name]]` links in the body are further reading \u2014 follow either with `crtr memory read <name>` only when the task needs that depth.":"Each `[[name]]` line in `listing` is one of this directory\u2019s immediate members, readable with `crtr memory read <name>` \u2014 follow one only when the task needs that depth.":u.length>0?"The `[[name]]` links in the body are further reading \u2014 follow one with `crtr memory read <name>` only when the task needs that depth.":null;return{name:n.name,local_name:n.localName,kind:C,scope:n.scope,path:n.path,store_root:n.root,physical_relative_path:n.physicalRelativePath,representation:n.representation,...s.candidates.length>1?{candidates:s.candidates.map(t=>he(t,n))}:{},content:L,...q?{listing:w}:{},extensions:Y(n.frontmatter?.extensions,K(n)),...u.length>0?{links:u}:{},...A===null?{}:{follow_up:A}}},"run"),render:i(e=>{const{extensions:r,...l}=e;return oe(l,ue.help)},"render")});export{he as candidateRow,V as createMemoryDocSnapshot,ue as readLeaf,R as readMemoryDocContent,z as resolveMemoryDocs};