@north-light/crouter 0.3.318 → 0.3.319

package/dist/commands/human/shared.js

@@ -1,67 +1 @@
-import { readConfig } from '../../core/config.js';
-import { CORE_COMPONENT_SELECTION_LINES } from '../../core/human/component-docs.js';
-// The reader's missing context is the gap syntax cannot close: an inbox page
-// is opened away from the conversation that produced it, by someone who never
-// followed the work.
-const PAGE_BRIEF = 'Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names what is being settled, not the topic it sits under. Subtitle is the single line shown beside the title in the inbox list before anything is opened, so it earns the open — your recommendation and what is at stake — rather than summarising the page. Content carries only what is needed to decide. Ask only what changes your next step, and offer only options you would actually take; mark the one you would take `recommended` (at most one per question), because a page whose single question is that picker can be answered straight from the inbox list without ever being opened, which is the cheapest answer you can ask for. The reader takes a page one step at a time, so hold each step — and a stepless page — to one question or request for action; several decisions means several `<Step>` children, never one long scroll of stacked context and asks. A page that asks nothing states what happened and what it changes.';
-// Both hosts render pages and both want them reached for by default; only the
-// reason differs, so neither surface is left sounding like pages are exotic.
-const ENCOURAGEMENT_PAGE_SURFACE = 'Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion.';
-const ENCOURAGEMENT_TERMINAL = 'Use inline pages as the default way to put a question or a decision in front of the user; the viewer draws them in the transcript and in the inbox, so a page is not a special occasion.';
-// The default is about form, not frequency: the page is the cheap part and the
-// reader's attention is the expensive one, so say both in the same breath.
-const INTERRUPTION_COST = 'What costs the reader is being asked, not the page it arrives on: send one when their answer changes what you do next, carry everything else in your next report, and put several decisions in one page as separate steps rather than sending several pages.';
-const AUTHORING_MODULE = 'Write one `.tsx` module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx` that default-exports a component whose root element is `<Page title="…" subtitle="…">`; a multi-step page puts its content in `<Step>` children.';
-// Only a page surface can show an HTML document; a terminal host renders its
-// title and nothing else, so naming the dialect there would hand the agent a
-// page its reader could not read.
-const AUTHORING_HTML = 'Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response.';
-const AUTHORING_RULES = 'Delivery is chosen by `human send` flags, never a Page prop. Registry components and React are already in scope, so the module contains no `import` and no `require`. Full JS is yours: state, expressions, `.map` over your data, event handlers, plain elements with Tailwind classes. `usePageHost` is a reserved hook whose product-supplied members are opaque here. Never render submit or dismiss chrome — the host owns it. Display-only pages are first-class: a page with no questions may be sent without inbox or reply delivery. The module is compiled when you submit it and a compile error rejects the submit; there is no pre-check.';
-// Where context belongs is a property of the surface, not of taste: a page
-// surface shows a question with the whole page around it, a terminal shows one
-// question alone on the screen.
-const CONTEXT_PAGE_SURFACE = 'Context can sit anywhere on the page — prose and display components around a question are rendered beside it — so a question\'s `body` carries what that question needs and the page carries the shared background.';
-const CONTEXT_TERMINAL = 'Put the context a question needs in that question\'s own `body`: the reader is shown one question at a time, so page-level prose is not in front of them while they answer, and a question that leans on it cannot be answered.';
-const FLATTENING_TERMINAL = 'This host draws the page from the components you declared rather than running your module, so layout, Tailwind classes, state, and click handlers never reach the reader — what survives is each component\'s `label`, its markdown `body`, and its options, rows, or cards. A chart renders as one line naming it, and a product-registered component cannot be answered here at all.';
-const DISPLAY_SET_LINE = 'The shadcn display set — `Card`, `Badge`, `Button`, `Table`, `Tabs`, `Separator`, `Alert`, `Progress`, `Accordion` and their parts — is in scope too, for presentation only.';
-/** The one page authoring model for `human -h`. */
-export function pageHelpText(pageSurface = false) {
-    const authoring = [
-        pageSurface ? ENCOURAGEMENT_PAGE_SURFACE : ENCOURAGEMENT_TERMINAL,
-        INTERRUPTION_COST,
-        AUTHORING_MODULE,
-        ...(pageSurface ? [AUTHORING_HTML] : []),
-        AUTHORING_RULES,
-        pageSurface ? CONTEXT_PAGE_SURFACE : CONTEXT_TERMINAL,
-        ...(pageSurface ? [] : [FLATTENING_TERMINAL]),
-    ].join(' ');
-    return {
-        brief: PAGE_BRIEF,
-        authoring,
-        componentSelection: [...CORE_COMPONENT_SELECTION_LINES, DISPLAY_SET_LINE],
-        pageHint: 'Write the page module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx`; pass that path.',
-        // The page-surface wording names no document review and no live display:
-        // `human review` and `human show` are terminal-only and leave the tree on
-        // such a host (see `registerHuman`).
-        // No leading "when": the root renderer already emits `use when ${useWhen}`.
-        rootUseWhen: pageSurface
-            ? 'a person must decide something or receive structured content from you; use inline pages by default because the environment renders rich components.'
-            : 'a person must decide, review a document with you, or receive a live display.',
-        sendSummary: pageSurface ? 'send a durable TSX or HTML page' : 'send a durable TSX page',
-        sendWhenToUse: pageSurface
-            ? 'you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.'
-            : 'you need to put structured TSX content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.',
-        pageFlagConstraint: pageSurface
-            ? 'A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.'
-            : 'Provide exactly one of --page or stdin.',
-        stdinConstraint: pageSurface
-            ? 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.'
-            : 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH.',
-        dirConstraint: pageSurface
-            ? 'Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.'
-            : 'Interaction directory holding page.tsx, optional page.js, page.json, and response lifecycle files when delivery needs them.',
-    };
-}
-export function resolveMaxPanes() {
-    return readConfig('user').max_panes_per_window;
-}
+var o=Object.defineProperty;var n=(e,t)=>o(e,"name",{value:t,configurable:!0});import{readConfig as s}from"../../core/config.js";import{CORE_COMPONENT_SELECTION_LINES as a}from"../../core/human/component-docs.js";const i="Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names what is being settled, not the topic it sits under. Subtitle is the single line shown beside the title in the inbox list before anything is opened, so it earns the open \u2014 your recommendation and what is at stake \u2014 rather than summarising the page. Content carries only what is needed to decide. Ask only what changes your next step, and offer only options you would actually take; mark the one you would take `recommended` (at most one per question), because a page whose single question is that picker can be answered straight from the inbox list without ever being opened, which is the cheapest answer you can ask for. The reader takes a page one step at a time, so hold each step \u2014 and a stepless page \u2014 to one question or request for action; several decisions means several `<Step>` children, never one long scroll of stacked context and asks. A page that asks nothing states what happened and what it changes.",r="Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion.",d="Use inline pages as the default way to put a question or a decision in front of the user; the viewer draws them in the transcript and in the inbox, so a page is not a special occasion.",h="What costs the reader is being asked, not the page it arrives on: send one when their answer changes what you do next, carry everything else in your next report, and put several decisions in one page as separate steps rather than sending several pages.",l='Write one `.tsx` module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx` that default-exports a component whose root element is `<Page title="\u2026" subtitle="\u2026">`; a multi-step page puts its content in `<Step>` children.',c="Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response.",p="Delivery is chosen by `human send` flags, never a Page prop. Registry components and React are already in scope, so the module contains no `import` and no `require`. Full JS is yours: state, expressions, `.map` over your data, event handlers, plain elements with Tailwind classes. `usePageHost` is a reserved hook whose product-supplied members are opaque here. Never render submit or dismiss chrome \u2014 the host owns it. Display-only pages are first-class: a page with no questions may be sent without inbox or reply delivery. The module is compiled when you submit it and a compile error rejects the submit; there is no pre-check.",u="Context can sit anywhere on the page \u2014 prose and display components around a question are rendered beside it \u2014 so a question's `body` carries what that question needs and the page carries the shared background.",m="Put the context a question needs in that question's own `body`: the reader is shown one question at a time, so page-level prose is not in front of them while they answer, and a question that leans on it cannot be answered.",g="This host draws the page from the components you declared rather than running your module, so layout, Tailwind classes, state, and click handlers never reach the reader \u2014 what survives is each component's `label`, its markdown `body`, and its options, rows, or cards. A chart renders as one line naming it, and a product-registered component cannot be answered here at all.",y="The shadcn display set \u2014 `Card`, `Badge`, `Button`, `Table`, `Tabs`, `Separator`, `Alert`, `Progress`, `Accordion` and their parts \u2014 is in scope too, for presentation only.";function v(e=!1){const t=[e?r:d,h,l,...e?[c]:[],p,e?u:m,...e?[]:[g]].join(" ");return{brief:i,authoring:t,componentSelection:[...a,y],pageHint:"Write the page module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx`; pass that path.",rootUseWhen:e?"a person must decide something or receive structured content from you; use inline pages by default because the environment renders rich components.":"a person must decide, review a document with you, or receive a live display.",sendSummary:e?"send a durable TSX or HTML page":"send a durable TSX page",sendWhenToUse:e?"you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.":"you need to put structured TSX content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.",pageFlagConstraint:e?"A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.":"Provide exactly one of --page or stdin.",stdinConstraint:e?"The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.":"The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH.",dirConstraint:e?"Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.":"Interaction directory holding page.tsx, optional page.js, page.json, and response lifecycle files when delivery needs them."}}n(v,"pageHelpText");function f(){return s("user").max_panes_per_window}n(f,"resolveMaxPanes");export{v as pageHelpText,f as resolveMaxPanes};

