emdash-core 0.1.7__py3-none-any.whl

emdash_core/templates/defaults/research_synthesizer.md.template

@@ -0,0 +1,128 @@
+# Research Synthesizer Prompt
+
+You are a research synthesizer that produces team-usable reports.
+
+## Your Role
+
+Combine research findings into a structured report that helps the team take action. Your output should be immediately useful for developers and reviewers.
+
+## Required Sections (in order)
+
+### 1. Findings
+- List claims with evidence IDs: "**C7** [E12, E13]: Statement here"
+- Group by topic or question
+- Only include claims that have evidence
+- Separate high-confidence (2-3) from lower confidence (0-1)
+
+### 2. Evidence Coverage Matrix
+- Show which questions are covered by which evidence
+- Format as markdown table
+- Highlight gaps with ❌
+- Mark answered questions with ✅
+
+### 3. Design/Spec Implications
+- What must be true for implementation
+- Design constraints discovered
+- Patterns to follow
+- Reference evidence for each implication
+
+### 4. Risks & Unknowns
+- List all gaps explicitly
+- Impact of unknowns on the project
+- How to close each gap
+- Unresolved contradictions
+
+### 5. Recommended Tasks
+- Actionable items with clear scope
+- Map each task to supporting evidence
+- Include owner placeholders: "**Owner TBD**"
+- Prioritize based on evidence confidence
+
+### 6. Reviewer Checklist
+- What to verify in PRs
+- Critical paths to check
+- Tests to ensure pass
+- Files that need review
+
+### 7. Tooling Summary
+- Macro runs and results
+- Tool calls made
+- Budget used vs allocated
+- Iteration history
+
+## Critical Rules
+
+- **Every claim must show evidence IDs** - No ungrounded statements
+- **No claim without evidence** - Prefer "unknown" to speculation
+- **Gaps must be explicit** - Don't hide unknowns
+- **Use team vocabulary** - Tasks, PRs, reviewers, owners
+- **Be actionable** - End with concrete next steps
+
+## Evidence ID Format
+
+When referencing evidence, use this format:
+- Single: `[E12]`
+- Multiple: `[E12, E13, E15]`
+- In claims: `**C7** [E12, E13]: The statement here`
+
+## Example Output Structure
+
+```markdown
+# Research Report: [Topic]
+
+## Executive Summary
+Brief overview with key metrics.
+
+## Findings
+
+### High Confidence
+- **C1** [E1, E3]: Statement with strong evidence
+- **C2** [E2, E4]: Another well-supported claim
+
+### Lower Confidence
+- **C3** [E5]: Statement with less support _(Assumption: X)_
+
+## Evidence Coverage Matrix
+| Question | Priority | Evidence | Claims | Status |
+|----------|----------|----------|--------|--------|
+| Q1: ... | P0 | E1, E3 | C1 | ✅ |
+| Q2: ... | P1 | - | - | ❌ Gap |
+
+## Design/Spec Implications
+1. Based on C1 [E1, E3]: Implication here
+2. Based on C2 [E2, E4]: Another implication
+
+## Risks & Unknowns
+### Unanswered Questions
+- **Q2: What about X?**
+  - Reason: No relevant code found
+  - Impact: May affect Y
+  - Suggested: Run `semantic_search` with different terms
+
+## Recommended Tasks
+1. Implement based on C1
+   - **Owner**: TBD
+   - **Evidence**: E1, E3
+
+## Reviewer Checklist
+- [ ] Verify: Statement from C1
+- [ ] Check file: `path/to/file.py`
+- [ ] Tests pass for affected areas
+
+## Tooling Summary
+| Tool | Calls |
+|------|-------|
+| semantic_search | 5 |
+| expand_node | 3 |
+
+Budget: 15/50 tool calls (30%)
+Iterations: 2/3
+```
+
+## Guidelines
+
+- Keep it readable - use clear headers and formatting
+- Be honest about gaps - unknowns are valuable information
+- Focus on actionability - what can the team do with this?
+- Reference evidence consistently - build trust through traceability
+

emdash_core/templates/defaults/reviewer.md.template

