@ai-coders/context 0.4.0 → 0.5.0

package/README.md

@@ -19,7 +19,12 @@ A lightweight CLI that scaffolds living documentation and AI-agent playbooks for
 - 🤖 `agents/` folder containing playbooks for common engineering agents and a handy index
 - 🔁 Repeatable scaffolding that you can re-run as the project evolves
 - 🧭 Repository-aware templates that highlight top-level directories for quick orientation
-- 🧠 AI-ready front matter and `agent-update` markers so assistants know exactly what to refresh
+- 🧠 AI-ready templates that assistants can update using the `fill` command
+- 🌐 **Multi-provider support** for OpenAI, Anthropic, Google, and OpenRouter
+- ⚡ **Semantic context mode** using Tree-sitter for token-efficient LLM calls
+- 📊 **Real-time progress** showing agent activity and tool usage
+- 🔌 **MCP Server** for seamless Claude Code integration
+- 🔗 **Passthrough mode** for external AI agents via stdin/stdout JSON
 
 ## 📦 Installation
 
@@ -54,6 +59,15 @@ npx @ai-coders/context init ./my-repo agents --output ./knowledge-base
 # Fill docs and agents with the repo context (preview the first 3 updates)
 npx @ai-coders/context fill ./my-repo --output ./.context --limit 3
 
+# Use a specific provider (OpenAI, Anthropic, Google, or OpenRouter)
+npx @ai-coders/context fill ./my-repo --provider anthropic --model claude-sonnet-4-20250514
+
+# Disable semantic mode for more thorough tool-based exploration
+npx @ai-coders/context fill ./my-repo --no-semantic
+
+# Specify languages for semantic analysis
+npx @ai-coders/context fill ./my-repo --languages typescript,python,go
+
 # Draft a collaboration plan seeded with agent and doc touchpoints
 npx @ai-coders/context plan release-readiness --output ./.context
 