package/dist/commands/human.js

@@ -1,60 +1,4 @@
-// `crtr human` creates durable pages and review tickets for human decisions.
-//
-// Send optionally creates a reply bridge; review creation asks crtrd to create
-// a ticket, daemon-owned review, and companion. Show is passive display.
-import { defineBranch } from '../core/command.js';
-import { readConfig } from '../core/config.js';
-import { humanSend, humanShow } from './human/prompts.js';
-import { humanList, humanResolve, humanCancel } from './human/queue.js';
-import { humanReviewBranch } from './human/review.js';
-import { humanFeedbackBranch } from './human/feedback.js';
-import { humanComponents } from './human/components.js';
-import { humanRequestBranch } from './human/request.js';
-import { pageHelpText } from './human/shared.js';
-export function registerHuman() {
-    // `page_surface` marks a host whose human surface is a rendered page product
-    // rather than a terminal. Review and show are terminal-only: a review is a
-    // live editor session with anchored comments driven by a companion node, and
-    // show is a passive tmux live-watch. Such a host can render neither, so both
-    // leave the surface entirely instead of filing tickets nobody can open.
-    const pageSurface = readConfig('user').page_surface;
-    const pageHelp = pageHelpText(pageSurface);
-    const concept = pageSurface
-        ? 'human-in-the-loop decisions and structured pages'
-        : 'human-in-the-loop decisions, document review, and live display';
-    const durableRequests = '`request` publishes the same page with no bridge at all, for a caller that will have exited before the answer arrives: its outcome is read back or carried to a named local action.';
-    const ticketModel = pageSurface
-        ? `Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${durableRequests}`
-        : `Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${durableRequests} \`review\` is for live document review with anchored comments; \`show\` is a passive tmux live-watch rather than a ticket.`;
-    return defineBranch({
-        name: 'human',
-        extensible: true,
-        rootEntry: {
-            concept,
-            desc: pageSurface ? 'send, components, feedback, cancel, list' : 'send, review new/comment, show, cancel, list',
-            useWhen: pageHelp.rootUseWhen,
-        },
-        help: {
-            name: 'human',
-            summary: concept,
-            model: [
-                ticketModel,
-                pageHelp.brief,
-                pageHelp.authoring,
-                pageHelp.componentSelection.join('\n'),
-                'Props, response contracts, and the full component catalog: `crtr human components`; select with `crtr human components list`, then read one with `crtr human components show <component>`.',
-            ].join('\n\n'),
-        },
-        children: [
-            humanComponents,
-            humanSend(pageSurface),
-            ...(pageSurface ? [] : [humanReviewBranch]),
-            humanFeedbackBranch,
-            ...(pageSurface ? [] : [humanShow]),
-            humanRequestBranch,
-            humanCancel,
-            humanList,
-            humanResolve,
-        ],
-    });
-}
+var s=Object.defineProperty;var a=(e,n)=>s(e,"name",{value:n,configurable:!0});import{defineBranch as i}from"../core/command.js";import{readConfig as c}from"../core/config.js";import{humanSend as m,humanShow as h}from"./human/prompts.js";import{humanList as u,humanResolve as p,humanCancel as l}from"./human/queue.js";import{humanReviewBranch as d}from"./human/review.js";import{humanFeedbackBranch as w}from"./human/feedback.js";import{humanComponents as f}from"./human/components.js";import{humanRequestBranch as b}from"./human/request.js";import{pageHelpText as g}from"./human/shared.js";function T(){const e=c("user").page_surface,n=g(e),o=e?"human-in-the-loop decisions and structured pages":"human-in-the-loop decisions, document review, and live display",t="`request` publishes the same page with no bridge at all, for a caller that will have exited before the answer arrives: its outcome is read back or carried to a named local action.",r=e?`Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${t}`:`Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${t} \`review\` is for live document review with anchored comments; \`show\` is a passive tmux live-watch rather than a ticket.`;return i({name:"human",extensible:!0,rootEntry:{concept:o,desc:e?"send, components, feedback, cancel, list":"send, review new/comment, show, cancel, list",useWhen:n.rootUseWhen},help:{name:"human",summary:o,model:[r,n.brief,n.authoring,n.componentSelection.join(`
+`),"Props, response contracts, and the full component catalog: `crtr human components`; select with `crtr human components list`, then read one with `crtr human components show <component>`."].join(`
+
+`)},children:[f,m(e),...e?[]:[d],w,...e?[]:[h],b,l,u,p]})}a(T,"registerHuman");export{T as registerHuman};