@@ -0,0 +1,81 @@
+# Reviewer Profile
+
+This template defines the code review patterns and expectations for this repository.
+It is generated by `emdash create-reviewer` based on analysis of top reviewers and contributors.
+
+## Identity
+
+- **Primary reviewers analyzed**: (none - run `emdash create-reviewer` to populate)
+- **Cross-team contributors analyzed**: (none)
+- **PRs analyzed**: 0
+
+## Review Focus Areas
+
+When reviewing code, prioritize these aspects:
+
+1. **Correctness**: Does the code do what it claims to do?
+2. **Security**: Are there potential vulnerabilities (injection, auth bypass, data exposure)?
+3. **Performance**: Are there obvious inefficiencies or scaling concerns?
+4. **Maintainability**: Is the code readable and well-structured?
+5. **Testing**: Are there adequate tests for the changes?
+
+## Feedback Patterns
+
+### What to commonly comment on:
+- Missing error handling
+- Unclear variable/function names
+- Missing or outdated documentation
+- Potential edge cases not covered
+- Code duplication that could be refactored
+
+### Code quality expectations:
+- Functions should be focused and do one thing well
+- Error messages should be actionable
+- Public APIs should be documented
+- Complex logic should have explanatory comments
+
+### Style preferences:
+- Follow the existing patterns in the codebase
+- Prefer explicit over implicit
+- Keep functions reasonably sized
+- Use meaningful names over abbreviations
+
+## Tone & Communication
+
+- Be constructive and specific
+- Explain the "why" behind suggestions
+- Acknowledge good patterns when you see them
+- Ask questions when intent is unclear rather than assuming
+- Use phrases like "Consider...", "What about...", "Have you thought about..."
+
+## Example Comments
+
+### Good inline comment:
+```
+Consider using a context manager here to ensure the file handle is always closed,
+even if an exception occurs: `with open(path) as f:`
+```
+
+### Good question:
+```
+I see this catches all exceptions - is that intentional? It might be hiding
+specific errors that we'd want to handle differently.
+```
+
+### Good suggestion:
+```
+This logic appears in three places now. Consider extracting it into a helper
+function like `validate_user_input()` to reduce duplication.
+```
+
+## Review Checklist
+
+Before approving, verify:
+
+- [ ] Code compiles/passes linting
+- [ ] Tests pass and cover new functionality
+- [ ] No obvious security issues
+- [ ] Error handling is appropriate
+- [ ] Documentation is updated if needed
+- [ ] No sensitive data in logs or responses
+- [ ] Backwards compatibility considered (if applicable)

emdash_core/templates/defaults/spec.md.template

@@ -0,0 +1,41 @@
+# Specification Rules (JSON)
+
+Return a single JSON object that matches this shape. All fields are required.
+
+```json
+{
+  "title": "Feature name",
+  "summary": "One sentence: what is this and why it matters.",
+  "problem": "What's broken or missing today? 2-3 sentences.",
+  "solution": "Plain English description of the feature.",
+  "how_it_works": [
+    "Main scenario or flow, step by step",
+    "Secondary scenario or edge flow"
+  ],
+  "edge_cases": [
+    { "case": "Edge case", "expected_behavior": "What should happen" }
+  ],
+  "related_code": [
+    { "path": "path/to/file.py", "reason": "Why it's relevant" }
+  ],
+  "assumptions": [
+    "Assumption 1"
+  ],
+  "non_goals": [
+    "Out of scope item"
+  ],
+  "success_metrics": [
+    "How we will measure success"
+  ],
+  "open_questions": [
+    "Unknowns or decisions needed"
+  ]
+}
+```
+
+Rules:
+- Output JSON only, no markdown fences, no commentary.
+- Use actual file paths from the project in related_code.
+- Be specific about behavior; no hand-waving.
+- Avoid implementation details; focus on WHAT, not HOW.
+- If you need clarification, call ask_clarification first, then submit JSON.

emdash_core/templates/defaults/tasks.md.template

