@compilr-dev/sdk 0.7.15 → 0.7.17

package/dist/platform/tools/document-tools.d.ts

@@ -13,6 +13,13 @@ export declare function createDocumentTools(config: PlatformToolsConfig): (impor
     doc_type: string;
     title: string;
     content: string;
+}> | import("@compilr-dev/agents").Tool<{
+    project_id?: number;
+    doc_type: string;
+    startLine?: number;
+    maxLines?: number;
+    section?: string;
+    summary_only?: boolean;
 }> | import("@compilr-dev/agents").Tool<{
     project_id?: number;
     doc_type: string;

package/dist/platform/tools/document-tools.js

@@ -114,7 +114,9 @@ export function createDocumentTools(config) {
     // ---------------------------------------------------------------------------
     const projectDocumentGetTool = defineTool({
         name: 'project_document_get',
-        description: 'Get a project document by type. Returns the document content.',
+        description: 'Get a project document by type. ' +
+            'Use maxLines/startLine for partial reads, section to read a specific heading, ' +
+            'or summary_only to get the document structure without full content.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -123,6 +125,24 @@ export function createDocumentTools(config) {
                     enum: DOC_TYPE_ENUM,
                     description: 'Document type to retrieve',
                 },
+                startLine: {
+                    type: 'number',
+                    description: 'Line number to start reading from (1-indexed, default: 1)',
+                },
+                maxLines: {
+                    type: 'number',
+                    description: 'Maximum number of lines to return (default: all)',
+                },
+                section: {
+                    type: 'string',
+                    description: 'Read only a specific section by its markdown heading (e.g., "## Methods"). ' +
+                        'Returns the heading and all content until the next heading of equal or higher level.',
+                },
+                summary_only: {
+                    type: 'boolean',
+                    description: 'If true, returns only the document structure: headings with line numbers and character counts per section. ' +
+                        'Useful for navigating large documents before reading specific parts.',
+                },
                 project_id: {
                     type: 'number',
                     description: 'Override active project.',
@@ -144,13 +164,104 @@ export function createDocumentTools(config) {
                         message: `No ${input.doc_type} document found for this project`,
                     });
                 }
+                const allLines = doc.content.split('\n');
+                const totalLines = allLines.length;
+                const totalChars = doc.content.length;
+                // ── summary_only: return document structure ──
+                if (input.summary_only) {
+                    const sections = [];
+                    for (let i = 0; i < allLines.length; i++) {
+                        const match = allLines[i].match(/^(#{1,6})\s+(.+)/);
+                        if (match) {
+                            // Close previous section
+                            if (sections.length > 0) {
+                                const prev = sections[sections.length - 1];
+                                prev.chars = allLines.slice(prev.line - 1, i).join('\n').length;
+                            }
+                            sections.push({
+                                heading: allLines[i].trim(),
+                                line: i + 1, // 1-indexed
+                                chars: 0,
+                            });
+                        }
+                    }
+                    // Close last section
+                    if (sections.length > 0) {
+                        const prev = sections[sections.length - 1];
+                        prev.chars = allLines.slice(prev.line - 1).join('\n').length;
+                    }
+                    return createSuccessResult({
+                        success: true,
+                        document: {
+                            id: doc.id,
+                            docType: doc.docType,
+                            title: doc.title,
+                            totalLines,
+                            totalChars,
+                            sections,
+                            hint: 'Use section param to read a specific heading, or startLine/maxLines for line ranges',
+                            updatedAt: doc.updatedAt.toISOString(),
+                        },
+                    });
+                }
+                // ── section: extract content under a specific heading ──
+                if (input.section) {
+                    const heading = input.section.trim();
+                    const headingLevel = heading.match(/^(#{1,6})\s/)?.[1]?.length ?? 2;
+                    let sectionStart = -1;
+                    let sectionEnd = allLines.length;
+                    for (let i = 0; i < allLines.length; i++) {
+                        const line = allLines[i].trim();
+                        if (sectionStart === -1) {
+                            if (line === heading) {
+                                sectionStart = i;
+                            }
+                        }
+                        else {
+                            const nextMatch = line.match(/^(#{1,6})\s/);
+                            if (nextMatch && nextMatch[1].length <= headingLevel) {
+                                sectionEnd = i;
+                                break;
+                            }
+                        }
+                    }
+                    if (sectionStart === -1) {
+                        const headings = allLines
+                            .filter((l) => l.trim().match(/^#{1,6}\s/))
+                            .map((l) => l.trim());
+                        return createErrorResult(`Section "${heading}" not found. Available headings: ${headings.join(', ') || '(none)'}`);
+                    }
+                    return createSuccessResult({
+                        success: true,
+                        document: {
+                            id: doc.id,
+                            docType: doc.docType,
+                            title: doc.title,
+                            content: allLines.slice(sectionStart, sectionEnd).join('\n'),
+                            totalLines,
+                            sectionLines: { start: sectionStart + 1, end: sectionEnd },
+                            updatedAt: doc.updatedAt.toISOString(),
+                        },
+                    });
+                }
+                // ── startLine/maxLines: line range ──
+                let content = doc.content;
+                let truncated = false;
+                if (input.startLine || input.maxLines) {
+                    const start = Math.max(0, (input.startLine ?? 1) - 1);
+                    const end = input.maxLines ? start + input.maxLines : allLines.length;
+                    content = allLines.slice(start, end).join('\n');
+                    truncated = end < allLines.length;
+                }
                 return createSuccessResult({
                     success: true,
                     document: {
                         id: doc.id,
                         docType: doc.docType,
                         title: doc.title,
-                        content: doc.content,
+                        content,
+                        totalLines,
+                        ...(truncated ? { truncated: true, hint: 'Use startLine/maxLines to read more' } : {}),
                         createdAt: doc.createdAt.toISOString(),
                         updatedAt: doc.updatedAt.toISOString(),
                     },

package/dist/project-generator/templates/compilr-md-import.js

@@ -37,7 +37,7 @@ This project uses compilr's database for tracking. Use these tools to access pro
 | Data Type | Read Tool | Write Tool |
 |-----------|-----------|------------|
 | Work Items (Backlog) | \`workitem_query\` | \`workitem_add\`, \`workitem_update\` |
-| Project Documents | \`project_document_get\`, \`project_document_list\` | \`project_document_add\` |
+| Project Documents | \`project_document_get\`, \`project_document_list\` | \`project_document_add\`, \`project_document_patch\` |
 | Anchors (Context) | \`anchor_list\` | \`anchor_add\`, \`anchor_remove\` |
 
 **Important:** Use database tools for project metadata. Explore the existing codebase for implementation details.

package/dist/project-generator/templates/compilr-md.js

@@ -34,7 +34,7 @@ This project uses compilr's database for tracking. Use these tools to access pro
 | Data Type | Read Tool | Write Tool |
 |-----------|-----------|------------|
 | Work Items (Backlog) | \`workitem_query\` | \`workitem_add\`, \`workitem_update\` |
-| Project Documents | \`project_document_get\`, \`project_document_list\` | \`project_document_add\` |
+| Project Documents | \`project_document_get\`, \`project_document_list\` | \`project_document_add\`, \`project_document_patch\` |
 | Anchors (Context) | \`anchor_list\` | \`anchor_add\`, \`anchor_remove\` |
 
 **Important:** Always use database tools instead of exploring the filesystem for project data.

package/dist/team/types.js

@@ -112,7 +112,7 @@ You are the **Project Manager (PM)** in this multi-agent development team. You s
 **Specialized tools** (call via \`use_tool\`):
 - \`workitem_add\`, \`workitem_update\`, \`workitem_query\` - Manage work items
 - \`workitem_claim\`, \`workitem_handoff\` - Assign and reassign tasks between agents
-- \`project_document_add\`, \`project_document_get\` - Save/retrieve project docs (PRD, architecture, design, plan, notes)
+- \`project_document_add\`, \`project_document_get\`, \`project_document_patch\` - Save/retrieve/update project docs. Use patch (append/prepend/replace_section) for large docs to avoid reading the full content
 - \`artifact_save\`, \`artifact_get\` - Store team decisions, meeting notes, reviews
 
 **IMPORTANT:** Specialized tools must be called via \`use_tool\`. Example: \`use_tool("project_document_add", {"doc_type": "design", "title": "...", "content": "..."})\`.
@@ -511,7 +511,7 @@ You are the **Technical Writer** in this multi-agent development team. You creat
 - \`handoff\` - Hand off to another specialist
 
 **Specialized tools** (call via \`use_tool\`):
-- \`project_document_add\`, \`project_document_get\` - Save/retrieve project docs (PRD, architecture, design, plan, notes)
+- \`project_document_add\`, \`project_document_get\`, \`project_document_patch\` - Save/retrieve/update project docs. Use patch (append/prepend/replace_section) for large docs to avoid reading the full content
 - \`artifact_save\` - Store drafts and notes for team reference
 
 **IMPORTANT:** Specialized tools must be called via \`use_tool\`. Example: \`use_tool("project_document_add", {"doc_type": "notes", "title": "...", "content": "..."})\`.
@@ -597,7 +597,7 @@ You are the **Business Analyst** in this multi-agent development team. You trans
 
 **Specialized tools** (call via \`use_tool\`):
 - \`workitem_add\`, \`workitem_update\` - Create and refine requirements
-- \`project_document_add\`, \`project_document_get\` - Save/retrieve project docs (PRD, architecture, design, plan, notes)
+- \`project_document_add\`, \`project_document_get\`, \`project_document_patch\` - Save/retrieve/update project docs. Use patch (append/prepend/replace_section) for large docs to avoid reading the full content
 - \`artifact_save\` - Store analysis notes, diagrams for team reference
 
 **IMPORTANT:** Specialized tools must be called via \`use_tool\`. Example: \`use_tool("project_document_add", {"doc_type": "prd", "title": "...", "content": "..."})\`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",