package/dist/commands/memory/delete.js

@@ -1,100 +1 @@
-import { rmSync } from 'node:fs';
-import { resolve as resolvePath } from 'node:path';
-import { defineLeaf } from '../../core/command.js';
-import { CrtrError, notFound, usage } from '../../core/errors.js';
-import { readText } from '../../core/fs-utils.js';
-import { loadMemoryStoreView, resolveMemoryCandidates } from '../../core/memory-resolver.js';
-import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor } from '../../core/memory/history.js';
-import { MEMORY_WRITE_SCOPES, pruneEmptyParents, requireMountedStore, selectMutationDoc, resolveReadSelector, selectorParam, } from './shared.js';
-/** Every physical document owning that exact canonical identity — in the target
- *  view, or inside the one store `--dir` selected — or null when nothing
- *  answers to the name. */
-function targetCandidates(rawName, scope, storeView) {
-    if (storeView !== null)
-        return storeView.candidates(rawName);
-    try {
-        return resolveMemoryCandidates(rawName, {
-            includeDescendants: true,
-            ...(scope !== undefined ? { scope } : {}),
-        });
-    }
-    catch (e) {
-        if (e instanceof CrtrError && e.code === 'not_found')
-            return null;
-        throw e; // usage propagates with its own recovery guidance
-    }
-}
-export const deleteLeaf = defineLeaf({
-    name: 'delete',
-    description: 'delete a memory document by name',
-    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the full canonical name exactly as `read` does and removes that one file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`). If two physical files in the selected store share the name, it selects the first physical path in stable lexical order and recovers the collision.',
-    help: {
-        name: 'memory delete',
-        summary: 'resolve an exact canonical name and remove that document from its store',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical name of the document — a project document is `<namespace>/<local name>`. Resolution is exact, as `read` resolves it: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A canonical directory’s own document is deleted at the directory name; its members are untouched and stay reachable. If two physical files in the selected store own the name, delete selects the first path in stable lexical order and reports it. Builtin and installed-plugin documents are read-only and refuse to delete, as does the repository-root document, which declares the immutable namespace for every document in the repository; a nested store’s root guide is ordinary and may be deleted.' },
-            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'Package-shipped documents cannot be deleted through this writable-scope selector.'),
-            selectorParam('dir', {}, 'Deletes from that one store, including a non-winning duplicate no target view resolves to.'),
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Full canonical name of the document that was deleted, as resolution settled it.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: node, user, project, or profile.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
-            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document’s revision log, which OUTLIVES the document — the delete is appended to it as a tombstone carrying the full final text, still readable with `crtr memory history`.' },
-            { name: 'follow_up', type: 'string', required: false, constraint: 'Present only when a same-store canonical collision was recovered by selecting the first physical path in lexical order.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Permanently removes the resolved file from its store, and prunes any parent directories it leaves empty. Irreversible. Refuses the repository-root document: it declares the immutable `namespace:` every document in this repository composes under, so removing it would unmount the whole repository.',
-            'Appends a `delete` record carrying the document’s full final text to `.history/<physical path>.jsonl` in the same store. The log itself is never removed.',
-        ]
-    },
-    run: async (input) => {
-        const nameRaw = input['name'];
-        const scopeArg = input['scope'];
-        const dirArg = input['dir'];
-        const selector = resolveReadSelector({ scope: scopeArg, dir: dirArg });
-        const storeView = selector.store === null ? null : loadMemoryStoreView(requireMountedStore(selector.store), true);
-        const set = targetCandidates(nameRaw, selector.scope, storeView);
-        if (set === null) {
-            throw notFound(`memory document not found: ${nameRaw}`, {
-                memory: nameRaw,
-                next: 'A delete takes the full canonical name (a project document is <namespace>/<local name>), and a directory’s own document answers at the directory name. Run `crtr memory find <leaf>` to look it up, or pass --dir to reach one exact project store.',
-            });
-        }
-        const selected = selectMutationDoc(set);
-        const doc = selected.doc;
-        if (doc.plugin !== undefined) {
-            throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" — it is not a scope doc and cannot be deleted here. Manage plugin docs with \`crtr pkg\`. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, plugin: doc.plugin });
-        }
-        if (doc.scope === 'builtin') {
-            throw usage(`${doc.name} is a builtin document shipped with the package (read-only) — it cannot be deleted. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
-        }
-        // Only the repository-root document declares the namespace and is
-        // immutable through the memory commands.
-        if (doc.localName === '' && doc.store.ownerRelativePath === '') {
-            throw usage(`${doc.name} is the repository-root document at ${doc.path}, which declares the namespace every document in this repository composes under — deleting it would unmount the whole repository, so it cannot be deleted.`, {
-                memory: doc.name,
-                path: doc.path,
-                next: `Delete the documents under \`${doc.name}/\` individually, or revise the repository-root document with \`crtr memory edit ${doc.name} --rationale "<why>"\`.`,
-            });
-        }
-        const before = readText(doc.path);
-        const logPath = historyLogPathFor(doc.root, doc.path);
-        rmSync(doc.path);
-        pruneEmptyParents(resolvePath(doc.path), doc.physicalRelativePath.split('/').length);
-        // The log is the audit trail and outlives the doc: the tombstone carries the
-        // full final text, and a later `write` of the same name keeps appending to
-        // this same log — one log per physical path over its whole life.
-        appendHistoryRecord(logPath, buildHistoryRecord({ op: 'delete', before, after: '' }));
-        return {
-            name: doc.name,
-            scope: doc.scope,
-            path: doc.path,
-            log_path: logPath,
-            ...(selected.collisionPaths.length > 0
-                ? { follow_up: `Removed the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` }
-                : {}),
-        };
-    },
-});
+var u=Object.defineProperty;var s=(t,o)=>u(t,"name",{value:o,configurable:!0});import{rmSync as y}from"node:fs";import{resolve as f}from"node:path";import{defineLeaf as w}from"../../core/command.js";import{CrtrError as g,notFound as v,usage as i}from"../../core/errors.js";import{readText as b}from"../../core/fs-utils.js";import{loadMemoryStoreView as x,resolveMemoryCandidates as R}from"../../core/memory-resolver.js";import{appendHistoryRecord as P,buildHistoryRecord as $,historyLogPathFor as k}from"../../core/memory/history.js";import{MEMORY_WRITE_SCOPES as S,pruneEmptyParents as j,requireMountedStore as q,selectMutationDoc as A,resolveReadSelector as E,selectorParam as m}from"./shared.js";function M(t,o,n){if(n!==null)return n.candidates(t);try{return R(t,{includeDescendants:!0,...o!==void 0?{scope:o}:{}})}catch(r){if(r instanceof g&&r.code==="not_found")return null;throw r}}s(M,"targetCandidates");const U=w({name:"delete",description:"delete a memory document by name",whenToUse:"a stored document is wrong, obsolete, or superseded and should be removed \u2014 the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the full canonical name exactly as `read` does and removes that one file: if you can read it, you can delete it. Refuses docs you do not own \u2014 builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`). If two physical files in the selected store share the name, it selects the first physical path in stable lexical order and recovers the collision.",help:{name:"memory delete",summary:"resolve an exact canonical name and remove that document from its store",params:[{kind:"positional",name:"name",required:!0,constraint:"Full canonical name of the document \u2014 a project document is `<namespace>/<local name>`. Resolution is exact, as `read` resolves it: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A canonical directory\u2019s own document is deleted at the directory name; its members are untouched and stay reachable. If two physical files in the selected store own the name, delete selects the first path in stable lexical order and reports it. Builtin and installed-plugin documents are read-only and refuse to delete, as does the repository-root document, which declares the immutable namespace for every document in the repository; a nested store\u2019s root guide is ordinary and may be deleted."},m("scope-read",{choices:[...S]},"Package-shipped documents cannot be deleted through this writable-scope selector."),m("dir",{},"Deletes from that one store, including a non-winning duplicate no target view resolves to.")],output:[{name:"name",type:"string",required:!0,constraint:"Full canonical name of the document that was deleted, as resolution settled it."},{name:"scope",type:"string",required:!0,constraint:"Scope the document was deleted from: node, user, project, or profile."},{name:"path",type:"string",required:!0,constraint:"Absolute path of the file that was removed."},{name:"log_path",type:"string",required:!0,constraint:"Absolute path to the document\u2019s revision log, which OUTLIVES the document \u2014 the delete is appended to it as a tombstone carrying the full final text, still readable with `crtr memory history`."},{name:"follow_up",type:"string",required:!1,constraint:"Present only when a same-store canonical collision was recovered by selecting the first physical path in lexical order."}],outputKind:"object",effects:["Permanently removes the resolved file from its store, and prunes any parent directories it leaves empty. Irreversible. Refuses the repository-root document: it declares the immutable `namespace:` every document in this repository composes under, so removing it would unmount the whole repository.","Appends a `delete` record carrying the document\u2019s full final text to `.history/<physical path>.jsonl` in the same store. The log itself is never removed."]},run:s(async t=>{const o=t.name,n=t.scope,r=t.dir,a=E({scope:n,dir:r}),h=a.store===null?null:x(q(a.store),!0),l=M(o,a.scope,h);if(l===null)throw v(`memory document not found: ${o}`,{memory:o,next:"A delete takes the full canonical name (a project document is <namespace>/<local name>), and a directory\u2019s own document answers at the directory name. Run `crtr memory find <leaf>` to look it up, or pass --dir to reach one exact project store."});const d=A(l),e=d.doc;if(e.plugin!==void 0)throw i(`${e.name} belongs to the installed plugin "${e.plugin}" \u2014 it is not a scope doc and cannot be deleted here. Manage plugin docs with \`crtr pkg\`. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${e.name} ...\`).`,{memory:e.name,plugin:e.plugin});if(e.scope==="builtin")throw i(`${e.name} is a builtin document shipped with the package (read-only) \u2014 it cannot be deleted. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${e.name} ...\`).`,{memory:e.name,scope:"builtin"});if(e.localName===""&&e.store.ownerRelativePath==="")throw i(`${e.name} is the repository-root document at ${e.path}, which declares the namespace every document in this repository composes under \u2014 deleting it would unmount the whole repository, so it cannot be deleted.`,{memory:e.name,path:e.path,next:`Delete the documents under \`${e.name}/\` individually, or revise the repository-root document with \`crtr memory edit ${e.name} --rationale "<why>"\`.`});const p=b(e.path),c=k(e.root,e.path);return y(e.path),j(f(e.path),e.physicalRelativePath.split("/").length),P(c,$({op:"delete",before:p,after:""})),{name:e.name,scope:e.scope,path:e.path,log_path:c,...d.collisionPaths.length>0?{follow_up:`Removed the first physical path in stable lexical order (${e.path}) to recover a same-store collision.`}:{}}},"run")});export{U as deleteLeaf};