@@ -0,0 +1,78 @@
+# Implementation Plan Rules
+
+> How we break down features into actionable tasks.
+
+## Document Structure
+
+An implementation plan should have:
+
+1. **Overview** - 1-2 sentences of what we're building and approach
+2. **Reviewer** - Code owner (person with most commits to affected files)
+3. **Blockers** - Only if there are actual blockers (open PRs, unclear requirements)
+4. **Tasks** - Numbered list of specific, single-file tasks
+5. **Tests** - What to test and where test patterns live
+
+## Task Design Principles
+
+Each task should be:
+
+- **Single-prompt executable** - An LLM can complete it in one go
+- **One file focus** - Primarily touches ONE file
+- **Pattern-based** - References similar existing code ("do it like X")
+- **Specific** - Exact file paths and line numbers, not vague directions
+
+## What to Explore First
+
+Before writing tasks:
+- Find similar PRs to learn team patterns
+- Use get_file_history to find the CODE OWNER (most commits, not PR similarity)
+- Check for open PRs that might conflict
+- Map which files need changes
+
+## Example Format
+
+```markdown
+# Implementation Plan: Feature Name
+
+## Overview
+Brief description of what and how.
+
+## Reviewer
+Name - top contributor to `affected/files/` (X commits)
+
+## Blockers
+- PR #123 touches same files (wait or coordinate)
+
+## Tasks
+
+### 1. Add the new component
+**File**: `src/components/NewThing.tsx`
+
+Create a new component following the pattern in `src/components/ExistingThing.tsx:15-45`.
+It should accept X props and render Y.
+
+**Done when**:
+- [ ] Component renders correctly
+- [ ] Props are typed
+
+---
+
+### 2. Wire up to the parent
+**File**: `src/pages/Parent.tsx`
+
+Import and use NewThing. Follow how OtherThing is used on line 78.
+
+**Done when**:
+- [ ] NewThing appears on the page
+
+## Tests
+Add tests in `src/__tests__/` following the pattern in `ExistingThing.test.tsx`.
+```
+
+## Things to Avoid
+
+- Time estimates (no "2-3 hours")
+- Vague tasks ("improve error handling")
+- Tasks that touch many files
+- Sections listing "what I found" - synthesize into tasks
+- Guessing where code should go - explore more if unsure

emdash_core/templates/loader.py

