poe-code 3.0.183 → 3.0.185

package/packages/memory/dist/edit.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryDiff, MemoryRoot } from "./types.js";
+export type EditPageOptions = {
+    reason: string;
+    launchEditor: (filePath: string) => Promise<void>;
+};
+export type EditPageResult = {
+    changed: boolean;
+    diff?: MemoryDiff;
+};
+export declare function editPage(root: MemoryRoot, relPath: string, opts: EditPageOptions): Promise<EditPageResult>;

package/packages/memory/dist/edit.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+import { writePage } from "./write.js";
+export async function editPage(root, relPath, opts) {
+    const pagePath = path.join(root, relPath);
+    const original = await readIfPresent(pagePath);
+    const tempRoot = path.join(root, ".tmp");
+    await fs.mkdir(tempRoot, { recursive: true });
+    const tempDir = await fs.mkdtemp(path.join(tempRoot, "poe-code-memory-edit-"));
+    const tempPath = path.join(tempDir, path.basename(relPath));
+    try {
+        await fs.writeFile(tempPath, original ?? "", "utf8");
+        await opts.launchEditor(tempPath);
+        const edited = await fs.readFile(tempPath, "utf8");
+        if (edited === (original ?? "")) {
+            return { changed: false };
+        }
+        const parsed = parseFrontmatter(edited);
+        const diff = await writePage(root, relPath, parsed.body, {
+            frontmatter: parsed.frontmatter,
+            reason: opts.reason
+        });
+        return {
+            changed: true,
+            diff
+        };
+    }
+    finally {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function readIfPresent(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/packages/memory/dist/explain.cli.d.ts

@@ -0,0 +1,8 @@
+import type { ExplainResult, SpawnFn } from "./types.js";
+export declare function runMemoryExplain(input: {
+    root: string;
+    relPath: string;
+    budget: number;
+    agent?: string;
+    spawnFn?: SpawnFn;
+}): Promise<ExplainResult>;

package/packages/memory/dist/explain.cli.js

@@ -0,0 +1,9 @@
+import { explainPage } from "./explain.js";
+export async function runMemoryExplain(input) {
+    return explainPage(input.root, {
+        relPath: input.relPath,
+        budget: input.budget,
+        agent: input.agent,
+        spawnFn: input.spawnFn
+    });
+}

package/packages/memory/dist/explain.d.ts

@@ -0,0 +1,8 @@
+import type { ExplainResult, MemoryRoot, SpawnFn } from "./types.js";
+export type ExplainOptions = {
+    relPath: string;
+    budget: number;
+    agent?: string;
+    spawnFn?: SpawnFn;
+};
+export declare function explainPage(root: MemoryRoot, options: ExplainOptions): Promise<ExplainResult>;

package/packages/memory/dist/explain.js

@@ -0,0 +1,77 @@
+import { countTokens } from "tokenfill";
+import { readPage } from "./pages.js";
+import { queryMemory, selectQueryContext } from "./query.js";
+export async function explainPage(root, options) {
+    const targetPage = await readPageIfPresent(root, options.relPath);
+    if (targetPage === undefined) {
+        return {
+            answer: "",
+            citations: [],
+            tokensUsed: 0,
+            budget: options.budget,
+            exitCode: 0,
+            inboundPages: [],
+            outboundSources: []
+        };
+    }
+    const allContext = await selectQueryContext(root, options.relPath, Number.MAX_SAFE_INTEGER);
+    const relatedPages = collectRelatedPages(allContext.selectedPages, targetPage.relPath, targetPage.frontmatter.sources ?? []);
+    const prompt = buildExplainPrompt(targetPage.relPath, relatedPages);
+    const tokensUsed = countTokens(prompt);
+    if (tokensUsed > options.budget) {
+        throw new Error(`budget too small; needs at least ${tokensUsed} tokens`);
+    }
+    const spawnFn = options.spawnFn;
+    const response = await queryMemory(root, {
+        question: `explain ${options.relPath}`,
+        budget: options.budget,
+        agent: options.agent,
+        spawnFn: spawnFn === undefined ? undefined : async (...args) => {
+            const [agent] = args;
+            return spawnFn(agent, prompt);
+        }
+    });
+    return {
+        ...response,
+        inboundPages: relatedPages
+            .filter((page) => page.relPath !== targetPage.relPath)
+            .filter((page) => (page.frontmatter.sources ?? []).some((source) => source.path === targetPage.relPath))
+            .map((page) => page.relPath),
+        outboundSources: targetPage.frontmatter.sources ?? []
+    };
+}
+function collectRelatedPages(pages, targetRelPath, outboundSources) {
+    const memorySourcePaths = new Set(outboundSources.map((source) => source.path));
+    return pages.filter((page) => {
+        if (page.relPath === targetRelPath) {
+            return true;
+        }
+        if (memorySourcePaths.has(page.relPath)) {
+            return true;
+        }
+        return (page.frontmatter.sources ?? []).some((source) => source.path === targetRelPath);
+    });
+}
+function buildExplainPrompt(targetRelPath, pages) {
+    return [
+        "Summarize the target page using only the provided memory pages.",
+        "Return a 1-2 paragraph explanation plus the important inbound/outbound links.",
+        "Cite pages and sections with [rel_path §section]. If memory is insufficient, say so.",
+        "No tools are available.",
+        "",
+        `Target page: ${targetRelPath}`,
+        "",
+        ...pages.map((page) => [`FILE: ${page.relPath}`, page.body].join("\n"))
+    ].join("\n\n");
+}
+async function readPageIfPresent(root, relPath) {
+    try {
+        return await readPage(root, relPath);
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/packages/memory/dist/frontmatter.d.ts

@@ -0,0 +1,9 @@
+import type { PageFrontmatter, SourceRef } from "./types.js";
+export interface ParsedFrontmatter {
+    frontmatter: PageFrontmatter;
+    body: string;
+}
+export declare function parseFrontmatter(markdown: string): ParsedFrontmatter;
+export declare function serializeFrontmatter(frontmatter: PageFrontmatter, body: string): string;
+export declare function parseSourceRef(serialized: string): SourceRef;
+export declare function serializeSourceRef(source: SourceRef): string;

package/packages/memory/dist/frontmatter.js

@@ -0,0 +1,217 @@
+import { parse, stringify } from "yaml";
+export function parseFrontmatter(markdown) {
+    const content = markdown.startsWith("\uFEFF") ? markdown.slice(1) : markdown;
+    const openingLineBreak = readOpeningLineBreak(content);
+    if (openingLineBreak === undefined) {
+        return {
+            frontmatter: {},
+            body: markdown
+        };
+    }
+    const frontmatterStart = 3 + openingLineBreak.length;
+    const closingFenceIndex = findClosingFence(content, frontmatterStart);
+    const yamlBlock = content.slice(frontmatterStart, closingFenceIndex);
+    const bodyStart = closingFenceIndex + 4;
+    return {
+        frontmatter: parsePageFrontmatter(parseYamlFrontmatter(yamlBlock)),
+        body: readBody(content, bodyStart)
+    };
+}
+export function serializeFrontmatter(frontmatter, body) {
+    const serialized = {
+        ...(frontmatter.name === undefined ? {} : { name: frontmatter.name }),
+        ...(frontmatter.description === undefined ? {} : { description: frontmatter.description }),
+        ...(frontmatter.lastTouchedAt === undefined
+            ? {}
+            : { last_touched_at: frontmatter.lastTouchedAt }),
+        ...(frontmatter.sources === undefined || frontmatter.sources.length === 0
+            ? {}
+            : { sources: frontmatter.sources.map((source) => serializeSourceRef(source)) })
+    };
+    if (Object.keys(serialized).length === 0) {
+        return body;
+    }
+    return `---\n${stringify(serialized).trimEnd()}\n---\n${body}`;
+}
+export function parseSourceRef(serialized) {
+    const [rawPath, rawAnchor] = serialized.split("#", 2);
+    const normalizedPath = rawPath?.trim();
+    if (normalizedPath === undefined || normalizedPath.length === 0) {
+        throw new Error(`Invalid source ref "${serialized}".`);
+    }
+    if (rawAnchor === undefined) {
+        return { path: normalizedPath };
+    }
+    const singleLineMatch = /^L(\d+)$/.exec(rawAnchor);
+    if (singleLineMatch !== null) {
+        const startLine = Number.parseInt(singleLineMatch[1], 10);
+        assertValidLineNumber(startLine, serialized);
+        return {
+            path: normalizedPath,
+            startLine
+        };
+    }
+    const rangeMatch = /^L(\d+)-L?(\d+)$/.exec(rawAnchor);
+    if (rangeMatch !== null) {
+        const startLine = Number.parseInt(rangeMatch[1], 10);
+        const endLine = Number.parseInt(rangeMatch[2], 10);
+        assertValidLineNumber(startLine, serialized);
+        assertValidLineNumber(endLine, serialized);
+        if (endLine < startLine) {
+            throw new Error(`Invalid source ref "${serialized}": line range is reversed.`);
+        }
+        return {
+            path: normalizedPath,
+            startLine,
+            endLine
+        };
+    }
+    throw new Error(`Invalid source ref "${serialized}".`);
+}
+export function serializeSourceRef(source) {
+    if (source.path.trim().length === 0) {
+        throw new Error("Source path cannot be empty.");
+    }
+    if (source.startLine === undefined) {
+        if (source.endLine !== undefined) {
+            throw new Error("Source endLine requires startLine.");
+        }
+        return source.path;
+    }
+    assertValidLineNumber(source.startLine, source.path);
+    if (source.endLine === undefined) {
+        return `${source.path}#L${source.startLine}`;
+    }
+    assertValidLineNumber(source.endLine, source.path);
+    if (source.endLine < source.startLine) {
+        throw new Error(`Invalid source ref "${source.path}": line range is reversed.`);
+    }
+    return `${source.path}#L${source.startLine}-L${source.endLine}`;
+}
+function readOpeningLineBreak(markdown) {
+    if (!markdown.startsWith("---")) {
+        return undefined;
+    }
+    const nextCharacter = markdown[3];
+    if (nextCharacter === "\n") {
+        return "\n";
+    }
+    if (nextCharacter === "\r" && markdown[4] === "\n") {
+        return "\r\n";
+    }
+    return nextCharacter === undefined ? "\n" : undefined;
+}
+function findClosingFence(markdown, searchFrom) {
+    let currentIndex = searchFrom - 1;
+    while (currentIndex < markdown.length) {
+        const candidateIndex = markdown.indexOf("\n---", currentIndex);
+        if (candidateIndex === -1) {
+            throw new Error("Missing YAML frontmatter end delimiter (---).");
+        }
+        const fenceEnd = candidateIndex + 4;
+        const nextCharacter = markdown[fenceEnd];
+        if (nextCharacter === "\n" || nextCharacter === undefined) {
+            return candidateIndex;
+        }
+        if (nextCharacter === "\r" && markdown[fenceEnd + 1] === "\n") {
+            return candidateIndex;
+        }
+        currentIndex = fenceEnd;
+    }
+    throw new Error("Missing YAML frontmatter end delimiter (---).");
+}
+function readBody(markdown, bodyStart) {
+    const nextCharacter = markdown[bodyStart];
+    if (nextCharacter === "\n") {
+        return markdown.slice(bodyStart + 1);
+    }
+    if (nextCharacter === "\r" && markdown[bodyStart + 1] === "\n") {
+        return markdown.slice(bodyStart + 2);
+    }
+    return markdown.slice(bodyStart);
+}
+function parseYamlFrontmatter(yamlBlock) {
+    const normalizedYamlBlock = yamlBlock.includes("\r")
+        ? yamlBlock.replaceAll("\r\n", "\n").replaceAll("\r", "")
+        : yamlBlock;
+    let parsed;
+    try {
+        parsed = parse(normalizedYamlBlock);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown YAML parse error";
+        throw new Error(`Invalid YAML frontmatter: ${message}`);
+    }
+    if (parsed === null) {
+        return {};
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("YAML frontmatter must parse to an object.");
+    }
+    return parsed;
+}
+function parsePageFrontmatter(value) {
+    const name = readOptionalString(value.name, "name");
+    const description = readOptionalString(value.description, "description");
+    const lastTouchedAt = readOptionalString(value.last_touched_at ?? value.lastTouchedAt, "last_touched_at");
+    const sources = parseSources(value.sources);
+    return {
+        ...(name === undefined ? {} : { name }),
+        ...(description === undefined ? {} : { description }),
+        ...(lastTouchedAt === undefined ? {} : { lastTouchedAt }),
+        ...(sources === undefined ? {} : { sources })
+    };
+}
+function parseSources(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error('Invalid "sources" frontmatter. Expected an array.');
+    }
+    return value.map((item) => {
+        if (typeof item === "string") {
+            return parseSourceRef(item);
+        }
+        if (!isRecord(item)) {
+            throw new Error('Invalid "sources" frontmatter. Expected each source to be a string or object.');
+        }
+        const path = readRequiredString(item.path, "sources[].path");
+        const startLine = readOptionalPositiveInteger(item.startLine, "sources[].startLine");
+        const endLine = readOptionalPositiveInteger(item.endLine, "sources[].endLine");
+        return parseSourceRef(serializeSourceRef({ path, ...(startLine === undefined ? {} : { startLine }), ...(endLine === undefined ? {} : { endLine }) }));
+    });
+}
+function readOptionalString(value, field) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`Invalid "${field}" frontmatter. Expected a string.`);
+    }
+    return value;
+}
+function readRequiredString(value, field) {
+    const parsed = readOptionalString(value, field);
+    if (parsed === undefined) {
+        throw new Error(`Invalid "${field}" frontmatter. Expected a string.`);
+    }
+    return parsed;
+}
+function readOptionalPositiveInteger(value, field) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`Invalid "${field}" frontmatter. Expected a positive integer.`);
+    }
+    return value;
+}
+function assertValidLineNumber(line, value) {
+    if (!Number.isInteger(line) || line <= 0) {
+        throw new Error(`Invalid source ref "${value}": line numbers must be positive integers.`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/memory/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type { ConfidenceTag, ConfidenceVerb, ExplainResult, IndexEntry, IngestCacheEntry, IngestCacheKey, IngestOptions, IngestResult, IngestSource, LintOptions, LintResult, LogEntry, LogVerb, McpServerOptions, MemoryDiff, MemoryInstallResult, MemoryPage, MemoryRoot, MemorySnapshot, PageFrontmatter, PageWithClaims, QueryCitation, QueryOptions, QueryResult, SearchHit, SourceRef, SpawnFn, TaggedClaim, TokenStats } from "./types.js";
+export { resolveMemoryRoot } from "./paths.js";
+export { MEMORY_ROOT_ENV_VAR, resolveConfiguredMemoryRoot, type ResolveConfiguredMemoryRootOptions } from "./resolve-root.js";
+export { initMemory } from "./init.js";
+export { listPages, readPage } from "./pages.js";
+export { searchMemory } from "./search.js";
+export { statusOf } from "./status.js";
+export { editPage } from "./edit.js";
+export { appendToPage, clearMemory, writePage } from "./write.js";
+export { reconcile, snapshot } from "./reconcile.js";
+export { parseClaims, serializeTag } from "./confidence.js";
+export { auditClaims } from "./audit.js";
+export { clearCache, computeIngestKey, readCacheEntry, writeCacheEntry } from "./cache.js";
+export { runMemoryCacheClear, runMemoryCacheStatus } from "./cache.cli.js";
+export { ingest, INGEST_PROMPT_VERSION } from "./ingest.js";
+export { computeTokenStats } from "./tokens.js";
+export { startMemoryMcpServer, printMcpConfig } from "./mcp.js";
+export { installMemory } from "./install.js";
+export { queryMemory, rankPagesForQuery, selectQueryContext } from "./query.js";
+export { explainPage } from "./explain.js";
+export { runMemoryExplain } from "./explain.cli.js";