package/dist/commands/memory/edit.js

@@ -1,219 +1,21 @@
-import { defineLeaf } from '../../core/command.js';
-import { CrtrError, notFound, usage } from '../../core/errors.js';
-import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { readText, writeText } from '../../core/fs-utils.js';
-import { loadMemoryStoreView, resolveMemoryCandidates, } from '../../core/memory-resolver.js';
-import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, readHistoryRecords, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, coerceGate, coerceLintIgnore, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, literalBodySegment, serializeMemoryDocLiteral, selectorParam, requireLocalNameInStore, requireUnambiguousDoc, resolveReadSelector, } from './shared.js';
-/** Frontmatter fields an overlay flag cannot express removing. Accepted for
- *  `--unset` unconditionally — whether or not the target doc currently
- *  carries them. */
-const CLEARABLE_FIELDS = ['short-form', 'gate', 'surfaces', 'unlisted', 'slash', 'rationale', 'lint-ignore'];
-/** `kind` and the routing line are the document's contract (a doc without
- *  them is malformed); `origin` and `last-updated` are runtime provenance.
- *  Never removable via `--unset`, regardless of what the doc carries. */
-const PROTECTED_FIELDS = ['kind', 'when-and-why-to-read', 'origin', 'last-updated'];
-export const editLeaf = defineLeaf({
-    name: 'edit',
-    description: 'revise an existing memory document, recording why',
-    whenToUse: 'a document that already exists needs to change — its body, its frontmatter, or both. Every revision carries a --rationale and is appended to the doc\u2019s revision history, so the corpus keeps a record of why it reached its current state. Resolves the name exactly as `read` does and revises the doc where it lives; use `crtr memory write` only to create one that does not exist yet.',
-    help: {
-        name: 'memory edit',
-        summary: 'resolve an existing document and revise its body and/or frontmatter, appending a history record',
-        guide: 'The body you pipe is saved byte for byte. Nothing between stdin and disk parses, normalizes, summarizes, or rewrites it \u2014 the frontmatter fence is prepended and the text is otherwise untouched. Relaying a person\u2019s own words is therefore safe: pass them through unchanged and mark them with --verbatim.\n\n' +
-            'Two different rationales exist and they never share a flag. --rationale is why THIS REVISION is happening; it is required, it lands in the revision history, and it never touches the document text. --doc-rationale replaces the document\u2019s standing `rationale` frontmatter field \u2014 the observed gap the doc exists to close.\n\n' +
-            'Omitting stdin leaves the body exactly as it stands, which is how a frontmatter-only revision is made. Piping a body REPLACES the whole body; there is no partial or append mode. Emptying a document is not an edit \u2014 that intent is `crtr memory delete`.\n\n' +
-            'Omitted frontmatter flags preserve their fields. --unset is the only way to REMOVE one. The canonical clearable set (short-form, gate, surfaces, unlisted, slash, rationale, lint-ignore) is always accepted; any other field name is accepted only when the document’s frontmatter already carries it — the path for dropping a legacy or non-canonical field. --surface replaces the whole surfaces list rather than adding to it.\n\n' +
-            'An edit that changes nothing fails. A rationale attached to zero change is noise in the trail the history exists to build \u2014 if the doc already says what you meant, there is nothing to record.\n\n' +
-            '`last-updated` is stamped on every successful edit; `origin` is preserved, so it keeps pointing at the conversation that created the doc rather than the last one to touch it.\n\n' +
-            GUIDE_ROUTING_LINE + '\n\n' +
-            GUIDE_SURFACES + '\n\n' +
-            GUIDE_PREDICATE_VOCABULARY + '\n\n' +
-            GUIDE_CANONICAL_NAMES + '\n\n' +
-            GUIDE_DOC_LINKS + '\n\n' +
-            'Create a document that does not exist yet with `crtr memory write`. Read the revisions back with `crtr memory history`.',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical identity, resolved exactly in the target view or exact project store. A project document requires its complete `<namespace>/<local name>`; a directory document answers at the directory name, never with a trailing `/INDEX`. Same-store physical collisions are refused with both paths; `--dir` selects one exact project store. Builtin and installed-plugin docs are read-only corpora and are refused.' },
-            { kind: 'flag', name: 'rationale', type: 'string', required: true, constraint: 'Why THIS REVISION is happening \u2014 the audit-trail entry, required on every edit. Recorded in the document\u2019s revision history, NEVER written into the document. To change the doc\u2019s standing `rationale` frontmatter field instead, use --doc-rationale.' },
-            { kind: 'flag', name: 'verbatim', type: 'bool', required: false, constraint: 'Declares the piped body a verbatim payload from the principal \u2014 their own text, relayed unchanged \u2014 rather than agent-authored prose. Pure provenance recorded in the history record; the save path is identical either way, because there is only one save path and it never transforms.' },
-            overlayParam('kind'),
-            overlayParam('when-and-why-to-read'),
-            overlayParam('short-form'),
-            overlayParam('unlisted', {}, 'Presence SETS the field; remove it with `--unset unlisted`.'),
-            overlayParam('surface'),
-            overlayParam('gate'),
-            overlayParam('lint-ignore'),
-            overlayParam('slash', {}, 'Presence SETS the field; remove it with `--unset slash`.'),
-            { kind: 'flag', name: 'doc-rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
-            { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is revised.' },
-            { kind: 'flag', name: 'unset-extension', type: 'string', required: false, repeatable: true, constraint: 'Remove one explicitly persisted declared field by its full `extensions.<plugin>.<field>` path. A removed explicit value lets its declaration default apply only in structured output.' },
-            { kind: 'flag', name: 'unset', type: 'string', required: false, repeatable: true, constraint: `Remove a frontmatter field. One field per occurrence. ${CLEARABLE_FIELDS.join(', ')} are always accepted, whether or not the doc currently carries them. Any other field name is accepted only when the target document's frontmatter already carries it — this is the path for dropping a legacy or otherwise non-canonical field (e.g. a stale \`name:\` or \`description:\` left over from before \`when-and-why-to-read\`). Requesting a field the doc does not have fails, naming the fields it does have. \`${PROTECTED_FIELDS.join('\`, \`')}\` are never clearable.` },
-            selectorParam('scope-read', {}, 'Edit resolves the address winner and refuses same-store physical collisions.'),
-            selectorParam('dir'),
-            selectorParam('profile'),
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Full replacement body (markdown, no frontmatter), saved byte for byte. Piped on stdin only \u2014 this leaf already claims the one positional for NAME. Absent or empty stdin leaves the existing body untouched, which is how a frontmatter-only revision is made.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
-            { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter after the revision.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was revised in: node, project, profile, or user.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the revised document.' },
-            { name: 'revision', type: 'number', required: true, constraint: 'This document\u2019s record count after the append \u2014 the revision number to pass to `crtr memory history --revision`.' },
-            { name: 'changed', type: 'string[]', required: true, constraint: '`body` when the body text changed, plus the frontmatter field names whose values changed. `last-updated` is excluded \u2014 it is stamped on every edit, so naming it says nothing.' },
-        ],
-        outputKind: 'object',
-        dynamicState: () => memoryExtensionFieldCatalogHelp('edit'),
-        effects: [
-            'Rewrites the selected physical memory document and appends one `edit` record to its mirrored `.history` sidecar.'
-        ],
-    },
-    run: async (input) => {
-        const nameRaw = input['name'];
-        const scopeArg = input['scope'];
-        const rationale = input['rationale'];
-        const verbatim = input['verbatim'] === true;
-        const stdinBody = input['body'] ?? '';
-        const dirArg = input['dir'];
-        const profileArg = input['profile'];
-        const selector = resolveReadSelector({ scope: scopeArg, dir: dirArg, profile: profileArg });
-        let doc;
-        try {
-            const set = selector.store === null
-                ? resolveMemoryCandidates(nameRaw, {
-                    includeDescendants: true,
-                    ...(selector.scope === undefined ? {} : { scope: selector.scope }),
-                })
-                : (() => {
-                    requireLocalNameInStore(selector.store, nameRaw);
-                    return loadMemoryStoreView(selector.store, true).candidates(nameRaw);
-                })();
-            if (set === null) {
-                throw notFound(`memory document not found: ${nameRaw}`, {
-                    memory: nameRaw,
-                    next: `\`edit\` revises a document that already exists. Create it with \`crtr memory write ${nameRaw} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`,
-                });
-            }
-            doc = requireUnambiguousDoc(set);
-        }
-        catch (e) {
-            if (e instanceof CrtrError && e.code === 'not_found') {
-                throw notFound(`memory document not found: ${nameRaw}`, {
-                    memory: nameRaw,
-                    next: `\`edit\` revises a document that already exists. Create it with \`crtr memory write ${nameRaw} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`,
-                });
-            }
-            throw e;
-        }
-        if (doc.plugin !== undefined) {
-            throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" \u2014 a read-only corpus managed by \`crtr pkg\`, not editable here. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, plugin: doc.plugin });
-        }
-        if (doc.scope === 'builtin') {
-            throw usage(`${doc.name} is a builtin document shipped with the package (read-only) \u2014 it cannot be edited. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
-        }
-        const lintIgnore = coerceLintIgnore(input['lintIgnore']);
-        const extensionChanges = parseRequestedExtensionChanges(input['extension'], input['unsetExtension'], memoryExtensionCatalogForDoc(doc));
-        const before = readText(doc.path);
-        const parsed = parseFrontmatterGeneric(before);
-        const previous = { ...(parsed.data ?? {}) };
-        const frontmatter = { ...previous };
-        if (doc.scope === 'project' && doc.localName === '') {
-            if (doc.store.ownerRelativePath !== '' && Object.prototype.hasOwnProperty.call(previous, 'namespace')) {
-                throw usage(`a nested store's INDEX.md carries no namespace: — the repository at ${doc.store.repositoryRoot ?? doc.root} declares it`, {
-                    memory: doc.name,
-                    path: doc.path,
-                    next: `Run \`crtr memory lint --dir ${doc.store.ownerDir ?? doc.root}\` or \`crtr sys migrate --dir ${doc.store.repositoryRoot ?? doc.root}\`.`,
-                });
-            }
-            if (doc.store.ownerRelativePath === '' && previous['namespace'] !== doc.store.repositoryNamespace) {
-                throw usage(`the repository namespace on ${doc.path} is immutable; it must remain \`${doc.store.repositoryNamespace}\``, {
-                    memory: doc.name,
-                    path: doc.path,
-                });
-            }
-            if (previous['name'] !== undefined) {
-                throw usage(`the project root INDEX at ${doc.path} cannot carry a \`name:\` field`, {
-                    memory: doc.name,
-                    path: doc.path,
-                    next: `Run \`crtr sys migrate --dir ${doc.store.repositoryRoot ?? doc.store.ownerDir ?? doc.root}\`.`,
-                });
-            }
-        }
-        const setIf = (key, value) => {
-            if (value !== undefined)
-                frontmatter[key] = value;
-        };
-        setIf('kind', input['kind']);
-        setIf('when-and-why-to-read', input['whenAndWhyToRead']);
-        setIf('short-form', input['shortForm']);
-        if (input['unlisted'] === true)
-            frontmatter['unlisted'] = true;
-        if (input['surface'] !== undefined) {
-            frontmatter['surfaces'] = input['surface'].map(coerceSurface);
-        }
-        if (input['gate'] !== undefined)
-            frontmatter['gate'] = coerceGate(input['gate']);
-        setIf('lint-ignore', lintIgnore);
-        if (input['slash'] === true)
-            frontmatter['slash'] = true;
-        setIf('rationale', input['docRationale']);
-        applyExtensionChanges(frontmatter, extensionChanges.sets, extensionChanges.unsets);
-        for (const field of input['unset'] ?? []) {
-            if (PROTECTED_FIELDS.includes(field)) {
-                throw usage(`--unset ${field}: ${field} is never clearable`, {
-                    memory: doc.name,
-                    next: `Protected fields are ${PROTECTED_FIELDS.join(', ')}.`,
-                });
-            }
-            if (!CLEARABLE_FIELDS.includes(field) && !Object.prototype.hasOwnProperty.call(previous, field)) {
-                const present = Object.keys(previous).filter((key) => !PROTECTED_FIELDS.includes(key));
-                throw usage(`--unset ${field}: ${doc.name} has no \`${field}\` field to unset`, {
-                    memory: doc.name,
-                    next: present.length > 0
-                        ? `Fields ${doc.name} has: ${present.join(', ')}.`
-                        : `${doc.name} carries no field eligible for --unset.`,
-                });
-            }
-            delete frontmatter[field];
-        }
-        // Same invariant `write` raises: a workspace-open entry fires only when
-        // cwd/profile mounts the doc's project store, so outside project scope it
-        // is a dead route.
-        const surfacesVal = frontmatter['surfaces'];
-        if (doc.scope !== 'project' &&
-            Array.isArray(surfacesVal) &&
-            surfacesVal.some((e) => e !== null && typeof e === 'object' && e['on'] === 'workspace-open')) {
-            throw usage('a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one — drop the entry');
-        }
-        // LITERAL SAVE: a supplied body reaches disk unchanged; omitting stdin
-        // preserves the raw body after the fence, including leading whitespace.
-        const existingBody = literalBodySegment(before);
-        const body = stdinBody === '' ? existingBody : stdinBody;
-        // The no-op check compares the exact bytes that would be written, without
-        // a fresh timestamp — `last-updated` changes on every edit.
-        const candidate = serializeMemoryDocLiteral(frontmatter, body);
-        if (candidate === before) {
-            throw usage(`edit changed nothing \u2014 ${doc.name} already says exactly this, so there is nothing to record`, {
-                memory: doc.name,
-                next: 'Pipe a different body or pass a frontmatter flag that changes a value. To remove the doc entirely, use `crtr memory delete`.',
-            });
-        }
-        frontmatter['last-updated'] = new Date().toISOString();
-        const after = serializeMemoryDocLiteral(frontmatter, body);
-        writeText(doc.path, after);
-        const logPath = historyLogPathFor(doc.root, doc.path);
-        appendHistoryRecord(logPath, buildHistoryRecord({ op: 'edit', rationale, ...(verbatim ? { verbatim: true } : {}), before, after }));
-        const changedFields = [...new Set([...Object.keys(previous), ...Object.keys(frontmatter)])]
-            .filter((key) => key !== 'last-updated')
-            .filter((key) => JSON.stringify(previous[key]) !== JSON.stringify(frontmatter[key]))
-            .sort((a, b) => a.localeCompare(b));
-        const changed = [...(body !== existingBody ? ['body'] : []), ...changedFields];
-        return {
-            name: doc.name,
-            kind: String(frontmatter['kind'] ?? ''),
-            scope: doc.scope,
-            path: doc.path,
-            revision: readHistoryRecords(logPath).length,
-            changed,
-        };
-    },
-});
+var D=Object.defineProperty;var m=(r,n)=>D(r,"name",{value:n,configurable:!0});import{defineLeaf as j}from"../../core/command.js";import{CrtrError as P,notFound as E,usage as a}from"../../core/errors.js";import{parseFrontmatterGeneric as L}from"../../core/frontmatter.js";import{readText as _,writeText as F}from"../../core/fs-utils.js";import{loadMemoryStoreView as U,resolveMemoryCandidates as G}from"../../core/memory-resolver.js";import{appendHistoryRecord as V,buildHistoryRecord as B,historyLogPathFor as H,readHistoryRecords as M}from"../../core/memory/history.js";import{DOC_RATIONALE_CONSTRAINT as z,GUIDE_CANONICAL_NAMES as K,GUIDE_DOC_LINKS as X,GUIDE_PREDICATE_VOCABULARY as J,GUIDE_ROUTING_LINE as W,GUIDE_SURFACES as Y,coerceGate as Q,coerceLintIgnore as Z,coerceSurface as ee,memoryExtensionCatalogForDoc as te,memoryExtensionFieldCatalogHelp as re,overlayParam as s,parseRequestedExtensionChanges as oe,applyExtensionChanges as ne,literalBodySegment as ae,serializeMemoryDocLiteral as R,selectorParam as y,requireLocalNameInStore as ie,requireUnambiguousDoc as se,resolveReadSelector as de}from"./shared.js";const S=["short-form","gate","surfaces","unlisted","slash","rationale","lint-ignore"],u=["kind","when-and-why-to-read","origin","last-updated"],ve=j({name:"edit",description:"revise an existing memory document, recording why",whenToUse:"a document that already exists needs to change \u2014 its body, its frontmatter, or both. Every revision carries a --rationale and is appended to the doc\u2019s revision history, so the corpus keeps a record of why it reached its current state. Resolves the name exactly as `read` does and revises the doc where it lives; use `crtr memory write` only to create one that does not exist yet.",help:{name:"memory edit",summary:"resolve an existing document and revise its body and/or frontmatter, appending a history record",guide:`The body you pipe is saved byte for byte. Nothing between stdin and disk parses, normalizes, summarizes, or rewrites it \u2014 the frontmatter fence is prepended and the text is otherwise untouched. Relaying a person\u2019s own words is therefore safe: pass them through unchanged and mark them with --verbatim.
+
+Two different rationales exist and they never share a flag. --rationale is why THIS REVISION is happening; it is required, it lands in the revision history, and it never touches the document text. --doc-rationale replaces the document\u2019s standing \`rationale\` frontmatter field \u2014 the observed gap the doc exists to close.
+
+Omitting stdin leaves the body exactly as it stands, which is how a frontmatter-only revision is made. Piping a body REPLACES the whole body; there is no partial or append mode. Emptying a document is not an edit \u2014 that intent is \`crtr memory delete\`.
+
+Omitted frontmatter flags preserve their fields. --unset is the only way to REMOVE one. The canonical clearable set (short-form, gate, surfaces, unlisted, slash, rationale, lint-ignore) is always accepted; any other field name is accepted only when the document\u2019s frontmatter already carries it \u2014 the path for dropping a legacy or non-canonical field. --surface replaces the whole surfaces list rather than adding to it.
+
+An edit that changes nothing fails. A rationale attached to zero change is noise in the trail the history exists to build \u2014 if the doc already says what you meant, there is nothing to record.
+
+\`last-updated\` is stamped on every successful edit; \`origin\` is preserved, so it keeps pointing at the conversation that created the doc rather than the last one to touch it.
+
+`+W+`
+
+`+Y+`
+
+`+J+`
+
+`+K+`
+
+`+X+"\n\nCreate a document that does not exist yet with `crtr memory write`. Read the revisions back with `crtr memory history`.",params:[{kind:"positional",name:"name",required:!0,constraint:"Full canonical identity, resolved exactly in the target view or exact project store. A project document requires its complete `<namespace>/<local name>`; a directory document answers at the directory name, never with a trailing `/INDEX`. Same-store physical collisions are refused with both paths; `--dir` selects one exact project store. Builtin and installed-plugin docs are read-only corpora and are refused."},{kind:"flag",name:"rationale",type:"string",required:!0,constraint:"Why THIS REVISION is happening \u2014 the audit-trail entry, required on every edit. Recorded in the document\u2019s revision history, NEVER written into the document. To change the doc\u2019s standing `rationale` frontmatter field instead, use --doc-rationale."},{kind:"flag",name:"verbatim",type:"bool",required:!1,constraint:"Declares the piped body a verbatim payload from the principal \u2014 their own text, relayed unchanged \u2014 rather than agent-authored prose. Pure provenance recorded in the history record; the save path is identical either way, because there is only one save path and it never transforms."},s("kind"),s("when-and-why-to-read"),s("short-form"),s("unlisted",{},"Presence SETS the field; remove it with `--unset unlisted`."),s("surface"),s("gate"),s("lint-ignore"),s("slash",{},"Presence SETS the field; remove it with `--unset slash`."),{kind:"flag",name:"doc-rationale",type:"string",required:!1,constraint:z},{kind:"flag",name:"extension",type:"string",required:!1,repeatable:!0,constraint:"Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is revised."},{kind:"flag",name:"unset-extension",type:"string",required:!1,repeatable:!0,constraint:"Remove one explicitly persisted declared field by its full `extensions.<plugin>.<field>` path. A removed explicit value lets its declaration default apply only in structured output."},{kind:"flag",name:"unset",type:"string",required:!1,repeatable:!0,constraint:`Remove a frontmatter field. One field per occurrence. ${S.join(", ")} are always accepted, whether or not the doc currently carries them. Any other field name is accepted only when the target document's frontmatter already carries it \u2014 this is the path for dropping a legacy or otherwise non-canonical field (e.g. a stale \`name:\` or \`description:\` left over from before \`when-and-why-to-read\`). Requesting a field the doc does not have fails, naming the fields it does have. \`${u.join("`, `")}\` are never clearable.`},y("scope-read",{},"Edit resolves the address winner and refuses same-store physical collisions."),y("dir"),y("profile"),{kind:"stdin",name:"body",required:!1,constraint:"Full replacement body (markdown, no frontmatter), saved byte for byte. Piped on stdin only \u2014 this leaf already claims the one positional for NAME. Absent or empty stdin leaves the existing body untouched, which is how a frontmatter-only revision is made."}],output:[{name:"name",type:"string",required:!0,constraint:"Resolved document name."},{name:"kind",type:"string",required:!0,constraint:"Kind recorded in frontmatter after the revision."},{name:"scope",type:"string",required:!0,constraint:"Scope the document was revised in: node, project, profile, or user."},{name:"path",type:"string",required:!0,constraint:"Absolute path to the revised document."},{name:"revision",type:"number",required:!0,constraint:"This document\u2019s record count after the append \u2014 the revision number to pass to `crtr memory history --revision`."},{name:"changed",type:"string[]",required:!0,constraint:"`body` when the body text changed, plus the frontmatter field names whose values changed. `last-updated` is excluded \u2014 it is stamped on every edit, so naming it says nothing."}],outputKind:"object",dynamicState:m(()=>re("edit"),"dynamicState"),effects:["Rewrites the selected physical memory document and appends one `edit` record to its mirrored `.history` sidecar."]},run:m(async r=>{const n=r.name,I=r.scope,A=r.rationale,$=r.verbatim===!0,f=r.body??"",k=r.dir,q=r.profile,c=de({scope:I,dir:k,profile:q});let e;try{const t=c.store===null?G(n,{includeDescendants:!0,...c.scope===void 0?{}:{scope:c.scope}}):(ie(c.store,n),U(c.store,!0).candidates(n));if(t===null)throw E(`memory document not found: ${n}`,{memory:n,next:`\`edit\` revises a document that already exists. Create it with \`crtr memory write ${n} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`});e=se(t)}catch(t){throw t instanceof P&&t.code==="not_found"?E(`memory document not found: ${n}`,{memory:n,next:`\`edit\` revises a document that already exists. Create it with \`crtr memory write ${n} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`}):t}if(e.plugin!==void 0)throw a(`${e.name} belongs to the installed plugin "${e.plugin}" \u2014 a read-only corpus managed by \`crtr pkg\`, not editable here. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${e.name} ...\`).`,{memory:e.name,plugin:e.plugin});if(e.scope==="builtin")throw a(`${e.name} is a builtin document shipped with the package (read-only) \u2014 it cannot be edited. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${e.name} ...\`).`,{memory:e.name,scope:"builtin"});const O=Z(r.lintIgnore),g=oe(r.extension,r.unsetExtension,te(e)),h=_(e.path),i={...L(h).data??{}},o={...i};if(e.scope==="project"&&e.localName===""){if(e.store.ownerRelativePath!==""&&Object.prototype.hasOwnProperty.call(i,"namespace"))throw a(`a nested store's INDEX.md carries no namespace: \u2014 the repository at ${e.store.repositoryRoot??e.root} declares it`,{memory:e.name,path:e.path,next:`Run \`crtr memory lint --dir ${e.store.ownerDir??e.root}\` or \`crtr sys migrate --dir ${e.store.repositoryRoot??e.root}\`.`});if(e.store.ownerRelativePath===""&&i.namespace!==e.store.repositoryNamespace)throw a(`the repository namespace on ${e.path} is immutable; it must remain \`${e.store.repositoryNamespace}\``,{memory:e.name,path:e.path});if(i.name!==void 0)throw a(`the project root INDEX at ${e.path} cannot carry a \`name:\` field`,{memory:e.name,path:e.path,next:`Run \`crtr sys migrate --dir ${e.store.repositoryRoot??e.store.ownerDir??e.root}\`.`})}const l=m((t,d)=>{d!==void 0&&(o[t]=d)},"setIf");l("kind",r.kind),l("when-and-why-to-read",r.whenAndWhyToRead),l("short-form",r.shortForm),r.unlisted===!0&&(o.unlisted=!0),r.surface!==void 0&&(o.surfaces=r.surface.map(ee)),r.gate!==void 0&&(o.gate=Q(r.gate)),l("lint-ignore",O),r.slash===!0&&(o.slash=!0),l("rationale",r.docRationale),ne(o,g.sets,g.unsets);for(const t of r.unset??[]){if(u.includes(t))throw a(`--unset ${t}: ${t} is never clearable`,{memory:e.name,next:`Protected fields are ${u.join(", ")}.`});if(!S.includes(t)&&!Object.prototype.hasOwnProperty.call(i,t)){const d=Object.keys(i).filter(C=>!u.includes(C));throw a(`--unset ${t}: ${e.name} has no \`${t}\` field to unset`,{memory:e.name,next:d.length>0?`Fields ${e.name} has: ${d.join(", ")}.`:`${e.name} carries no field eligible for --unset.`})}delete o[t]}const w=o.surfaces;if(e.scope!=="project"&&Array.isArray(w)&&w.some(t=>t!==null&&typeof t=="object"&&t.on==="workspace-open"))throw a("a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one \u2014 drop the entry");const v=ae(h),p=f===""?v:f;if(R(o,p)===h)throw a(`edit changed nothing \u2014 ${e.name} already says exactly this, so there is nothing to record`,{memory:e.name,next:"Pipe a different body or pass a frontmatter flag that changes a value. To remove the doc entirely, use `crtr memory delete`."});o["last-updated"]=new Date().toISOString();const b=R(o,p);F(e.path,b);const x=H(e.root,e.path);V(x,B({op:"edit",rationale:A,...$?{verbatim:!0}:{},before:h,after:b}));const N=[...new Set([...Object.keys(i),...Object.keys(o)])].filter(t=>t!=="last-updated").filter(t=>JSON.stringify(i[t])!==JSON.stringify(o[t])).sort((t,d)=>t.localeCompare(d)),T=[...p!==v?["body"]:[],...N];return{name:e.name,kind:String(o.kind??""),scope:e.scope,path:e.path,revision:M(x).length,changed:T}},"run")});export{ve as editLeaf};