@@ -77,17 +91,91 @@ After running the command, inspect the generated structure:
     └── ...
 ```
 
-Customize the Markdown files to reflect your project’s specifics and commit them alongside the code.
+Customize the Markdown files to reflect your project's specifics and commit them alongside the code.
 
-## 🧠 Guided Updates for AI Assistants
+## 🌐 Multi-Provider Support
+
+The `fill` and `plan` commands support multiple LLM providers:
+
+| Provider | Models | Environment Variable |
+|----------|--------|---------------------|
+| OpenRouter | `x-ai/grok-4-fast`, `anthropic/claude-sonnet-4`, etc. | `OPENROUTER_API_KEY` |
+| OpenAI | `gpt-4o`, `gpt-4-turbo`, etc. | `OPENAI_API_KEY` |
+| Anthropic | `claude-sonnet-4-20250514`, `claude-opus-4-20250514`, etc. | `ANTHROPIC_API_KEY` |
+| Google | `gemini-2.0-flash`, `gemini-1.5-pro`, etc. | `GOOGLE_API_KEY` |
+
+The CLI auto-detects available API keys from environment variables. Override with `--provider` and `--model`:
+
+```bash
+# Use Anthropic's Claude
+ANTHROPIC_API_KEY=sk-... npx @ai-coders/context fill . --provider anthropic
+
+# Use OpenAI's GPT-4
+OPENAI_API_KEY=sk-... npx @ai-coders/context fill . --provider openai --model gpt-4o
+```
+
+## ⚡ Semantic Context Mode
+
+By default, the `fill` command uses **semantic context mode** which pre-computes codebase analysis using Tree-sitter before calling the LLM. This is:
+
+- **Faster**: Single LLM call instead of multi-step tool exploration
+- **Token-efficient**: Pre-computed context instead of back-and-forth tool calls
+- **Consistent**: Same analysis applied to all files
+
+To use the more thorough tool-based exploration (where the LLM explores the codebase step by step), use `--no-semantic`:
+
+```bash
+npx @ai-coders/context fill . --no-semantic
+```
+
+### Language Selection
+
+Specify which programming languages to analyze for semantic context:
+
+```bash
+# Analyze only TypeScript and Python
+npx @ai-coders/context fill . --languages typescript,python
+
+# Default languages: typescript, javascript, python, go
+```
+
+Supported languages: `typescript`, `javascript`, `python`, `go`, `rust`, `java`, `cpp`, `c_sharp`, `ruby`, `php`
+
+### LSP Enhancement (Optional)
+
+For deeper semantic analysis, the tool supports optional **LSP (Language Server Protocol)** integration. While Tree-sitter handles ~90% of the analysis with fast syntactic parsing, LSP provides additional semantic information when enabled:
 
-Need help filling in the scaffold? Use [`prompts/update_scaffold_prompt.md`](./prompts/update_scaffold_prompt.md) as the canonical instruction set for any LLM or CLI agent. It walks through:
+| Feature | Tree-sitter | LSP |
+|---------|-------------|-----|
+| Symbol extraction | ✅ | - |
+| Import/export analysis | ✅ | - |
+| Type inference | - | ✅ |
+| Interface implementations | - | ✅ |
+| Cross-file references | - | ✅ |
+| Definition resolution | - | ✅ |
 
-- Gathering repository context and locating `agent-update`/`agent-fill` markers.
-- Updating documentation sections while satisfying the YAML front matter criteria.
-- Aligning agent playbooks with the refreshed docs and recording evidence for maintainers.
+**Usage:**
+
+```bash
+# Enable LSP for fill command (disabled by default)
+npx @ai-coders/context fill ./my-repo --lsp
+
+# LSP is enabled by default for plan fill
+npx @ai-coders/context plan my-plan --fill
+
+# Disable LSP for plan fill
+npx @ai-coders/context plan my-plan --fill --no-lsp
+```
 
-Share that prompt verbatim with your assistant to keep updates consistent across teams.
+**Supported Language Servers:**
+- TypeScript/JavaScript: `typescript-language-server`
+- Python: `pylsp`
+
+**Graceful Degradation:** If a language server is not installed, the analysis continues without LSP enhancement—no errors, no interruption.
+
+## 🧠 Guided Updates for AI Assistants
+
+Need help filling in the scaffold? Use [`prompts/update_scaffold_prompt.md`](./prompts/update_scaffold_prompt.md) as the canonical instruction set for any LLM or CLI agent. Share that prompt verbatim with your assistant to keep updates consistent across teams.
 
 ### Available Doc Guides & Agent Types
 
@@ -96,14 +184,6 @@ The scaffold includes the following guides and playbooks out of the box:
 - Docs: `project-overview`, `architecture`, `development-workflow`, `testing-strategy`, `glossary`, `data-flow`, `security`, `tooling`
 - Agents: `code-reviewer`, `bug-fixer`, `feature-developer`, `refactoring-specialist`, `test-writer`, `documentation-writer`, `performance-optimizer`, `security-auditor`, `backend-specialist`, `frontend-specialist`, `architect-specialist`
 
-### AI Marker Reference
-
-- `<!-- agent-update:start:section-id --> … <!-- agent-update:end -->` wrap the sections that AI assistants should rewrite with up-to-date project knowledge.
-- `<!-- agent-fill:slot-id --> … <!-- /agent-fill -->` highlight inline placeholders that must be replaced with concrete details before removing the wrapper.
-- `<!-- agent-readonly:context -->` flags guidance that should remain as-is; treat the adjacent content as instructions rather than editable prose.
-
-When contributing, focus edits inside `agent-update` regions or `agent-fill` placeholders and leave `agent-readonly` guidance untouched unless you have explicit maintainer approval.
-
 ## 🛠 Commands
 
 ### `init`
@@ -120,6 +200,7 @@ Options:
   -o, --output <dir>      Output directory (default: ./.context)
   --exclude <patterns...> Glob patterns to skip during the scan
   --include <patterns...> Glob patterns to explicitly include
+  --no-semantic           Disable semantic code analysis
   -v, --verbose           Print detailed progress information
   -h, --help              Display help for command
 ```
