poe-code 3.0.311 → 3.0.313

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poe-code",
-  "version": "3.0.311",
+  "version": "3.0.313",
   "description": "CLI tool to configure Poe API for developer workflows.",
   "type": "module",
   "main": "./dist/index.js",

package/packages/markdown-reader/dist/core/document.js

@@ -20,6 +20,9 @@ export async function loadMarkdownDocument(file, dependencies = {}) {
     };
 }
 export function resolveMarkdownPath(file, cwd = process.cwd()) {
+    if (file.trim().length === 0) {
+        throw new UserError("invalid file: expected a non-empty path");
+    }
     return path.isAbsolute(file) ? file : path.resolve(cwd, file);
 }
 export function sliceMarkdownBytes(source, start, end) {
@@ -58,6 +61,9 @@ function hasYamlLikeLeadingFrontmatter(source) {
     if (lines[0] !== "---") {
         return false;
     }
+    if (lines[1]?.trim().length === 0) {
+        return false;
+    }
     for (const line of lines.slice(1)) {
         const trimmed = line.trim();
         if (trimmed.length === 0) {

package/packages/markdown-reader/dist/core/read-section.js

@@ -1,7 +1,11 @@
 import { loadMarkdownDocument, sliceMarkdownBytes } from "./document.js";
 import { resolveSection } from "./resolve.js";
+import { UserError } from "toolcraft";
 export function createReadSection(dependencies = {}) {
     return async function readSection(params) {
+        if (params.section.trim().length === 0) {
+            throw new UserError("invalid section: expected a non-empty section id");
+        }
         const { source, sections } = await loadMarkdownDocument(params.file, dependencies);
         const section = resolveSection(sections, params.section);
         const end = params.includeChildren === false ? section.bodyEndNoChildren : section.bodyEnd;

package/packages/markdown-reader/dist/core/resolve.js

@@ -1,14 +1,17 @@
 import { UserError } from "toolcraft";
 export function resolveSection(sections, id) {
     const trimmedId = id.trim();
-    const unnumberedTitleMatch = sections.find((section) => section.number === null && section.title === trimmedId);
-    if (unnumberedTitleMatch !== undefined) {
-        return unnumberedTitleMatch;
+    if (trimmedId.length === 0) {
+        throw new UserError("invalid section: expected a non-empty section id");
     }
     const sectionByNumber = sections.find((section) => section.number === trimmedId);
     if (sectionByNumber !== undefined) {
         return sectionByNumber;
     }
+    const unnumberedTitleMatch = sections.find((section) => section.number === null && section.title === trimmedId);
+    if (unnumberedTitleMatch !== undefined) {
+        return unnumberedTitleMatch;
+    }
     const titleMatches = sections.filter((section) => section.title === trimmedId);
     if (titleMatches.length === 1) {
         return titleMatches[0];

package/packages/markdown-reader/dist/core/scan.js

@@ -4,7 +4,10 @@ export function scanMarkdown(source) {
     if (ast.type !== "root") {
         return [];
     }
-    const headings = ast.children.filter(isHeadingNode);
+    const htmlCommentRanges = collectHtmlCommentRanges(source);
+    const headings = ast.children
+        .filter(isHeadingNode)
+        .filter((heading) => !isInsideHtmlComment(getRequiredRange(heading).start, htmlCommentRanges));
     if (headings.length === 0) {
         return [];
     }
@@ -25,6 +28,30 @@ export function scanMarkdown(source) {
     applyNumbers(sections, baselineDepth);
     return sections;
 }
+function collectHtmlCommentRanges(source) {
+    const ranges = [];
+    let searchStart = 0;
+    while (searchStart < source.length) {
+        const commentStart = source.indexOf("<!--", searchStart);
+        if (commentStart === -1) {
+            return ranges;
+        }
+        const commentEndMarker = source.indexOf("-->", commentStart + "<!--".length);
+        const commentEnd = commentEndMarker === -1 ? source.length : commentEndMarker + "-->".length;
+        ranges.push({
+            start: byteOffset(source, commentStart),
+            end: byteOffset(source, commentEnd)
+        });
+        searchStart = commentEnd;
+    }
+    return ranges;
+}
+function isInsideHtmlComment(offset, ranges) {
+    return ranges.some((range) => offset >= range.start && offset < range.end);
+}
+function byteOffset(source, index) {
+    return Buffer.byteLength(source.slice(0, index), "utf8");
+}
 function isHeadingNode(node) {
     return node.type === "heading";
 }

package/packages/markdown-reader/dist/mcp/tools.js

@@ -3,8 +3,12 @@ import { S } from "toolcraft-schema";
 import { readMarkdown } from "../core/read-markdown.js";
 import { readSection } from "../core/read-section.js";
 const readParams = S.Object({
-    file: S.String({ description: "Path to the markdown file" }),
-    depth: S.Optional(S.Number({ description: "Limit TOC to headings at depth <= n" }))
+    file: S.String({ description: "Path to the markdown file", minLength: 1 }),
+    depth: S.Optional(S.Number({
+        description: "Limit TOC to headings at depth <= n",
+        jsonType: "integer",
+        minimum: 0
+    }))
 });
 const tocEntryResult = S.Object({
     depth: S.Number(),
@@ -24,8 +28,11 @@ export const readTool = defineCommand({
     handler: async ({ params }) => readMarkdown(params)
 });
 const readSectionParams = S.Object({
-    file: S.String({ description: "Path to the markdown file" }),
-    section: S.String({ description: "Numeric path or exact heading text to read" }),
+    file: S.String({ description: "Path to the markdown file", minLength: 1 }),
+    section: S.String({
+        description: "Numeric path or exact heading text to read",
+        minLength: 1
+    }),
     includeChildren: S.Optional(S.Boolean({ description: "Include nested child sections" }))
 });
 export const readSectionTool = defineCommand({

package/packages/memory/dist/agent-response.d.ts

@@ -0,0 +1,2 @@
+import type { QueryResult } from "./types.js";
+export declare function parseMemoryAgentResponse(stdout: string): Pick<QueryResult, "answer" | "citations" | "tokensUsed">;

package/packages/memory/dist/agent-response.js

@@ -0,0 +1,38 @@
+const validCitationConfidences = new Set(["extracted", "inferred", "ambiguous"]);
+export function parseMemoryAgentResponse(stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error("Memory agent returned invalid JSON output.");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Memory agent returned an invalid result payload.");
+    }
+    const result = value;
+    if (typeof result.answer !== "string" ||
+        !Array.isArray(result.citations) ||
+        !isNonNegativeInteger(result.tokensUsed) ||
+        !result.citations.every(isQueryCitation)) {
+        throw new Error("Memory agent returned an invalid result payload.");
+    }
+    return {
+        answer: result.answer,
+        citations: result.citations,
+        tokensUsed: result.tokensUsed
+    };
+}
+function isQueryCitation(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const citation = value;
+    return (typeof citation.relPath === "string" &&
+        (citation.section === undefined || typeof citation.section === "string") &&
+        typeof citation.confidence === "string" &&
+        validCitationConfidences.has(citation.confidence));
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}

package/packages/memory/dist/cache.js

@@ -97,17 +97,21 @@ export async function clearCache(root, opts = {}) {
 async function assertIngestCachePathIsNotSymlink(root) {
     await assertNoSymlinkSegments(root, MEMORY_INGEST_CACHE_DIR_RELPATH);
 }
-function parseCacheEntry(value, _key) {
+function parseCacheEntry(value, requestedKey) {
     const object = expectRecord(value);
+    const key = expectString(getOwnEntry(object, "key"), "key");
+    if (key !== requestedKey) {
+        throw new Error(`Cache entry key "${key}" does not match requested key "${requestedKey}".`);
+    }
     return {
-        key: expectString(getOwnEntry(object, "key"), "key"),
+        key,
         ingestedAt: expectString(getOwnEntry(object, "ingestedAt"), "ingestedAt"),
         sourceLabel: expectString(getOwnEntry(object, "sourceLabel"), "sourceLabel"),
         diff: parseMemoryDiff(getOwnEntry(object, "diff")),
-        exitCode: expectNumber(getOwnEntry(object, "exitCode"), "exitCode"),
-        durationMs: expectNumber(getOwnEntry(object, "durationMs"), "durationMs"),
-        memoryTokens: expectNumber(getOwnEntry(object, "memoryTokens"), "memoryTokens"),
-        sourceTokens: expectNumber(getOwnEntry(object, "sourceTokens"), "sourceTokens"),
+        exitCode: expectNonNegativeInteger(getOwnEntry(object, "exitCode"), "exitCode"),
+        durationMs: expectNonNegativeInteger(getOwnEntry(object, "durationMs"), "durationMs"),
+        memoryTokens: expectNonNegativeInteger(getOwnEntry(object, "memoryTokens"), "memoryTokens"),
+        sourceTokens: expectNonNegativeInteger(getOwnEntry(object, "sourceTokens"), "sourceTokens"),
         promptTemplateVersion: expectString(getOwnEntry(object, "promptTemplateVersion"), "promptTemplateVersion"),
         agentId: expectString(getOwnEntry(object, "agentId"), "agentId")
     };
@@ -132,9 +136,9 @@ function expectString(value, field) {
     }
     return value;
 }
-function expectNumber(value, field) {
-    if (typeof value !== "number" || Number.isNaN(value)) {
-        throw new Error(`Expected number at "${field}".`);
+function expectNonNegativeInteger(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`Expected non-negative integer at "${field}".`);
     }
     return value;
 }

package/packages/memory/dist/explain.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { countTokens } from "tokenfill";
 import { spawn } from "@poe-code/agent-spawn";
 import { resolveAgent } from "@poe-code/poe-code-config";
+import { parseMemoryAgentResponse } from "./agent-response.js";
 import { hasOwnErrorCode } from "./errors.js";
 import { readPage } from "./pages.js";
 import { selectQueryContext } from "./query.js";
@@ -33,7 +34,7 @@ export async function explainPage(root, options) {
     };
     const agentId = (await resolveAgent(configOptions, options.agent ?? null)) ?? options.agent ?? "claude-code";
     const spawned = await spawn(agentId, { prompt });
-    const response = parseExplainResponse(spawned.stdout);
+    const response = parseMemoryAgentResponse(spawned.stdout);
     return {
         answer: response.answer,
         citations: response.citations,
@@ -47,30 +48,6 @@ export async function explainPage(root, options) {
         outboundSources: targetPage.frontmatter.sources ?? []
     };
 }
-function parseExplainResponse(stdout) {
-    let value;
-    try {
-        value = JSON.parse(stdout);
-    }
-    catch {
-        throw new Error("Memory agent returned invalid JSON output.");
-    }
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new Error("Memory agent returned an invalid result payload.");
-    }
-    const response = value;
-    if (typeof response.answer !== "string" ||
-        !Array.isArray(response.citations) ||
-        typeof response.tokensUsed !== "number" ||
-        !Number.isFinite(response.tokensUsed)) {
-        throw new Error("Memory agent returned an invalid result payload.");
-    }
-    return {
-        answer: response.answer,
-        citations: response.citations,
-        tokensUsed: response.tokensUsed
-    };
-}
 function collectRelatedPages(pages, targetRelPath, outboundSources) {
     const memorySourcePaths = new Set(outboundSources.map((source) => source.path));
     return pages.filter((page) => {

package/packages/memory/dist/frontmatter.js

@@ -23,7 +23,11 @@ export function serializeFrontmatter(frontmatter, body) {
     return stringifyFrontmatter(serialized, body);
 }
 export function parseSourceRef(serialized) {
-    const [rawPath, rawAnchor] = serialized.split("#", 2);
+    const parts = serialized.split("#");
+    if (parts.length > 2) {
+        throw new Error(`Invalid source ref "${serialized}".`);
+    }
+    const [rawPath, rawAnchor] = parts;
     const normalizedPath = rawPath?.trim();
     if (normalizedPath === undefined || normalizedPath.length === 0) {
         throw new Error(`Invalid source ref "${serialized}".`);

package/packages/memory/dist/index.js

@@ -68,6 +68,9 @@ async function assertMemoryRootIsNotSymlink(root) {
     try {
       const stat7 = await fs.lstat(currentPath);
       if (stat7.isSymbolicLink()) {
+        if (await isAllowedMacSystemAlias(currentPath)) {
+          continue;
+        }
         throw new MemoryPathError(`Memory root "${root}" cannot be a symbolic link.`);
       }
     } catch (error2) {
@@ -78,6 +81,17 @@ async function assertMemoryRootIsNotSymlink(root) {
     }
   }
 }
+async function isAllowedMacSystemAlias(currentPath) {
+  if (currentPath !== "/var") {
+    return false;
+  }
+  try {
+    const target = await fs.readlink(currentPath);
+    return target === "/private/var" || target === "private/var";
+  } catch {
+    return false;
+  }
+}
 function isMissing(error2) {
   return hasOwnErrorCode(error2, "ENOENT");
 }
@@ -5388,7 +5402,11 @@ function serializeFrontmatter(frontmatter, body) {
   return stringifyFrontmatter(serialized, body);
 }
 function parseSourceRef(serialized) {
-  const [rawPath, rawAnchor] = serialized.split("#", 2);
+  const parts = serialized.split("#");
+  if (parts.length > 2) {
+    throw new Error(`Invalid source ref "${serialized}".`);
+  }
+  const [rawPath, rawAnchor] = parts;
   const normalizedPath = rawPath?.trim();
   if (normalizedPath === void 0 || normalizedPath.length === 0) {
     throw new Error(`Invalid source ref "${serialized}".`);
@@ -5626,7 +5644,7 @@ async function searchMemory(root, query) {
   if (normalizedQuery.length === 0) {
     throw new Error("Search query cannot be empty.");
   }
-  const relPaths = await collectMarkdownRelPaths(root);
+  const relPaths = await collectMarkdownRelPaths(root, MEMORY_PAGES_DIR_RELPATH);
   const hits = [];
   for (const relPath of relPaths) {
     await assertNoSymlinkSegments(root, relPath);
@@ -6149,7 +6167,7 @@ async function appendToPage(root, relPath, content, opts) {
   const before = await snapshot(root);
   await fs8.mkdir(path22.dirname(pagePath), { recursive: true });
   await assertNoSymlinkSegments(root, pageRelPath);
-  const parsed = originalPage === void 0 ? { frontmatter: {}, body: "" } : parseFrontmatter2(originalPage);
+  const parsed = parseAppendTarget(originalPage, pageRelPath);
   try {
     await writeFileAtomically2(
       pagePath,
@@ -6161,6 +6179,18 @@ async function appendToPage(root, relPath, content, opts) {
     throw error2;
   }
 }
+function parseAppendTarget(originalPage, relPath) {
+  if (originalPage === void 0) {
+    return { frontmatter: {}, body: "" };
+  }
+  try {
+    return parseFrontmatter2(originalPage);
+  } catch (error2) {
+    const message2 = error2 instanceof Error ? error2.message : String(error2);
+    console.warn(`Failed to parse frontmatter for "${relPath}": ${message2}`);
+    return { frontmatter: {}, body: originalPage };
+  }
+}
 async function clearMemory(root) {
   await assertMemoryRootIsNotSymlink(root);
   const stagedRoot = `${root}.clear-${randomUUID7()}`;
@@ -6494,17 +6524,21 @@ async function clearCache(root, opts = {}) {
 async function assertIngestCachePathIsNotSymlink(root) {
   await assertNoSymlinkSegments(root, MEMORY_INGEST_CACHE_DIR_RELPATH);
 }
-function parseCacheEntry(value, _key) {
+function parseCacheEntry(value, requestedKey) {
   const object = expectRecord(value);
+  const key = expectString(getOwnEntry8(object, "key"), "key");
+  if (key !== requestedKey) {
+    throw new Error(`Cache entry key "${key}" does not match requested key "${requestedKey}".`);
+  }
   return {
-    key: expectString(getOwnEntry8(object, "key"), "key"),
+    key,
     ingestedAt: expectString(getOwnEntry8(object, "ingestedAt"), "ingestedAt"),
     sourceLabel: expectString(getOwnEntry8(object, "sourceLabel"), "sourceLabel"),
     diff: parseMemoryDiff(getOwnEntry8(object, "diff")),
-    exitCode: expectNumber(getOwnEntry8(object, "exitCode"), "exitCode"),
-    durationMs: expectNumber(getOwnEntry8(object, "durationMs"), "durationMs"),
-    memoryTokens: expectNumber(getOwnEntry8(object, "memoryTokens"), "memoryTokens"),
-    sourceTokens: expectNumber(getOwnEntry8(object, "sourceTokens"), "sourceTokens"),
+    exitCode: expectNonNegativeInteger(getOwnEntry8(object, "exitCode"), "exitCode"),
+    durationMs: expectNonNegativeInteger(getOwnEntry8(object, "durationMs"), "durationMs"),
+    memoryTokens: expectNonNegativeInteger(getOwnEntry8(object, "memoryTokens"), "memoryTokens"),
+    sourceTokens: expectNonNegativeInteger(getOwnEntry8(object, "sourceTokens"), "sourceTokens"),
     promptTemplateVersion: expectString(
       getOwnEntry8(object, "promptTemplateVersion"),
       "promptTemplateVersion"
@@ -6532,9 +6566,9 @@ function expectString(value, field) {
   }
   return value;
 }
-function expectNumber(value, field) {
-  if (typeof value !== "number" || Number.isNaN(value)) {
-    throw new Error(`Expected number at "${field}".`);
+function expectNonNegativeInteger(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`Expected non-negative integer at "${field}".`);
   }
   return value;
 }
@@ -16586,7 +16620,7 @@ async function installMemory(options) {
       }
       throw error2;
     }
-    mcpConfigPath = options.agent === "codex" ? `${options.homeDir}/.config/codex/mcp-config.json` : `${options.homeDir}/.mcp.json`;
+    mcpConfigPath = resolveMcpConfigPath(options.agent, options.homeDir, options.platform);
   }
   return {
     skillInstalled: !options.mcpOnly,
@@ -16595,6 +16629,14 @@ async function installMemory(options) {
     mcpConfigPath
   };
 }
+function resolveMcpConfigPath(agent, homeDir, platform) {
+  const support = resolveAgentSupport3(agent);
+  if (support.status !== "supported" || support.config === void 0) {
+    throw new Error(`Unsupported agent: ${agent}`);
+  }
+  const configFile = typeof support.config.configFile === "function" ? support.config.configFile(platform) : support.config.configFile;
+  return configFile.startsWith("~/") ? path61.join(homeDir, configFile.slice(2)) : configFile;
+}
 async function removeInstalledSkill(options, skillPath) {
   const baseDir = options.scope === "global" ? options.homeDir : options.cwd;
   const displayPath = skillPath.startsWith("~/") ? skillPath.slice(2) : skillPath;
@@ -16609,6 +16651,41 @@ async function removeInstalledSkill(options, skillPath) {
 // packages/memory/src/query.ts
 import * as fs18 from "node:fs/promises";
 import path62 from "node:path";
+
+// packages/memory/src/agent-response.ts
+var validCitationConfidences = /* @__PURE__ */ new Set(["extracted", "inferred", "ambiguous"]);
+function parseMemoryAgentResponse(stdout) {
+  let value;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    throw new Error("Memory agent returned invalid JSON output.");
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Memory agent returned an invalid result payload.");
+  }
+  const result = value;
+  if (typeof result.answer !== "string" || !Array.isArray(result.citations) || !isNonNegativeInteger(result.tokensUsed) || !result.citations.every(isQueryCitation)) {
+    throw new Error("Memory agent returned an invalid result payload.");
+  }
+  return {
+    answer: result.answer,
+    citations: result.citations,
+    tokensUsed: result.tokensUsed
+  };
+}
+function isQueryCitation(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const citation = value;
+  return typeof citation.relPath === "string" && (citation.section === void 0 || typeof citation.section === "string") && typeof citation.confidence === "string" && validCitationConfidences.has(citation.confidence);
+}
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+// packages/memory/src/query.ts
 async function queryMemory(root, options) {
   const pages = await listPages(root);
   if (pages.length === 0) {
@@ -16628,7 +16705,7 @@ async function queryMemory(root, options) {
   const agentId = await resolveAgent(configOptions, options.agent ?? null) ?? options.agent ?? "claude-code";
   const context = await selectQueryContext(root, options.question, options.budget);
   const spawned = await spawn4(agentId, { prompt: context.prompt });
-  const result = parseQueryResponse(spawned.stdout);
+  const result = parseMemoryAgentResponse(spawned.stdout);
   return {
     answer: result.answer,
     citations: result.citations,
@@ -16637,26 +16714,6 @@ async function queryMemory(root, options) {
     exitCode: spawned.exitCode
   };
 }
-function parseQueryResponse(stdout) {
-  let value;
-  try {
-    value = JSON.parse(stdout);
-  } catch {
-    throw new Error("Memory agent returned invalid JSON output.");
-  }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  const result = value;
-  if (typeof result.answer !== "string" || !Array.isArray(result.citations) || typeof result.tokensUsed !== "number" || !Number.isFinite(result.tokensUsed)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  return {
-    answer: result.answer,
-    citations: result.citations,
-    tokensUsed: result.tokensUsed
-  };
-}
 async function selectQueryContext(root, question, budget) {
   if (!Number.isFinite(budget) || budget < 0) {
     throw new Error("budget must be a finite non-negative number");
@@ -16774,7 +16831,7 @@ async function explainPage(root, options) {
   };
   const agentId = await resolveAgent(configOptions, options.agent ?? null) ?? options.agent ?? "claude-code";
   const spawned = await spawn4(agentId, { prompt });
-  const response = parseExplainResponse(spawned.stdout);
+  const response = parseMemoryAgentResponse(spawned.stdout);
   return {
     answer: response.answer,
     citations: response.citations,
@@ -16785,26 +16842,6 @@ async function explainPage(root, options) {
     outboundSources: targetPage.frontmatter.sources ?? []
   };
 }
-function parseExplainResponse(stdout) {
-  let value;
-  try {
-    value = JSON.parse(stdout);
-  } catch {
-    throw new Error("Memory agent returned invalid JSON output.");
-  }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  const response = value;
-  if (typeof response.answer !== "string" || !Array.isArray(response.citations) || typeof response.tokensUsed !== "number" || !Number.isFinite(response.tokensUsed)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  return {
-    answer: response.answer,
-    citations: response.citations,
-    tokensUsed: response.tokensUsed
-  };
-}
 function collectRelatedPages(pages, targetRelPath, outboundSources) {
   const memorySourcePaths = new Set(outboundSources.map((source) => source.path));
   return pages.filter((page) => {