@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/document.js

@@ -0,0 +1,373 @@
+/**
+ * One memory file parsed into heading nodes (`document.rs`). Parsing never fails and rendering
+ * reproduces the source bytes exactly; only nodes that were written regenerate their heading or
+ * metadata line. Headings are found with a CommonMark parser, so `#` lines inside fences, quotes
+ * and lists stay body text.
+ */
+import { createHash } from 'node:crypto';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { MAX_NODE_LEVEL } from './constants.js';
+const META_PREFIX = '<!-- mem ';
+const META_VALUE = /^[A-Za-z0-9\-_.:]+$/;
+/** Whether a value can be stored in a metadata line and read back. */
+export function isMetaValue(value) {
+    return META_VALUE.test(value);
+}
+/** Parse one metadata line; malformed lines are ordinary body text. */
+export function parseMetaLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith(META_PREFIX) || !trimmed.endsWith('-->'))
+        return undefined;
+    const inner = trimmed.slice(META_PREFIX.length, trimmed.length - 3).trim();
+    const fields = {};
+    let source;
+    for (const pair of inner.split(/\s+/).filter(part => part !== '')) {
+        const equals = pair.indexOf('=');
+        if (equals < 0)
+            return undefined;
+        const key = pair.slice(0, equals);
+        const value = pair.slice(equals + 1);
+        if (!META_VALUE.test(value))
+            return undefined;
+        switch (key) {
+            case 'id':
+            case 'section':
+            case 'created':
+            case 'updated':
+            case 'session':
+                fields[key] = value;
+                break;
+            case 'source':
+                if (value !== 'ai' && value !== 'user')
+                    return undefined;
+                source = value;
+                break;
+        }
+    }
+    if (fields.id === undefined || fields.created === undefined || fields.updated === undefined || source === undefined)
+        return undefined;
+    return {
+        id: fields.id,
+        ...fields.section === undefined ? {} : { section: fields.section },
+        created: fields.created,
+        updated: fields.updated,
+        ...fields.session === undefined ? {} : { session: fields.session },
+        source,
+    };
+}
+/** Render a metadata comment without a line terminator. */
+export function renderMeta(meta) {
+    let line = `${META_PREFIX}id=${meta.id}`;
+    if (meta.section !== undefined)
+        line += ` section=${meta.section}`;
+    line += ` created=${meta.created} updated=${meta.updated}`;
+    if (meta.session !== undefined)
+        line += ` session=${meta.session}`;
+    return `${line} source=${meta.source} -->`;
+}
+/** One heading node with its own body and child nodes. */
+export class MemoryNode {
+    level;
+    title;
+    meta;
+    body;
+    /** Original heading bytes including the terminator; `undefined` regenerates it. */
+    headingRaw;
+    /** Original metadata line including the terminator; `undefined` regenerates it. */
+    metaRaw;
+    children = [];
+    constructor(level, title, meta, 
+    /** Own body bytes up to the next node heading. */
+    body, raw) {
+        this.level = level;
+        this.title = title;
+        this.meta = meta;
+        this.body = body;
+        this.headingRaw = raw?.heading;
+        this.metaRaw = raw?.meta;
+    }
+    /** Copy without children for another document: lines regenerate at `level`, the body uses `eol`. */
+    detached(level, eol) {
+        return new MemoryNode(level, this.title, this.meta, storedBody(this.bodyText(), eol));
+    }
+    rawBody() {
+        return this.body;
+    }
+    /** The own body with normalized line endings and no surrounding blank lines. */
+    bodyText() {
+        return normalizeNewlines(this.body).replace(/^\n+|\n+$/g, '').trimEnd();
+    }
+    setBody(body) {
+        this.body = body;
+    }
+    setTitle(title) {
+        this.title = title;
+        this.headingRaw = undefined;
+    }
+    setMeta(meta) {
+        this.meta = meta;
+        this.metaRaw = undefined;
+    }
+    /** Shift the subtree to a new root level; returns the deepest level reached when it does not fit. */
+    relevel(level) {
+        const deepest = level + this.subtreeDepth();
+        if (level === 0 || deepest > MAX_NODE_LEVEL)
+            return deepest;
+        this.shiftLevels(level - this.level);
+        return undefined;
+    }
+    subtreeDepth() {
+        return Math.max(0, ...this.children.map(child => Math.max(0, child.level - this.level) + child.subtreeDepth()));
+    }
+    shiftLevels(delta) {
+        if (delta !== 0) {
+            this.level += delta;
+            this.headingRaw = undefined;
+        }
+        for (const child of this.children)
+            child.shiftLevels(delta);
+    }
+    /** Revision token of the node's own title and body. */
+    revision() {
+        return createHash('sha256').update(this.title.trim()).update(Buffer.from([0])).update(this.bodyText()).digest('hex').slice(0, 8);
+    }
+    descendantCount() {
+        return this.children.reduce((count, child) => count + 1 + child.descendantCount(), 0);
+    }
+    /** Append this subtree's text, reusing original bytes wherever they are still valid. */
+    render(eol, output) {
+        ensureLineStart(output, eol);
+        output.push(this.headingRaw ?? `${'#'.repeat(this.level)} ${this.title}${eol}`);
+        if (this.meta !== undefined) {
+            ensureLineStart(output, eol);
+            output.push(this.metaRaw ?? `${renderMeta(this.meta)}${eol}`);
+        }
+        if (this.body !== '') {
+            ensureLineStart(output, eol);
+            output.push(this.body);
+        }
+        for (const child of this.children)
+            child.render(eol, output);
+    }
+}
+/** The last title of a view's path. */
+export function viewTitle(view) {
+    return view.path[view.path.length - 1] ?? '';
+}
+/** One parsed memory file. */
+export class MemoryDocument {
+    eol;
+    preamble;
+    roots;
+    constructor(
+    /** Line terminator for generated lines, taken from the source. */
+    eol, 
+    /** Bytes before the first node heading. */
+    preamble, roots) {
+        this.eol = eol;
+        this.preamble = preamble;
+        this.roots = roots;
+    }
+    static empty() {
+        return new MemoryDocument('\n', '', []);
+    }
+    static parse(text) {
+        const eol = text.includes('\r\n') ? '\r\n' : '\n';
+        const headings = scanHeadings(text);
+        const first = headings[0];
+        if (first === undefined)
+            return new MemoryDocument(eol, text, []);
+        const flat = headings.map((heading, index) => {
+            const ownEnd = headings[index + 1]?.start ?? text.length;
+            const headingRaw = text.slice(heading.start, heading.after);
+            let bodyStart = heading.after;
+            let meta;
+            let metaRaw;
+            if (bodyStart < ownEnd) {
+                const newline = text.slice(bodyStart, ownEnd).indexOf('\n');
+                const lineEnd = newline < 0 ? ownEnd : bodyStart + newline + 1;
+                meta = parseMetaLine(text.slice(bodyStart, lineEnd));
+                if (meta !== undefined) {
+                    metaRaw = text.slice(bodyStart, lineEnd);
+                    bodyStart = lineEnd;
+                }
+            }
+            return new MemoryNode(heading.level, headingTitle(headingRaw, heading.level), meta, text.slice(bodyStart, ownEnd), { heading: headingRaw, meta: metaRaw });
+        });
+        return new MemoryDocument(eol, text.slice(0, first.start), buildTree(flat));
+    }
+    render() {
+        const output = [this.preamble];
+        for (const node of this.roots)
+            node.render(this.eol, output);
+        return output.join('');
+    }
+    /** Views of every node in document order. */
+    views(scope) {
+        const views = [];
+        const occurrences = new Map();
+        this.roots.forEach((node, index) => {
+            const section = node.level === 1 ? node.meta?.section : undefined;
+            collectViews(node, scope, [], [index], section, occurrences, views);
+        });
+        return views;
+    }
+    node(locator) {
+        const [first, ...rest] = locator;
+        if (first === undefined)
+            return undefined;
+        let node = this.roots[first];
+        for (const index of rest)
+            node = node?.children[index];
+        return node;
+    }
+    /** Remove and return the subtree at a locator. */
+    remove(locator) {
+        const last = locator[locator.length - 1];
+        if (last === undefined)
+            return undefined;
+        const parent = locator.slice(0, -1);
+        const siblings = parent.length === 0 ? this.roots : this.node(parent)?.children;
+        if (siblings === undefined || last >= siblings.length)
+            return undefined;
+        return siblings.splice(last, 1)[0];
+    }
+    /** Append a subtree as the last child of a parent, or as the last top-level node. */
+    append(parent, node) {
+        if (parent === undefined) {
+            this.roots.push(node);
+            return true;
+        }
+        const target = this.node(parent);
+        if (target === undefined)
+            return false;
+        target.children.push(node);
+        return true;
+    }
+}
+/** Convert written text into stored body bytes: the file's terminators and one trailing blank line. */
+export function storedBody(text, eol) {
+    const trimmed = normalizeNewlines(text).replace(/^\n+|\n+$/g, '').trimEnd();
+    if (trimmed === '')
+        return eol;
+    return `${trimmed.replaceAll('\n', eol)}${eol}${eol}`;
+}
+/** Levels of node-forming headings in text written as a body. */
+export function nodeHeadingLevels(text) {
+    return scanHeadings(text).map(heading => heading.level);
+}
+/** Whether text renders as exactly one ATX heading with the given title. */
+export function titleRoundTrips(level, title) {
+    const line = `${'#'.repeat(level)} ${title}\n`;
+    const headings = scanHeadings(line);
+    const [only] = headings;
+    return headings.length === 1 && only !== undefined && only.level === level
+        && headingTitle(line.slice(only.start, only.after), level) === title;
+}
+function normalizeNewlines(text) {
+    return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+}
+/** Top-level H1–H4 headings; a heading inside a quote, list or fence is not top level. */
+function scanHeadings(text) {
+    const headings = [];
+    for (const child of fromMarkdown(text).children) {
+        if (child.type !== 'heading' || child.depth > MAX_NODE_LEVEL)
+            continue;
+        const start = child.position?.start.offset;
+        const end = child.position?.end.offset;
+        if (start === undefined || end === undefined)
+            continue;
+        const last = Math.max(end - 1, start);
+        const newline = text.indexOf('\n', last);
+        headings.push({ start, after: newline < 0 ? text.length : newline + 1, level: child.depth });
+    }
+    return headings;
+}
+/** Rust `str::lines`: split on `\n`, drop one trailing empty line, strip a `\r` ending each line. */
+export function lines(text) {
+    const parts = text.split('\n');
+    if (parts[parts.length - 1] === '')
+        parts.pop();
+    return parts.map(line => line.endsWith('\r') ? line.slice(0, -1) : line);
+}
+/** The raw title text of an ATX or setext heading's source. */
+function headingTitle(raw, level) {
+    const all = lines(raw);
+    const first = all[0] ?? '';
+    const stripped = first.replace(/^ +/, '');
+    const marker = '#'.repeat(level);
+    if (first.length - stripped.length <= 3 && stripped.startsWith(marker)) {
+        const rest = stripped.slice(marker.length);
+        if (rest === '' || rest.startsWith(' ') || rest.startsWith('\t')) {
+            const content = rest.trim();
+            const withoutClosing = content.replace(/#+$/, '');
+            if (withoutClosing === '')
+                return '';
+            return /[ \t]$/.test(withoutClosing) ? withoutClosing.trimEnd() : content;
+        }
+    }
+    return all.slice(0, Math.max(0, all.length - 1)).map(line => line.trim()).join(' ');
+}
+/** Nest a flat heading list into a tree by level. */
+function buildTree(flat) {
+    const roots = [];
+    const stack = [];
+    const attach = (node) => {
+        const parent = stack[stack.length - 1];
+        if (parent === undefined)
+            roots.push(node);
+        else
+            parent.children.push(node);
+    };
+    for (const node of flat) {
+        while ((stack[stack.length - 1]?.level ?? 0) >= node.level)
+            attach(stack.pop());
+        stack.push(node);
+    }
+    while (stack.length > 0)
+        attach(stack.pop());
+    return roots;
+}
+function ensureLineStart(output, eol) {
+    const last = output.findLast(part => part !== '');
+    if (last !== undefined && !last.endsWith('\n'))
+        output.push(eol);
+}
+function collectViews(node, scope, path, locator, section, occurrences, views) {
+    path.push(node.title);
+    let id = node.meta?.id;
+    if (id === undefined) {
+        const key = JSON.stringify(path);
+        const occurrence = (occurrences.get(key) ?? 0) + 1;
+        occurrences.set(key, occurrence);
+        id = derivedNodeId(scope, path, occurrence);
+    }
+    views.push({
+        id,
+        scope,
+        level: node.level,
+        path: [...path],
+        locator: [...locator],
+        section,
+        revision: node.revision(),
+        meta: node.meta,
+        body: node.bodyText(),
+        children: node.children.map(child => child.title),
+        descendants: node.descendantCount(),
+    });
+    node.children.forEach((child, index) => {
+        locator.push(index);
+        collectViews(child, scope, path, locator, section, occurrences, views);
+        locator.pop();
+    });
+    path.pop();
+}
+/** Stable id of a node without metadata, from its scope, title path and occurrence. */
+function derivedNodeId(scope, path, occurrence) {
+    const hash = createHash('sha256').update(scope);
+    const separator = Buffer.from([0x1f]);
+    for (const title of path)
+        hash.update(separator).update(title);
+    hash.update(separator).update(String(occurrence));
+    return `h-${hash.digest('hex').slice(0, 10)}`;
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/errors.d.ts

@@ -0,0 +1,14 @@
+/** Failures of the Markdown memory store; every message is English and safe to return to the model (`error.rs`). */
+export type MemoryErrorKind = 'invalid' | 'not_found' | 'revision_mismatch' | 'project_unavailable' | 'unsupported_format' | 'concurrent_modification' | 'rollback_incomplete' | 'io' | 'json';
+export declare class MemoryError extends Error {
+    readonly kind: MemoryErrorKind;
+    constructor(kind: MemoryErrorKind, message: string);
+    static invalid(message: string): MemoryError;
+    static notFound(id: string): MemoryError;
+    static revisionMismatch(id: string, expected: string, current: string): MemoryError;
+    static concurrent(path: string): MemoryError;
+    static io(path: string, action: string, cause: unknown): MemoryError;
+    static json(path: string, message: string): MemoryError;
+    /** One operation of a multi-operation write failed; nothing was written. */
+    static operation(index: number, cause: MemoryError): MemoryError;
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/errors.js

@@ -0,0 +1,31 @@
+/** Failures of the Markdown memory store; every message is English and safe to return to the model (`error.rs`). */
+export class MemoryError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'MemoryError';
+    }
+    static invalid(message) {
+        return new MemoryError('invalid', message);
+    }
+    static notFound(id) {
+        return new MemoryError('not_found', `Memory node \`${id}\` was not found; run memory_outline or memory_search to get current ids.`);
+    }
+    static revisionMismatch(id, expected, current) {
+        return new MemoryError('revision_mismatch', `Memory node \`${id}\` changed (expected revision ${expected}, current ${current}); read it again before writing.`);
+    }
+    static concurrent(path) {
+        return new MemoryError('concurrent_modification', `Memory file \`${path}\` changed on disk while the write was prepared; retry the write.`);
+    }
+    static io(path, action, cause) {
+        return new MemoryError('io', `Memory file \`${path}\` could not be ${action}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    static json(path, message) {
+        return new MemoryError('json', `Memory file \`${path}\` is not valid JSON: ${message}`);
+    }
+    /** One operation of a multi-operation write failed; nothing was written. */
+    static operation(index, cause) {
+        return new MemoryError(cause.kind, `Operation #${index} (counting from 1) failed, so no change was written: ${cause.message}`);
+    }
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/index.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Markdown memory as the plugin uses it: resolve whether memory is active for a session's project,
+ * run the three tools, and build the injection snapshot. Everything Markdown-specific stays below
+ * this module; the plugin entry only calls these functions.
+ */
+import { type WriteAuthor } from './operations.js';
+import { type MemoryScope } from './scope.js';
+import { type OutlineRequest, type SearchRequest } from './search.js';
+import { MarkdownMemoryStore, type ProjectContext } from './store.js';
+import type { InjectionBudget, MemorySettings } from '../settings.js';
+export { MarkdownMemoryStore } from './store.js';
+export type { ProjectContext } from './store.js';
+/** Memory reachable from one session: the store, its project and the budget. */
+export interface MarkdownMemoryAccess {
+    readonly store: MarkdownMemoryStore;
+    readonly context: ProjectContext;
+    readonly budget: InjectionBudget;
+}
+/**
+ * Memory of a project, or `undefined` when the mode is not `markdown` or the user turned memory
+ * off for this project (which also hides the user and space scopes), as VulcanCode resolves it.
+ */
+export declare function resolveAccess(store: MarkdownMemoryStore, settings: MemorySettings, context: ProjectContext): MarkdownMemoryAccess | undefined;
+export declare const NOT_ACTIVE_MESSAGE = "Markdown memory is not active for this conversation; the memory mode changed or memory is off for this project.";
+export declare function outline(access: MarkdownMemoryAccess, args: unknown): string;
+export declare function search(access: MarkdownMemoryAccess, args: unknown): string;
+export declare function write(access: MarkdownMemoryAccess, author: WriteAuthor, args: unknown): string;
+/** The snapshot text injected into a conversation; empty when every scope is empty. */
+export declare function snapshot(access: MarkdownMemoryAccess): string;
+/** Model-facing names, descriptions and schemas, the same text VulcanCode registers. */
+export declare const TOOL_SPECS: {
+    readonly outline: {
+        readonly name: "memory_outline";
+        readonly description: "List the heading tree of long-term memory: the user profile, space memory (rules for every project) and this project's memory, with node ids, revisions, update dates and body sizes. Use it to see what is remembered and where a new fact belongs before memory_write.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly scopes: {
+                    readonly type: "array";
+                    readonly uniqueItems: true;
+                    readonly items: {
+                        type: string;
+                        enum: MemoryScope[];
+                    };
+                    readonly description: "Scopes to list; defaults to all.";
+                };
+                readonly section: {
+                    readonly type: "string";
+                    readonly description: "Section key or H1 title to list.";
+                };
+                readonly pathPrefix: {
+                    readonly type: "string";
+                    readonly description: "Title path prefix, segments separated by `/`.";
+                };
+                readonly depth: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 4;
+                    readonly description: "Deepest heading level listed; defaults to all.";
+                };
+            };
+        };
+    };
+    readonly search: {
+        readonly name: "memory_search";
+        readonly description: "Search long-term memory nodes with several patterns combined with OR (regex unless fixedStrings; case-insensitive by default), optionally limited to scopes, a section or a title path prefix; or read nodes by id. Each result is a whole node: scope, title path, id, revision, update time and body, with matching lines prefixed by `>> `. Catalog lines injected at session start are titles only: read the node before relying on it or changing it.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly patterns: {
+                    readonly type: "array";
+                    readonly maxItems: 12;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly description: "Patterns combined with OR; include synonyms and other languages. Mutually exclusive with ids.";
+                };
+                readonly fixedStrings: {
+                    readonly type: "boolean";
+                    readonly description: "Match patterns as literal text.";
+                };
+                readonly ignoreCase: {
+                    readonly type: "boolean";
+                    readonly description: "Case-insensitive matching; defaults to true.";
+                };
+                readonly scopes: {
+                    readonly type: "array";
+                    readonly uniqueItems: true;
+                    readonly items: {
+                        type: string;
+                        enum: MemoryScope[];
+                    };
+                    readonly description: "Scopes to search; defaults to all.";
+                };
+                readonly section: {
+                    readonly type: "string";
+                    readonly description: "Section key or H1 title filter.";
+                };
+                readonly pathPrefix: {
+                    readonly type: "string";
+                    readonly description: "Title path prefix filter, segments separated by `/`.";
+                };
+                readonly ids: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Node ids to read whole. Mutually exclusive with patterns.";
+                };
+                readonly limit: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 20;
+                    readonly description: "Nodes per page.";
+                };
+                readonly cursor: {
+                    readonly type: "string";
+                    readonly description: "Cursor from a previous result: the next result page, or the next body page of a single id.";
+                };
+            };
+        };
+    };
+    readonly write: {
+        readonly name: "memory_write";
+        readonly description: "Change long-term memory with 1 to 16 operations applied all-or-nothing: create, replace, append, rename, move (across scopes and sections too) and delete. create needs a scope and exactly one of parentId, section or newSection. Every action except create needs the node's current expectedRevision from memory_search or memory_outline. Scopes: `user` describes who the user is; `space` holds rules and environment that hold for every project; `project` holds facts, decisions and constraints of this project only. The `base` section of space and project is injected in full every session, so keep it to a few critical, stable rules and put the rest in other sections. Write when the user asks you to remember something, corrects your approach, or a decision is made that the repository does not show. Make titles state the fact itself; bodies cannot contain H1-H4 headings.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly operations: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 16;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly action: {
+                                readonly type: "string";
+                                readonly enum: readonly ["create", "replace", "append", "rename", "move", "delete"];
+                            };
+                            readonly id: {
+                                readonly type: "string";
+                                readonly description: "Node id; every action except create.";
+                            };
+                            readonly expectedRevision: {
+                                readonly type: "string";
+                                readonly description: "Revision last read; every action except create.";
+                            };
+                            readonly scope: {
+                                readonly type: "string";
+                                readonly enum: readonly MemoryScope[];
+                                readonly description: "Destination scope; required for create, optional for move.";
+                            };
+                            readonly parentId: {
+                                readonly type: "string";
+                                readonly description: "create/move: become the last child of this node.";
+                            };
+                            readonly section: {
+                                readonly type: "string";
+                                readonly description: `create/move: become a child of this section, by key or H1 title. New files start with the preset sections: ${string}.`;
+                            };
+                            readonly newSection: {
+                                readonly type: "boolean";
+                                readonly description: "create/move: become a new H1 section. Give exactly one of parentId, section, newSection.";
+                            };
+                            readonly title: {
+                                readonly type: "string";
+                                readonly description: "create/rename: heading text.";
+                            };
+                            readonly body: {
+                                readonly type: "string";
+                                readonly description: "create/replace: Markdown body. replace keeps the title; change it with rename.";
+                            };
+                            readonly text: {
+                                readonly type: "string";
+                                readonly description: "append: Markdown appended after a blank line.";
+                            };
+                            readonly withChildren: {
+                                readonly type: "boolean";
+                                readonly description: "delete: also delete child nodes.";
+                            };
+                        };
+                        readonly required: readonly ["action"];
+                    };
+                };
+            };
+            readonly required: readonly ["operations"];
+        };
+    };
+};
+export declare function parseOutlineRequest(args: unknown): OutlineRequest;
+export declare function parseSearchRequest(args: unknown): SearchRequest;