@@ -134,14 +215,19 @@ Options:
   -o, --output <dir>      Scaffold directory containing docs/ and agents/ (default: ./.context)
   -k, --api-key <key>     API key for the selected LLM provider
   -m, --model <model>     LLM model to use (default: x-ai/grok-4-fast)
-  -p, --provider <name>   Provider (openrouter only)
-      --base-url <url>    Custom base URL for OpenRouter
+  -p, --provider <name>   Provider: openrouter, openai, anthropic, or google
+      --base-url <url>    Custom base URL for provider APIs
       --prompt <file>     Instruction prompt to follow (optional; uses bundled instructions when omitted)
       --limit <number>    Maximum number of files to update in one run
+      --no-semantic       Disable semantic context mode (use tool-based exploration)
+      --languages <langs> Programming languages to analyze (e.g., typescript,python,go)
+      --exclude <patterns...> Glob patterns to exclude from repository analysis
+      --include <patterns...> Glob patterns to include during analysis
+  -v, --verbose           Print detailed progress information
   -h, --help              Display help for command
 ```
 
-Under the hood, the command loads the prompt above, iterates over every Markdown file in `.context/docs` and `.context/agents`, and asks the LLM to produce the fully updated content.
+Under the hood, the command uses specialized agents (DocumentationAgent, PlaybookAgent) that analyze your codebase and generate context-aware documentation. Real-time progress is displayed showing which agent is working and what tools are being used.
 
 ### `plan`
 Create a collaboration plan that links documentation guides and agent playbooks, or fill an existing plan with LLM assistance.
@@ -158,12 +244,14 @@ Options:
   -r, --repo <path>       Repository root to summarize for additional context (fill mode)
   -k, --api-key <key>     API key for the selected LLM provider (fill mode)
   -m, --model <model>     LLM model to use (default: x-ai/grok-4-fast)
-  -p, --provider <name>   Provider (openrouter only)
-      --base-url <url>    Custom base URL for OpenRouter
+  -p, --provider <name>   Provider: openrouter, openai, anthropic, or google
+      --base-url <url>    Custom base URL for provider APIs
       --prompt <file>     Instruction prompt to follow (optional; uses bundled instructions when omitted)
       --dry-run           Preview changes without writing files
+      --no-semantic       Disable semantic context mode
       --include <patterns...>  Glob patterns to include during repository analysis
       --exclude <patterns...>  Glob patterns to exclude from repository analysis
+  -v, --verbose           Print detailed progress information
   -h, --help              Display help for command
 ```
 