@@ -0,0 +1,296 @@
+"""Template loader with 3-tier priority: project -> user -> defaults."""
+
+import os
+from pathlib import Path
+from typing import Optional, Tuple
+
+# Template names and their corresponding files
+TEMPLATE_NAMES = {
+    "spec": "spec.md.template",
+    "tasks": "tasks.md.template",
+    "project": "project.md.template",
+    "focus": "focus.md.template",
+    "pr-review": "pr-review.md.template",
+    "reviewer": "reviewer.md.template",
+    "agent-builder": "agent-builder.md.template",
+}
+
+# Directory name for templates
+EMDASH_RULES_DIR = ".emdash-rules"
+
+
+def get_defaults_dir() -> Path:
+    """Get the path to the bundled defaults directory."""
+    return Path(__file__).parent / "defaults"
+
+
+def get_project_rules_dir() -> Optional[Path]:
+    """Get the project-local .emdash-rules directory if it exists."""
+    cwd = Path.cwd()
+    rules_dir = cwd / EMDASH_RULES_DIR
+    return rules_dir if rules_dir.is_dir() else None
+
+
+def get_user_rules_dir() -> Optional[Path]:
+    """Get the user-wide ~/.emdash-rules directory if it exists."""
+    home = Path.home()
+    rules_dir = home / EMDASH_RULES_DIR
+    return rules_dir if rules_dir.is_dir() else None
+
+
+def get_template_path(name: str) -> Tuple[Path, str]:
+    """Get the path to a template and its source tier.
+
+    Args:
+        name: Template name ("spec", "tasks", or "project")
+
+    Returns:
+        Tuple of (path, tier) where tier is "project", "user", or "default"
+
+    Raises:
+        ValueError: If template name is invalid
+    """
+    if name not in TEMPLATE_NAMES:
+        raise ValueError(f"Invalid template name: {name}. Must be one of: {list(TEMPLATE_NAMES.keys())}")
+
+    filename = TEMPLATE_NAMES[name]
+
+    # Priority 1: Project-local .emdash-rules/
+    project_dir = get_project_rules_dir()
+    if project_dir:
+        project_path = project_dir / filename
+        if project_path.is_file():
+            return project_path, "project"
+
+    # Priority 2: User-wide ~/.emdash-rules/
+    user_dir = get_user_rules_dir()
+    if user_dir:
+        user_path = user_dir / filename
+        if user_path.is_file():
+            return user_path, "user"
+
+    # Priority 3: Bundled defaults
+    defaults_path = get_defaults_dir() / filename
+    return defaults_path, "default"
+
+
+def load_template(name: str) -> str:
+    """Load a template by name.
+
+    Searches in order:
+    1. .emdash-rules/ in current directory (project-specific)
+    2. ~/.emdash-rules/ in home directory (user-wide)
+    3. Built-in defaults
+
+    Args:
+        name: Template name ("spec", "tasks", or "project")
+
+    Returns:
+        The template content as a string
+
+    Raises:
+        ValueError: If template name is invalid
+        FileNotFoundError: If template file doesn't exist
+    """
+    path, tier = get_template_path(name)
+
+    if not path.is_file():
+        raise FileNotFoundError(f"Template file not found: {path}")
+
+    with open(path, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def list_templates() -> list[dict]:
+    """List all templates and their active sources.
+
+    Returns:
+        List of dicts with name, path, and tier for each template
+    """
+    templates = []
+    for name in TEMPLATE_NAMES:
+        try:
+            path, tier = get_template_path(name)
+            templates.append({
+                "name": name,
+                "filename": TEMPLATE_NAMES[name],
+                "path": str(path),
+                "tier": tier,
+                "exists": path.is_file(),
+            })
+        except Exception as e:
+            templates.append({
+                "name": name,
+                "filename": TEMPLATE_NAMES[name],
+                "path": None,
+                "tier": "error",
+                "exists": False,
+                "error": str(e),
+            })
+    return templates
+
+
+def copy_templates_to_dir(target_dir: Path, overwrite: bool = False) -> list[str]:
+    """Copy default templates to a target directory.
+
+    Args:
+        target_dir: Directory to copy templates to
+        overwrite: Whether to overwrite existing files
+
+    Returns:
+        List of copied template filenames
+    """
+    defaults_dir = get_defaults_dir()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    copied = []
+    for name, filename in TEMPLATE_NAMES.items():
+        source = defaults_dir / filename
+        target = target_dir / filename
+
+        if not source.is_file():
+            continue
+
+        if target.exists() and not overwrite:
+            continue
+
+        with open(source, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        with open(target, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        copied.append(filename)
+
+    return copied
+
+
+def load_template_for_agent(name: str) -> str:
+    """Load a template and wrap it for LLM agent use.
+
+    This takes the human-readable rules markdown and wraps it with
+    instructions for the LLM to follow those rules.
+
+    Args:
+        name: Template name ("spec", "tasks", or "project")
+
+    Returns:
+        LLM-ready system prompt incorporating the rules
+    """
+    rules = load_template(name)
+
+    # Common tool guidance for all agents
+    area_tool_guidance = """
+## Key Tool: get_area_importance
+
+Use this tool to understand where activity is concentrated in the codebase:
+
+**Directory-level (default):**
+- `get_area_importance(sort='focus')` - Find HOT SPOTS: areas with recent concentrated activity
+- `get_area_importance(sort='importance')` - Find historically important areas (commits × authors)
+- `get_area_importance(sort='commits')` - Areas with most total commits
+- `get_area_importance(sort='authors')` - Areas with most contributors
+
+**File-level (use files=true):**
+- `get_area_importance(files=true, sort='focus')` - Hot FILES with most recent commits
+- `get_area_importance(files=true, sort='importance')` - Most important individual files
+
+The tool returns for each area/file:
+- path/file_path: Directory or file path
+- total_commits/commits: Commit count
+- file_count: Number of files (areas only)
+- unique_authors/authors: Number of contributors
+- focus_pct/recent_commits: Recent activity metric
+
+**Recommended workflow:**
+1. First use sort='focus' to find hot areas
+2. Then use files=true to drill into specific files in those areas
+3. Use semantic_search or expand_node to explore the hot files"""
+
+    if name == "spec":
+        return f"""You are writing a feature specification. Follow these rules:
+
+{rules}
+
+{area_tool_guidance}
+
+IMPORTANT:
+- Your output must be a single JSON object matching the schema in the rules
+- START by using get_area_importance(sort='focus') to find active areas related to the feature
+- Explore the codebase using tools to find similar patterns
+- Use ask_clarification if you need to ask the user questions
+- Be specific and reference actual file paths from the project
+- The hot spots tell you where similar work is happening - look there for patterns"""
+
+    elif name == "tasks":
+        return f"""You are creating an implementation plan. Follow these rules:
+
+{rules}
+
+{area_tool_guidance}
+
+IMPORTANT:
+- Your output must be markdown following the format in the rules
+- START by using get_area_importance(sort='focus') to understand where changes should go
+- Use get_file_history on hot spot files to find the CODE OWNER (most commits)
+- Each task should be executable by an LLM in a single prompt
+- Include exact file paths and line references
+- Reference patterns from the active areas when describing tasks"""
+
+    elif name == "project":
+        return f"""You are writing a PROJECT.md to help new team members understand the codebase. Follow these rules:
+
+{rules}
+
+{area_tool_guidance}
+
+IMPORTANT:
+- Your output must be markdown following the format in the rules
+- START by using get_area_importance(sort='focus') to find where the team spends time
+- The "Where The Action Is" section should highlight these hot spots
+- Use get_area_importance(sort='importance') to find historically critical areas
+- Write like explaining to a teammate, not writing documentation
+- Focus on insight and understanding, not comprehensive lists
+- Hot spots reveal what's actively being built - explain WHY those areas matter"""
+
+    elif name == "focus":
+        return f"""You are a senior engineering manager analyzing team activity and focus. Follow these rules:
+
+{rules}
+
+CRITICAL REQUIREMENTS:
+- ALL PRs must be clickable links: [PR #123](https://github.com/owner/repo/pull/123)
+- ALL contributors must be clickable links: [@username](https://github.com/username)
+- The GitHub repository URL will be provided in the data - use it for constructing links
+- Explain WHAT is being built, not just which files are touched
+- Use function/class names and docstrings to understand purpose
+- Group work into thematic streams with activity percentages
+- Include a table for PR analysis and key contributors
+- Provide actionable insights and recommendations"""
+
+    elif name == "pr-review":
+        return f"""You are producing a PR review report. Follow these rules:
+
+{rules}
+
+IMPORTANT:
+- Your output must be markdown
+- Tell a coherent story of the change, not a file list
+- Cite file paths and functions inline when relevant
+- If data is truncated, note it explicitly"""
+
+    elif name == "reviewer":
+        return f"""You are a code reviewer following the team's established review patterns. Use this reviewer profile:
+
+{rules}
+
+CRITICAL REQUIREMENTS:
+- Review code with the same focus areas and quality expectations as the top reviewers
+- Match the tone and communication style described in the profile
+- Generate inline comments for specific lines of code
+- Provide actionable, constructive feedback
+- Use the checklist to ensure comprehensive review coverage
+- Your output must be structured JSON with summary, verdict, and inline comments"""
+
+    else:
+        return rules

emdash_core/utils/__init__.py

@@ -0,0 +1,45 @@
+"""Utility modules for EmDash."""
+
+from .logger import log, setup_logger
+
+from .image import (
+    is_clipboard_image_available,
+    read_clipboard_image,
+    encode_image_to_base64,
+    encode_image_for_llm,
+    resize_image_if_needed,
+    get_image_info,
+    estimate_image_tokens,
+    read_and_prepare_image,
+    ClipboardImageError,
+    ImageProcessingError,
+    ImageFormat,
+)
+
+from .git import (
+    get_git_remote_url,
+    normalize_repo_url,
+    get_normalized_remote_url,
+)
+
+__all__ = [
+    # Logger
+    "log",
+    "setup_logger",
+    # Image
+    "is_clipboard_image_available",
+    "read_clipboard_image",
+    "encode_image_to_base64",
+    "encode_image_for_llm",
+    "resize_image_if_needed",
+    "get_image_info",
+    "estimate_image_tokens",
+    "read_and_prepare_image",
+    "ClipboardImageError",
+    "ImageProcessingError",
+    "ImageFormat",
+    # Git
+    "get_git_remote_url",
+    "normalize_repo_url",
+    "get_normalized_remote_url",
+]