@phuetz/code-buddy 0.4.0 → 1.0.0

package/dist/tools/document-tool.js

@@ -75,6 +75,121 @@ export class DocumentTool {
             };
         }
     }
+    /**
+     * Extract embedded DOCX images to a directory so downstream OCR or deliverable
+     * generation can inspect screenshots instead of only seeing text markers.
+     */
+    async extractEmbeddedImages(filePath, outputDir) {
+        try {
+            const resolvedPath = path.resolve(process.cwd(), filePath);
+            if (!await this.vfs.exists(resolvedPath)) {
+                return {
+                    success: false,
+                    error: `Document not found: ${filePath}`
+                };
+            }
+            const ext = path.extname(resolvedPath).toLowerCase();
+            if (ext !== '.docx') {
+                return {
+                    success: false,
+                    error: 'Embedded image extraction currently supports DOCX files only'
+                };
+            }
+            const stats = await this.vfs.stat(resolvedPath);
+            const fileSizeMB = stats.size / (1024 * 1024);
+            if (fileSizeMB > this.maxFileSizeMB) {
+                return {
+                    success: false,
+                    error: `File too large: ${fileSizeMB.toFixed(2)}MB. Max: ${this.maxFileSizeMB}MB`
+                };
+            }
+            const AdmZip = (await import('adm-zip')).default;
+            const buffer = await this.vfs.readFileBuffer(resolvedPath);
+            const zip = new AdmZip(buffer);
+            const selectedImages = this.selectDocxImagesForExtraction(zip);
+            const resolvedOutputDir = outputDir
+                ? path.resolve(process.cwd(), outputDir)
+                : path.join(path.dirname(resolvedPath), `${path.basename(resolvedPath, ext)}-images`);
+            if (selectedImages.length === 0) {
+                return {
+                    success: true,
+                    output: `No embedded images found in ${filePath}`,
+                    data: { images: [], outputDir: resolvedOutputDir }
+                };
+            }
+            await this.vfs.ensureDir(resolvedOutputDir);
+            const images = [];
+            for (const selected of selectedImages) {
+                const fileName = path.basename(selected.entry.entryName);
+                if (!fileName)
+                    continue;
+                const imageBuffer = selected.entry.getData();
+                const outputPath = path.join(resolvedOutputDir, fileName);
+                const markdownRef = `![Source screenshot - ${fileName}](${formatMarkdownPath(outputPath)})`;
+                await this.vfs.writeFileBuffer(outputPath, imageBuffer);
+                images.push({
+                    sourcePath: selected.entry.entryName,
+                    outputPath,
+                    markdownRef,
+                    size: imageBuffer.length
+                });
+            }
+            return {
+                success: true,
+                output: [
+                    `Extracted ${images.length} embedded image(s) to ${resolvedOutputDir}`,
+                    ...images.map(image => `- ${image.outputPath} (${image.size} bytes)`),
+                    ...(images.length > 0
+                        ? [
+                            'Markdown references for generate_document:',
+                            ...images.map(image => `- ${image.markdownRef}`)
+                        ]
+                        : [])
+                ].join('\n'),
+                data: { images, outputDir: resolvedOutputDir }
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to extract embedded images: ${getErrorMessage(error)}`
+            };
+        }
+    }
+    selectDocxImagesForExtraction(zip) {
+        const relationships = this.extractDocxImageRelationshipEntries(zip);
+        const byId = new Map(relationships.map(relationship => [relationship.id, relationship]));
+        const documentXml = safeReadZipText(zip, 'word/document.xml');
+        const orderedRelationshipIds = documentXml
+            ? this.extractDocxImageRelationshipIdsInDocumentOrder(documentXml)
+            : [];
+        const selectedRelationships = orderedRelationshipIds
+            .map(id => byId.get(id))
+            .filter((relationship) => Boolean(relationship));
+        const relationshipsToExtract = selectedRelationships.length > 0 ? selectedRelationships : relationships;
+        if (relationshipsToExtract.length > 0) {
+            const seen = new Set();
+            return relationshipsToExtract
+                .filter(relationship => {
+                if (seen.has(relationship.zipPath))
+                    return false;
+                seen.add(relationship.zipPath);
+                return true;
+            })
+                .map(relationship => {
+                const entry = zip.getEntry(relationship.zipPath);
+                return entry && !entry.isDirectory
+                    ? { relationshipId: relationship.id, entry }
+                    : null;
+            })
+                .filter((image) => Boolean(image));
+        }
+        // Backward-compatible fallback for minimal synthetic DOCX files or unusual
+        // packages that include media but omit document relationships.
+        return zip.getEntries()
+            .filter(entry => !entry.isDirectory && entry.entryName.startsWith('word/media/'))
+            .map(entry => ({ entry }));
+    }
     /**
      * Read DOCX file
      */
@@ -84,8 +199,12 @@ export class DocumentTool {
         const zip = new AdmZip(buffer);
         // Read document.xml
         const documentXml = zip.readAsText('word/document.xml');
-        // Extract text from XML
-        const text = this.extractTextFromXml(documentXml, 'w:t');
+        const relationships = this.extractDocxRelationships(zip);
+        // Extract text from XML while preserving paragraph, table, and image
+        // positions. Question documents depend on those breaks to keep
+        // analysis/context attached to the right question.
+        const extraction = this.extractDocxText(documentXml, relationships);
+        const { text } = extraction;
         // Try to read metadata from core.xml
         const metadata = this.extractDocxMetadata(zip);
         return {
@@ -93,7 +212,8 @@ export class DocumentTool {
             type: 'docx',
             metadata: {
                 ...metadata,
-                wordCount: text.split(/\s+/).filter(w => w.length > 0).length
+                wordCount: text.split(/\s+/).filter(w => w.length > 0).length,
+                embeddedImageCount: extraction.embeddedImageCount
             }
         };
     }
@@ -115,7 +235,7 @@ export class DocumentTool {
             .filter(entry => /^xl\/worksheets\/sheet\d+\.xml$/.test(entry.entryName))
             .map(entry => {
             const match = entry.entryName.match(/sheet(\d+)\.xml$/);
-            return { entryName: entry.entryName, index: match ? parseInt(match[1]) : 0 };
+            return { entryName: entry.entryName, index: match?.[1] ? parseInt(match[1]) : 0 };
         })
             .sort((a, b) => a.index - b.index);
         // Process sheets in batches to avoid blocking
@@ -198,7 +318,7 @@ export class DocumentTool {
         const sheetMatches = workbookXml.match(/<sheet[^>]+name="([^"]+)"[^>]*>/g) || [];
         for (const match of sheetMatches) {
             const nameMatch = match.match(/name="([^"]+)"/);
-            if (nameMatch) {
+            if (nameMatch?.[1] !== undefined) {
                 sheetNames.push(nameMatch[1]);
             }
         }
@@ -220,7 +340,7 @@ export class DocumentTool {
         const rowMatches = xml.match(/<row[^>]*>[\s\S]*?<\/row>/g) || [];
         for (const rowXml of rowMatches) {
             const rowNumMatch = rowXml.match(/r="(\d+)"/);
-            const rowNum = rowNumMatch ? parseInt(rowNumMatch[1]) - 1 : data.length;
+            const rowNum = rowNumMatch?.[1] !== undefined ? parseInt(rowNumMatch[1]) - 1 : data.length;
             // Ensure row exists
             while (data.length <= rowNum) {
                 data.push([]);
@@ -229,24 +349,28 @@ export class DocumentTool {
             const cellMatches = rowXml.match(/<c[^>]*>[\s\S]*?<\/c>/g) || [];
             for (const cellXml of cellMatches) {
                 const refMatch = cellXml.match(/r="([A-Z]+)(\d+)"/);
-                if (!refMatch)
+                const colStr = refMatch?.[1];
+                if (colStr === undefined)
                     continue;
-                const colStr = refMatch[1];
                 const colIndex = this.colStringToIndex(colStr);
                 maxCol = Math.max(maxCol, colIndex + 1);
                 // Ensure row has enough columns
-                while (data[rowNum].length <= colIndex) {
-                    data[rowNum].push('');
+                const row = data[rowNum];
+                if (row === undefined)
+                    continue;
+                while (row.length <= colIndex) {
+                    row.push('');
                 }
                 // Get cell value
                 const valueMatch = cellXml.match(/<v>([^<]*)<\/v>/);
-                let value = valueMatch ? valueMatch[1] : '';
+                let value = valueMatch?.[1] ?? '';
                 // Check if it's a shared string reference
                 const typeMatch = cellXml.match(/t="s"/);
-                if (typeMatch && sharedStrings[parseInt(value)]) {
-                    value = sharedStrings[parseInt(value)];
+                const sharedValue = sharedStrings[parseInt(value)];
+                if (typeMatch && sharedValue) {
+                    value = sharedValue;
                 }
-                data[rowNum][colIndex] = value;
+                row[colIndex] = value;
             }
         }
         return { data, maxCol };
@@ -389,16 +513,173 @@ export class DocumentTool {
      * Extract text from XML content
      */
     extractTextFromXml(xml, tagName) {
-        const regex = new RegExp(`<${tagName}[^>]*>([^<]*)</${tagName}>`, 'g');
-        const matches = xml.match(regex) || [];
+        return this.extractTextRunsFromXml(xml, tagName)
+            .map(text => text.trim())
+            .filter(Boolean)
+            .join(' ');
+    }
+    extractDocxText(documentXml, relationships = new Map()) {
+        const bodyMatch = documentXml.match(/<w:body\b[^>]*>([\s\S]*?)<\/w:body>/);
+        const sourceXml = bodyMatch?.[1] || documentXml;
+        const blocks = this.extractXmlBlocks(sourceXml, ['w:p', 'w:tbl']);
+        if (blocks.length === 0) {
+            const text = this.extractTextFromXml(documentXml, 'w:t');
+            const imageMarkers = this.extractDocxImageMarkers(documentXml, relationships);
+            return {
+                text: [text, ...imageMarkers].filter(Boolean).join('\n'),
+                embeddedImageCount: imageMarkers.length
+            };
+        }
+        const lines = [];
+        let embeddedImageCount = 0;
+        for (const block of blocks) {
+            if (block.tagName === 'w:tbl') {
+                const table = this.extractDocxTableText(block.xml, relationships);
+                if (table.lines.length > 0) {
+                    lines.push('[Table]', ...table.lines);
+                }
+                embeddedImageCount += table.embeddedImageCount;
+                continue;
+            }
+            const paragraph = this.extractDocxParagraphText(block.xml, relationships);
+            if (paragraph.lines.length > 0) {
+                lines.push(...paragraph.lines);
+            }
+            embeddedImageCount += paragraph.embeddedImageCount;
+        }
+        return {
+            text: lines.filter(Boolean).join('\n'),
+            embeddedImageCount
+        };
+    }
+    extractXmlBlocks(xml, tagNames) {
+        const pattern = tagNames.map(tag => tag.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')).join('|');
+        const regex = new RegExp(`<(${pattern})\\b[^>]*>[\\s\\S]*?</\\1>`, 'g');
+        const blocks = [];
+        let match;
+        while ((match = regex.exec(xml)) !== null) {
+            blocks.push({ tagName: match[1] ?? '', xml: match[0] });
+        }
+        return blocks;
+    }
+    extractDocxTableText(tableXml, relationships) {
+        const rows = this.extractXmlBlocks(tableXml, ['w:tr']);
+        const lines = [];
+        let embeddedImageCount = 0;
+        for (const row of rows) {
+            const cells = this.extractXmlBlocks(row.xml, ['w:tc']);
+            const cellTexts = [];
+            for (const cell of cells) {
+                const paragraphs = this.extractXmlBlocks(cell.xml, ['w:p']);
+                const paragraphLines = [];
+                for (const paragraphXml of paragraphs) {
+                    const paragraph = this.extractDocxParagraphText(paragraphXml.xml, relationships);
+                    paragraphLines.push(...paragraph.lines);
+                    embeddedImageCount += paragraph.embeddedImageCount;
+                }
+                if (paragraphs.length === 0) {
+                    const paragraph = this.extractDocxParagraphText(cell.xml, relationships);
+                    paragraphLines.push(...paragraph.lines);
+                    embeddedImageCount += paragraph.embeddedImageCount;
+                }
+                cellTexts.push(paragraphLines.join(' / ').replace(/\s*\n\s*/g, ' / ').trim());
+            }
+            const rowText = cellTexts.join('\t').trim();
+            if (rowText) {
+                lines.push(rowText);
+            }
+        }
+        return { lines, embeddedImageCount };
+    }
+    extractDocxParagraphText(paragraphXml, relationships) {
+        const text = this.extractTextRunsFromXml(paragraphXml, 'w:t').join('').trim();
+        const imageMarkers = this.extractDocxImageMarkers(paragraphXml, relationships);
+        return {
+            lines: [text, ...imageMarkers].filter(Boolean),
+            embeddedImageCount: imageMarkers.length
+        };
+    }
+    extractDocxImageMarkers(paragraphXml, relationships) {
+        const relIds = new Set();
+        const relRegex = /\br:(?:embed|link|id)=["']([^"']+)["']/g;
+        let match;
+        const hasImageMarkup = /<(?:w:drawing|w:pict|pic:pic|v:imagedata)\b/.test(paragraphXml);
+        while ((match = relRegex.exec(paragraphXml)) !== null) {
+            relIds.add(this.decodeXmlText(match[1] ?? ''));
+        }
+        const markers = [...relIds]
+            .map(relId => relationships.get(relId))
+            .filter((target) => Boolean(target))
+            .map(target => `[Embedded image: ${target}]`);
+        if (markers.length === 0 && hasImageMarkup) {
+            markers.push('[Embedded image]');
+        }
+        return markers;
+    }
+    extractTextRunsFromXml(xml, tagName) {
+        const regex = new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)</${tagName}>`, 'g');
         const texts = [];
-        for (const match of matches) {
-            const text = match.replace(/<[^>]+>/g, '').trim();
-            if (text) {
-                texts.push(text);
+        let match;
+        while ((match = regex.exec(xml)) !== null) {
+            texts.push(this.decodeXmlText(match[1] ?? ''));
+        }
+        return texts;
+    }
+    decodeXmlText(text) {
+        return text
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&amp;/g, '&')
+            .replace(/&quot;/g, '"')
+            .replace(/&apos;/g, "'");
+    }
+    extractDocxRelationships(zip) {
+        const relationships = new Map();
+        for (const relationship of this.extractDocxImageRelationshipEntries(zip)) {
+            relationships.set(relationship.id, relationship.target);
+        }
+        return relationships;
+    }
+    extractDocxImageRelationshipEntries(zip) {
+        const relationships = [];
+        try {
+            const relsXml = zip.readAsText('word/_rels/document.xml.rels');
+            const relMatches = relsXml.match(/<Relationship\b[^>]*\/?>/g) || [];
+            for (const relXml of relMatches) {
+                const id = this.getXmlAttribute(relXml, 'Id');
+                const type = this.getXmlAttribute(relXml, 'Type');
+                const target = this.getXmlAttribute(relXml, 'Target');
+                const targetMode = this.getXmlAttribute(relXml, 'TargetMode');
+                if (id && target && targetMode !== 'External' && type?.endsWith('/image')) {
+                    const zipPath = resolveDocxImageTargetToZipPath(target);
+                    if (zipPath) {
+                        relationships.push({ id, target, zipPath });
+                    }
+                }
             }
         }
-        return texts.join(' ');
+        catch {
+            // Relationship extraction is best-effort; text extraction can continue.
+        }
+        return relationships;
+    }
+    extractDocxImageRelationshipIdsInDocumentOrder(documentXml) {
+        const ids = [];
+        const seen = new Set();
+        const relRegex = /\br:(?:embed|link)=["']([^"']+)["']/g;
+        let match;
+        while ((match = relRegex.exec(documentXml)) !== null) {
+            const id = this.decodeXmlText(match[1] ?? '');
+            if (!seen.has(id)) {
+                ids.push(id);
+                seen.add(id);
+            }
+        }
+        return ids;
+    }
+    getXmlAttribute(xml, attributeName) {
+        const match = xml.match(new RegExp(`\\b${attributeName}=(["'])(.*?)\\1`));
+        return match ? this.decodeXmlText(match[2] ?? '') : undefined;
     }
     /**
      * Extract DOCX metadata
@@ -453,6 +734,9 @@ export class DocumentTool {
         if (content.metadata.wordCount) {
             lines.push(`   Words: ${content.metadata.wordCount}`);
         }
+        if (content.metadata.embeddedImageCount) {
+            lines.push(`   Images: ${content.metadata.embeddedImageCount}`);
+        }
         if (content.metadata.sheetCount) {
             lines.push(`   Sheets: ${content.metadata.sheetCount}`);
         }
@@ -530,4 +814,25 @@ export class DocumentTool {
         return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
     }
 }
+function safeReadZipText(zip, entryName) {
+    try {
+        return zip.readAsText(entryName);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveDocxImageTargetToZipPath(target) {
+    const normalized = target.trim().replace(/\\/g, '/').replace(/^\/+/, '');
+    if (!normalized || normalized.includes('..')) {
+        return null;
+    }
+    const zipPath = normalized.startsWith('word/')
+        ? normalized
+        : path.posix.join('word', normalized);
+    return zipPath.startsWith('word/media/') ? zipPath : null;
+}
+function formatMarkdownPath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
 //# sourceMappingURL=document-tool.js.map

package/dist/tools/enhanced-search.js

@@ -402,8 +402,9 @@ export class EnhancedSearch extends EventEmitter {
         ];
         for (const pattern of patterns) {
             const match = text.match(pattern);
-            if (match) {
-                name = match[1];
+            const captured = match?.[1];
+            if (captured !== undefined) {
+                name = captured;
                 break;
             }
         }
@@ -621,8 +622,9 @@ export class EnhancedSearch extends EventEmitter {
         if (match) {
             // Find the capture group with the name (usually last non-empty one)
             for (let i = match.length - 1; i >= 1; i--) {
-                if (match[i] && /^[a-zA-Z_$]/.test(match[i])) {
-                    name = match[i];
+                const group = match[i];
+                if (group && /^[a-zA-Z_$]/.test(group)) {
+                    name = group;
                     break;
                 }
             }

package/dist/tools/env-tool.js

@@ -165,6 +165,8 @@ export class EnvTool {
             const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/i);
             if (match) {
                 const [, key, value] = match;
+                if (key === undefined || value === undefined)
+                    continue;
                 // Remove surrounding quotes
                 const cleanValue = value.replace(/^["']|["']$/g, '');
                 process.env[key] = cleanValue;
@@ -231,7 +233,10 @@ export class EnvTool {
         const issues = [];
         const variables = [];
         for (let i = 0; i < lines.length; i++) {
-            const line = lines[i].trim();
+            const rawLine = lines[i];
+            if (rawLine === undefined)
+                continue;
+            const line = rawLine.trim();
             const lineNum = i + 1;
             // Skip comments and empty lines
             if (!line || line.startsWith('#'))
@@ -243,6 +248,8 @@ export class EnvTool {
                 continue;
             }
             const [, key, value] = match;
+            if (key === undefined || value === undefined)
+                continue;
             variables.push(key);
             // Check for common issues
             if (value.startsWith(' ') || value.endsWith(' ')) {

package/dist/tools/execute-code-rpc-invoker.d.ts

@@ -0,0 +1,50 @@
+/**
+ * execute_code → Code Buddy tool RPC invoker (opt-in, OFF by default).
+ *
+ * Hermes parity (`delegation-parallelism`): generated code run by
+ * `execute_code` may call back into a *small, read-only* set of Code
+ * Buddy tools via RPC. This module owns the **policy + execution** half
+ * of that channel; the runner (`execute-code-runner.ts`) owns the
+ * transport (file framing, call-count bound, per-call timeout).
+ *
+ * Security model — fail closed at every gate, in order:
+ *   1. **Master flag** — disabled unless `CODEBUDDY_EXECUTE_CODE_TOOL_RPC`
+ *      is truthy (`true`/`1`/`yes`/`on`). Enforced by the runner BEFORE
+ *      this invoker is ever constructed, so a child process can never
+ *      flip it on. When off, the runner still answers every request with
+ *      a structured denial (never a hang).
+ *   2. **Allowlist** — `tool ∈ {view_file, list_directory, search}`,
+ *      override via env `CODEBUDDY_EXECUTE_CODE_TOOL_RPC_ALLOWLIST` (csv).
+ *   3. **fleetSafe** — the tool's registry metadata must declare
+ *      `fleetSafe: true` (read-only by definition).
+ *
+ * No write/exec tool is reachable; the executors below physically only
+ * read. This mirrors the audited `peer-tool-bridge.ts` pattern.
+ */
+export interface ExecuteCodeRpcInvokeRequest {
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface ExecuteCodeRpcInvokeResult {
+    ok: boolean;
+    output?: string;
+    error?: string;
+    truncated?: boolean;
+}
+export type ExecuteCodeRpcInvoker = (request: ExecuteCodeRpcInvokeRequest) => Promise<ExecuteCodeRpcInvokeResult>;
+/** Truthy-flag parse — the single master gate. Read once, in the parent. */
+export declare function isExecuteCodeToolRpcEnabled(raw?: string | undefined): boolean;
+export declare function getExecuteCodeToolRpcAllowlist(raw?: string | undefined): Set<string>;
+interface InvokerOptions {
+    /** Root the read-only executors are confined to. Defaults to cwd. */
+    workspaceRoot: string;
+    allowlist?: Set<string>;
+    isFleetSafe?: (name: string) => boolean;
+}
+/**
+ * Build the policy-gated invoker. The master flag is intentionally NOT
+ * read here — the runner only constructs an invoker once it has already
+ * decided RPC is enabled, keeping the flag boundary in the parent.
+ */
+export declare function createExecuteCodeRpcInvoker(options: InvokerOptions): ExecuteCodeRpcInvoker;
+export {};