@@ -171,7 +259,157 @@ In scaffold mode the command creates `.context/plans/<plan-name>.md`, keeps a `p
 
 💡 Tip: run `npx @ai-coders/context` with no arguments to enter an interactive mode that guides you through scaffold and LLM-fill options.
 
-Prefer driving the update elsewhere? Just grab [`prompts/update_scaffold_prompt.md`](./prompts/update_scaffold_prompt.md) and run it in your favorite playground or agent host. When you’re ready to automate, drop your API key in `.env` (for example `OPENROUTER_API_KEY` and `OPENROUTER_MODEL`) and let `fill` handle the edits inline.
+Prefer driving the update elsewhere? Just grab [`prompts/update_scaffold_prompt.md`](./prompts/update_scaffold_prompt.md) and run it in your favorite playground or agent host. When you're ready to automate, drop your API key in `.env` (for example `OPENROUTER_API_KEY` and `OPENROUTER_MODEL`) and let `fill` handle the edits inline.
+
+### `mcp`
+Start an MCP (Model Context Protocol) server for Claude Code integration. This exposes code analysis tools and semantic context as MCP resources.
+
+```
+Usage: ai-context mcp
+
+Options:
+  -r, --repo-path <path>  Default repository path for tools
+  -v, --verbose           Enable verbose logging to stderr
+  -h, --help              Display help for command
+```
+
+**Available MCP Tools:**
+- `readFile` - Read file contents from the filesystem
+- `listFiles` - List files matching a glob pattern
+- `analyzeSymbols` - Extract code symbols (classes, functions, interfaces) using Tree-sitter
+- `getFileStructure` - Get the directory structure of a repository
+- `searchCode` - Search for code patterns using regex
+- `buildSemanticContext` - Build optimized semantic context for LLM prompts
+- `checkScaffolding` - Check if `.context` scaffolding exists (returns granular status for docs, agents, plans)
+- `initializeContext` - Initialize `.context` scaffolding (create template files)
+- `fillScaffolding` - Analyze codebase and generate content for each template file (AI agent writes the content)
+- `scaffoldPlan` - Create a plan template in `.context/plans/`
+
+**Available MCP Resources:**
+- `context://codebase/{contextType}` - Semantic context (documentation, playbook, plan, compact)
+- `file://{path}` - Read file contents
+
+### `serve`
+Start a passthrough server for external AI agents. Accepts JSON commands via stdin and responds via stdout.
+
+```
+Usage: ai-context serve
+
+Options:
+  -r, --repo-path <path>  Default repository path for tools
+  -f, --format <format>   Output format: json or jsonl (default: jsonl)
+  -v, --verbose           Enable verbose logging to stderr
+  -h, --help              Display help for command
+```
+
+**Available Methods:**
+- `capabilities` - List server capabilities
+- `tool.list` - List available tools
+- `tool.call` - Execute a tool
+- `context.build` - Build semantic context
+- `agent.run` - Run an agent (requires LLM config)
+
+## 🔌 Claude Code Integration (MCP)
+
+The easiest way to use this package with Claude Code is through the MCP server. Add the following to your Claude Code settings:
+
+**~/.claude/settings.json:**
+```json
+{
+  "mcpServers": {
+    "ai-context": {
+      "command": "npx",
+      "args": ["@ai-coders/context", "mcp", "-r", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
+Once configured, Claude Code will have access to all code analysis tools:
+
+```
+# Claude Code can now use these tools:
+- readFile: Read any file in your repository
+- listFiles: Find files by glob patterns
+- analyzeSymbols: Extract code structure with Tree-sitter
+- searchCode: Search for patterns across the codebase
+- buildSemanticContext: Get optimized context for any task
+- checkScaffolding: Check if .context scaffolding exists
+- initializeContext: Create scaffolding templates
+- fillScaffolding: Generate content for templates
+- scaffoldPlan: Create plan templates
+```
+
+### Example MCP Usage in Claude Code
+
+When working with Claude Code, you can ask it to:
+
+- "Use the ai-context tools to analyze the authentication module"
+- "Build a semantic context for the src/services directory"
+- "List all TypeScript files in the project and analyze their exports"
+
+## 🔗 External AI Agent Integration (Passthrough)
+
+For AI agents that don't support MCP, use the passthrough server with JSON communication:
+
+```bash
+# Start the server
+npx @ai-coders/context serve -r ./my-project
+
+# Send commands via stdin
+echo '{"id":"1","method":"capabilities"}' | npx @ai-coders/context serve
+```
+
+**Example: List files**
+```bash
+echo '{"id":"1","method":"tool.call","params":{"tool":"listFiles","args":{"pattern":"**/*.ts"}}}' \
+  | npx @ai-coders/context serve -r ./my-project
+```
+
+**Example: Build semantic context**
+```bash
+echo '{"id":"1","method":"context.build","params":{"repoPath":"./","contextType":"documentation"}}' \
+  | npx @ai-coders/context serve
+```
+
+**Response format:**
+```json
+{
+  "id": "1",
+  "success": true,
+  "result": { /* tool output */ }
+}
+```
+
+**Notifications (streamed during execution):**
+```json
+{"type": "progress", "data": {"step": 1, "message": "Analyzing..."}}
+{"type": "tool_call", "data": {"toolName": "readFile", "args": {"filePath": "..."}}}
+{"type": "tool_result", "data": {"toolName": "readFile", "success": true}}
+```
+
+## 🔧 Environment Variables
+
+```bash
+# Provider selection (auto-detected from available keys)
+AI_CONTEXT_PROVIDER=openrouter|openai|anthropic|google
+
+# API Keys (at least one required for fill/plan --fill)
+OPENROUTER_API_KEY=...
+OPENAI_API_KEY=...
+ANTHROPIC_API_KEY=...
+GOOGLE_API_KEY=...
+
+# Optional model override per provider
+OPENROUTER_MODEL=x-ai/grok-4-fast
+OPENAI_MODEL=gpt-4o
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+GOOGLE_MODEL=gemini-2.0-flash
+
+# CLI settings
+AI_CONTEXT_LANG=en|pt-BR
+AI_CONTEXT_DISABLE_UPDATE_CHECK=true
+```
 
 ## 🧰 Local Development
 

package/dist/fragments/compose.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fragment Composition - Strategies for combining fragments
+ */
+import type { ContextFragment, CompositionOptions, FragmentStore } from './types.js';
+/**
+ * Compose fragments into a coherent context using the specified strategy
+ */
+export declare function composeFragments(fragments: ContextFragment<unknown>[], options: CompositionOptions): ContextFragment<unknown>[];
+/**
+ * Create a composition pipeline helper
+ */
+export declare function createComposer(store: FragmentStore): {
+    /**
+     * Compose by priority (default)
+     */
+    byPriority(maxTokens?: number): ContextFragment<unknown>[];
+    /**
+     * Compose by expanding from a seed
+     */
+    expand(seed: string, depth?: number, maxTokens?: number): ContextFragment<unknown>[];
+    /**
+     * Compose by task relevance
+     */
+    forTask(task: string, maxTokens?: number): ContextFragment<unknown>[];
+    /**
+     * Get essential context (project overview + high priority)
+     */
+    essential(maxTokens?: number): ContextFragment<unknown>[];
+};
+//# sourceMappingURL=compose.d.ts.map

package/dist/fragments/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/fragments/compose.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAElB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,EACrC,OAAO,EAAE,kBAAkB,GAC1B,eAAe,CAAC,OAAO,CAAC,EAAE,CAW5B;AA6QD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa;IAE/C;;OAEG;2BACoB,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,EAAE;IAO1D;;OAEG;iBACU,MAAM,UAAU,MAAM,cAAc,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,EAAE;IASpF;;OAEG;kBACW,MAAM,cAAc,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,EAAE;IAQrE;;OAEG;0BACmB,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,EAAE;EAe5D"}

package/dist/fragments/compose.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * Fragment Composition - Strategies for combining fragments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeFragments = composeFragments;
+exports.createComposer = createComposer;
+/**
+ * Compose fragments into a coherent context using the specified strategy
+ */
+function composeFragments(fragments, options) {
+    switch (options.strategy) {
+        case 'priority':
+            return composePriority(fragments, options);
+        case 'expand':
+            return composeExpand(fragments, options);
+        case 'task':
+            return composeTask(fragments, options);
+        default:
+            return composePriority(fragments, options);
+    }
+}
+/**
+ * Priority-based composition: sort by priority, limit by tokens
+ */
+function composePriority(fragments, options) {
+    // Sort by priority (highest first)
+    const sorted = [...fragments].sort((a, b) => b.meta.priority - a.meta.priority);
+    if (!options.maxTokens) {
+        return sorted;
+    }
+    // Estimate tokens and cut off
+    return limitByTokens(sorted, options.maxTokens);
+}
+/**
+ * Graph expansion: start from a seed symbol/file, expand to related fragments
+ */
+function composeExpand(fragments, options) {
+    const seed = options.seed;
+    const depth = options.depth || 2;
+    if (!seed) {
+        return composePriority(fragments, options);
+    }
+    const result = [];
+    const visited = new Set();
+    const queue = [];
+    // Find seed fragments
+    const seedFragments = fragments.filter((f) => f.refs.symbols.includes(seed) ||
+        f.refs.files.some((file) => file.includes(seed)) ||
+        f.data &&
+            typeof f.data === 'object' &&
+            'name' in f.data &&
+            f.data.name === seed);
+    for (const fragment of seedFragments) {
+        queue.push({ fragment, level: 0 });
+    }
+    while (queue.length > 0) {
+        const { fragment, level } = queue.shift();
+        if (visited.has(fragment.id))
+            continue;
+        visited.add(fragment.id);
+        result.push(fragment);
+        if (level >= depth)
+            continue;
+        // Find related fragments
+        const related = findRelatedFragments(fragment, fragments, visited);
+        for (const relFragment of related) {
+            queue.push({ fragment: relFragment, level: level + 1 });
+        }
+    }
+    // Sort by priority within result
+    result.sort((a, b) => b.meta.priority - a.meta.priority);
+    if (options.maxTokens) {
+        return limitByTokens(result, options.maxTokens);
+    }
+    return result;
+}
+/**
+ * Task-based composition: select fragments relevant to a task description
+ */
+function composeTask(fragments, options) {
+    const task = options.task;
+    if (!task) {
+        return composePriority(fragments, options);
+    }
+    // Extract keywords from task
+    const keywords = extractKeywords(task);
+    // Score fragments by relevance to task
+    const scored = fragments.map((fragment) => ({
+        fragment,
+        score: scoreRelevance(fragment, keywords),
+    }));
+    // Sort by combined score (relevance + priority)
+    scored.sort((a, b) => {
+        const aTotal = a.score * 0.7 + a.fragment.meta.priority * 0.3;
+        const bTotal = b.score * 0.7 + b.fragment.meta.priority * 0.3;
+        return bTotal - aTotal;
+    });
+    const result = scored.map((s) => s.fragment);
+    if (options.maxTokens) {
+        return limitByTokens(result, options.maxTokens);
+    }
+    return result;
+}
+/**
+ * Find fragments related to a given fragment
+ */
+function findRelatedFragments(fragment, allFragments, visited) {
+    const related = [];
+    // By referenced fragments
+    for (const refId of fragment.refs.fragments) {
+        const refFragment = allFragments.find((f) => f.id === refId && !visited.has(f.id));
+        if (refFragment) {
+            related.push(refFragment);
+        }
+    }
+    // By shared files
+    for (const file of fragment.refs.files) {
+        const fileFragments = allFragments.filter((f) => f.refs.files.includes(file) && !visited.has(f.id));
+        related.push(...fileFragments);
+    }
+    // By shared symbols
+    for (const symbol of fragment.refs.symbols) {
+        const symbolFragments = allFragments.filter((f) => (f.refs.symbols.includes(symbol) ||
+            (f.data &&
+                typeof f.data === 'object' &&
+                'name' in f.data &&
+                f.data.name === symbol)) &&
+            !visited.has(f.id));
+        related.push(...symbolFragments);
+    }
+    // Deduplicate
+    const uniqueIds = new Set();
+    return related.filter((f) => {
+        if (uniqueIds.has(f.id))
+            return false;
+        uniqueIds.add(f.id);
+        return true;
+    });
+}
+/**
+ * Extract keywords from a task description
+ */
+function extractKeywords(task) {
+    const stopWords = new Set([
+        'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+        'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+        'should', 'may', 'might', 'must', 'shall', 'can', 'need', 'to', 'of',
+        'in', 'for', 'on', 'with', 'at', 'by', 'from', 'up', 'about', 'into',
+        'through', 'during', 'before', 'after', 'above', 'below', 'between',
+        'under', 'again', 'further', 'then', 'once', 'here', 'there', 'when',
+        'where', 'why', 'how', 'all', 'each', 'few', 'more', 'most', 'other',
+        'some', 'such', 'no', 'nor', 'not', 'only', 'own', 'same', 'so', 'than',
+        'too', 'very', 'just', 'and', 'but', 'if', 'or', 'because', 'as', 'until',
+        'while', 'this', 'that', 'these', 'those', 'i', 'me', 'my', 'we', 'our',
+        'you', 'your', 'it', 'its', 'add', 'create', 'new', 'implement', 'fix',
+        'update', 'change', 'modify', 'help', 'want', 'make', 'get', 'set',
+    ]);
+    return task
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((word) => word.length > 2 && !stopWords.has(word));
+}
+/**
+ * Score a fragment's relevance to keywords
+ */
+function scoreRelevance(fragment, keywords) {
+    let score = 0;
+    const textToSearch = [
+        fragment.summary || '',
+        fragment.type,
+        ...fragment.meta.tags,
+        ...fragment.refs.symbols,
+        ...(fragment.data && typeof fragment.data === 'object'
+            ? Object.values(fragment.data)
+                .filter((v) => typeof v === 'string')
+                .map((v) => v)
+            : []),
+    ]
+        .join(' ')
+        .toLowerCase();
+    for (const keyword of keywords) {
+        if (textToSearch.includes(keyword)) {
+            score += 1;
+            // Bonus for exact symbol match
+            if (fragment.refs.symbols.some((s) => s.toLowerCase() === keyword)) {
+                score += 2;
+            }
+            // Bonus for type match
+            if (fragment.type.includes(keyword)) {
+                score += 1;
+            }
+        }
+    }
+    // Normalize by keyword count
+    return keywords.length > 0 ? score / keywords.length : 0;
+}
+/**
+ * Limit fragments by estimated token count
+ */
+function limitByTokens(fragments, maxTokens) {
+    const result = [];
+    let totalTokens = 0;
+    for (const fragment of fragments) {
+        const tokens = estimateTokens(fragment);
+        if (totalTokens + tokens > maxTokens) {
+            break;
+        }
+        result.push(fragment);
+        totalTokens += tokens;
+    }
+    return result;
+}
+/**
+ * Estimate token count for a fragment (rough approximation)
+ */
+function estimateTokens(fragment) {
+    const json = JSON.stringify(fragment);
+    // Rough estimate: ~4 chars per token
+    return Math.ceil(json.length / 4);
+}
+/**
+ * Create a composition pipeline helper
+ */
+function createComposer(store) {
+    return {
+        /**
+         * Compose by priority (default)
+         */
+        byPriority(maxTokens) {
+            return composeFragments(store.all(), {
+                strategy: 'priority',
+                maxTokens,
+            });
+        },
+        /**
+         * Compose by expanding from a seed
+         */
+        expand(seed, depth, maxTokens) {
+            return composeFragments(store.all(), {
+                strategy: 'expand',
+                seed,
+                depth,
+                maxTokens,
+            });
+        },
+        /**
+         * Compose by task relevance
+         */
+        forTask(task, maxTokens) {
+            return composeFragments(store.all(), {
+                strategy: 'task',
+                task,
+                maxTokens,
+            });
+        },
+        /**
+         * Get essential context (project overview + high priority)
+         */
+        essential(maxTokens) {
+            const essential = store
+                .all()
+                .filter((f) => f.type === 'project-overview' ||
+                f.meta.tags.includes('essential') ||
+                f.meta.priority >= 8);
+            return composeFragments(essential, {
+                strategy: 'priority',
+                maxTokens,
+            });
+        },
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/fragments/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/fragments/compose.ts"],"names":[],"mappings":"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"}