reprompt-cli 2.1.0__tar.gz → 2.2.0__tar.gz

{reprompt_cli-2.1.0 → reprompt_cli-2.2.0}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.0] - 2026-04-01
+
+### Added
+- **Prompt builder** — `reprompt build "task" --file src/auth.ts --error "TypeError" --constraint "keep tests"` assembles well-scored prompts from components. Model-aware formatting: XML tags for Claude, markdown headers for GPT. Shows score, tier, and suggestions for missing components.
+- **Unified diagnostic** — `reprompt check "prompt"` runs score + lint + rewrite in one command. Shows dimensional breakdown, strengths, suggestions with point values, lint issues, and auto-rewrite preview.
+- **Prompt explainer** — `reprompt explain "prompt"` explains what makes a prompt good or bad in plain English. Educational feedback with research-backed insights per dimension.
+- Tests: 1741 → 1846
+
 ## [2.1.0] - 2026-04-01
 
 ### Added

{reprompt_cli-2.1.0 → reprompt_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reprompt-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Discover, analyze, and optimize your prompts from AI coding sessions
 Project-URL: Homepage, https://github.com/reprompt-dev/reprompt
 Project-URL: Repository, https://github.com/reprompt-dev/reprompt
@@ -104,6 +104,7 @@ $ reprompt
 |---------|-------------|
 | `reprompt` | Instant dashboard -- prompts, sessions, avg score, top categories |
 | `reprompt scan` | Auto-discover prompts from 9 AI tools |
+| `reprompt check "prompt"` | **Full diagnostic** -- score + lint + rewrite preview in one command |
 | `reprompt score "prompt"` | Research-backed 0-100 scoring with 30+ features |
 | `reprompt compare "a" "b"` | Side-by-side prompt analysis (or `--best-worst` for auto-selection) |
 | `reprompt insights` | Personal patterns vs research-optimal benchmarks |
@@ -117,6 +118,7 @@ $ reprompt
 
 | Command | Description |
 |---------|-------------|
+| `reprompt build "task"` | **Build prompts from components** -- task, context, files, errors, constraints. Model-aware (Claude/GPT/Gemini) |
 | `reprompt rewrite "prompt"` | **Rewrite prompts to score higher** -- filler removal, restructuring, hedging cleanup |
 | `reprompt compress "prompt"` | 4-layer prompt compression (40-60% token savings typical) |
 | `reprompt distill` | Extract important turns from conversations with 6-signal scoring |
@@ -228,7 +230,7 @@ Captured prompts sync locally via Native Messaging -- nothing leaves your machin
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/reprompt-dev/reprompt
-    rev: v2.1.0
+    rev: v2.2.0
     hooks:
       - id: reprompt-lint
 ```

{reprompt_cli-2.1.0 → reprompt_cli-2.2.0}/README.md

@@ -59,6 +59,7 @@ $ reprompt
 |---------|-------------|
 | `reprompt` | Instant dashboard -- prompts, sessions, avg score, top categories |
 | `reprompt scan` | Auto-discover prompts from 9 AI tools |
+| `reprompt check "prompt"` | **Full diagnostic** -- score + lint + rewrite preview in one command |
 | `reprompt score "prompt"` | Research-backed 0-100 scoring with 30+ features |
 | `reprompt compare "a" "b"` | Side-by-side prompt analysis (or `--best-worst` for auto-selection) |
 | `reprompt insights` | Personal patterns vs research-optimal benchmarks |
@@ -72,6 +73,7 @@ $ reprompt
 
 | Command | Description |
 |---------|-------------|
+| `reprompt build "task"` | **Build prompts from components** -- task, context, files, errors, constraints. Model-aware (Claude/GPT/Gemini) |
 | `reprompt rewrite "prompt"` | **Rewrite prompts to score higher** -- filler removal, restructuring, hedging cleanup |
 | `reprompt compress "prompt"` | 4-layer prompt compression (40-60% token savings typical) |
 | `reprompt distill` | Extract important turns from conversations with 6-signal scoring |
@@ -183,7 +185,7 @@ Captured prompts sync locally via Native Messaging -- nothing leaves your machin
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/reprompt-dev/reprompt
-    rev: v2.1.0
+    rev: v2.2.0
     hooks:
       - id: reprompt-lint
 ```

{reprompt_cli-2.1.0 → reprompt_cli-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "reprompt-cli"
-version = "2.1.0"
+version = "2.2.0"
 description = "Discover, analyze, and optimize your prompts from AI coding sessions"
 readme = "README.md"
 license = { text = "MIT" }

{reprompt_cli-2.1.0 → reprompt_cli-2.2.0}/src/reprompt/cli.py

@@ -946,6 +946,111 @@ def lint(
         raise typer.Exit(1)
 
 
+@app.command(rich_help_panel="Analyze")
+def check(
+    text: str = typer.Argument(..., help="Prompt text to check"),
+    model: str = typer.Option("", "--model", "-m", help="Target model (claude/gpt/gemini)"),
+    max_tokens: int = typer.Option(0, "--max-tokens", help="Token budget (0 = disabled)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    copy: bool = typer.Option(False, "--copy", help="Copy rewritten prompt to clipboard"),
+) -> None:
+    """Full prompt diagnostic — score + lint + rewrite in one command.
+
+    Runs all quality checks and shows a unified report with score breakdown,
+    strengths, suggestions, lint issues, and auto-rewrite preview.
+
+    Examples:
+
+        reprompt check "fix the auth bug in login.ts"
+
+        reprompt check "refactor the middleware" --model claude
+
+        reprompt check "help me debug this crash" --json
+    """
+    from reprompt.core.check import check_prompt
+
+    result = check_prompt(text, model=model, max_tokens=max_tokens)
+
+    if json_output:
+        import json as json_mod
+
+        data = {
+            "total": result.total,
+            "tier": result.tier,
+            "clarity": result.clarity,
+            "context": result.context,
+            "position": result.position,
+            "structure": result.structure,
+            "repetition": result.repetition,
+            "word_count": result.word_count,
+            "token_count": result.token_count,
+            "confirmations": result.confirmations,
+            "suggestions": result.suggestions,
+            "lint_issues": result.lint_issues,
+            "rewritten": result.rewritten,
+            "rewrite_delta": result.rewrite_delta,
+            "rewrite_changes": result.rewrite_changes,
+        }
+        typer.echo(json_mod.dumps(data, indent=2, ensure_ascii=False))
+    else:
+        from reprompt.output.check_terminal import render_check
+
+        typer.echo(render_check(result))
+
+    if copy:
+        _copy_to_clip(result.rewritten, quiet=json_output)
+
+    from reprompt.core.suggestions import get_suggestion
+
+    hint = get_suggestion("check")
+    if hint and not json_output:
+        console.print(f"  [dim]→ Try: {hint}[/dim]\n")
+
+
+@app.command(rich_help_panel="Analyze")
+def explain(
+    text: str = typer.Argument(..., help="Prompt text to explain"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Explain what makes a prompt good or bad in plain English.
+
+    Analyzes the prompt and provides educational feedback: what's working,
+    what's missing, and specific tips to improve. No LLM needed.
+
+    Examples:
+
+        reprompt explain "fix the auth bug"
+
+        reprompt explain "Fix the JWT expiration in src/auth.ts line 42" --json
+    """
+    from reprompt.core.explain import explain_prompt
+
+    result = explain_prompt(text)
+
+    if json_output:
+        import json as json_mod
+
+        data = {
+            "score": result.score,
+            "tier": result.tier,
+            "summary": result.summary,
+            "strengths": result.strengths,
+            "weaknesses": result.weaknesses,
+            "tips": result.tips,
+        }
+        typer.echo(json_mod.dumps(data, indent=2, ensure_ascii=False))
+    else:
+        from reprompt.output.explain_terminal import render_explain
+
+        typer.echo(render_explain(result))
+
+    from reprompt.core.suggestions import get_suggestion
+
+    hint = get_suggestion("explain")
+    if hint and not json_output:
+        console.print(f"  [dim]→ Try: {hint}[/dim]\n")
+
+
 @app.command(rich_help_panel="Analyze")
 def score(
     text: str = typer.Argument(..., help="Prompt text to score"),
@@ -1158,6 +1263,73 @@ def rewrite(
         console.print(f"  [dim]→ Try: {hint}[/dim]\n")
 
 
+@app.command(rich_help_panel="Optimize")
+def build(
+    task: str = typer.Argument(..., help="What the AI should do"),
+    context: str = typer.Option("", "--context", "-c", help="Background information"),
+    file: list[str] = typer.Option([], "--file", "-f", help="File references (repeatable)"),
+    error: str = typer.Option("", "--error", "-e", help="Error message or stack trace"),
+    constraint: list[str] = typer.Option([], "--constraint", help="Constraints (repeatable)"),
+    example: str = typer.Option("", "--example", help="Example input/output"),
+    output_format: str = typer.Option("", "--output-format", help="Expected response format"),
+    role: str = typer.Option("", "--role", "-r", help="AI role/persona"),
+    model: str = typer.Option("", "--model", "-m", help="Target model (claude/gpt/gemini)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    copy: bool = typer.Option(False, "--copy", help="Copy built prompt to clipboard"),
+) -> None:
+    """Build a well-structured prompt from components.
+
+    Assembles a prompt that maximizes quality score by combining
+    your task with context, files, errors, and constraints.
+
+    Examples:
+
+        reprompt build "fix the auth bug"
+
+        reprompt build "fix the crash" --file src/auth.ts --error "TypeError: ..."
+
+        reprompt build "refactor" -f src/app.py --constraint "keep tests" --model claude
+    """
+    from reprompt.core.build import build_prompt
+
+    result = build_prompt(
+        task,
+        context=context,
+        files=file if file else None,
+        error=error,
+        constraints=constraint if constraint else None,
+        examples=example,
+        output_format=output_format,
+        role=role,
+        model=model,
+    )
+
+    if json_output:
+        import json as json_mod
+
+        data = {
+            "prompt": result.prompt,
+            "score": result.score,
+            "tier": result.tier,
+            "components_used": result.components_used,
+            "suggestions": result.suggestions,
+        }
+        typer.echo(json_mod.dumps(data, indent=2, ensure_ascii=False))
+    else:
+        from reprompt.output.build_terminal import render_build
+
+        typer.echo(render_build(result))
+
+    if copy:
+        _copy_to_clip(result.prompt, quiet=json_output)
+
+    from reprompt.core.suggestions import get_suggestion
+
+    hint = get_suggestion("build")
+    if hint and not json_output:
+        console.print(f"  [dim]→ Try: {hint}[/dim]\n")
+
+
 @app.command(rich_help_panel="Optimize")
 def distill(
     session_id: str = typer.Argument(None, help="Session ID to distill"),

reprompt_cli-2.2.0/src/reprompt/core/build.py

@@ -0,0 +1,246 @@
+"""Prompt builder — assemble a well-structured prompt from components.
+
+Takes a task description and optional context, files, errors, constraints,
+and examples, then assembles a prompt that maximizes the scoring dimensions.
+Scoring-aware: structures the output to hit clarity, context, and position.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BuildResult:
+    """Result of building a prompt from components."""
+
+    prompt: str
+    score: float = 0.0
+    tier: str = ""
+    components_used: list[str] = field(default_factory=list)
+    suggestions: list[str] = field(default_factory=list)
+
+
+def build_prompt(
+    task: str,
+    *,
+    context: str = "",
+    files: list[str] | None = None,
+    error: str = "",
+    constraints: list[str] | None = None,
+    examples: str = "",
+    output_format: str = "",
+    role: str = "",
+    model: str = "",
+) -> BuildResult:
+    """Build a well-structured prompt from components.
+
+    Returns the assembled prompt with its score and suggestions
+    for components the user could still add.
+    """
+    parts: list[str] = []
+    components: list[str] = []
+
+    # Role (if provided) — goes first
+    if role:
+        parts.append(f"You are {role}.")
+        components.append("role")
+
+    # Task — always present, imperative form, at the front (position bias)
+    task_text = _ensure_imperative(task.strip())
+    if task_text and task_text[-1] not in ".!?":
+        task_text += "."
+    parts.append(task_text)
+    components.append("task")
+
+    # File references — high context value
+    if files:
+        if len(files) == 1:
+            parts.append(f"File: {files[0]}")
+        else:
+            file_list = ", ".join(files)
+            parts.append(f"Files: {file_list}")
+        components.append("files")
+
+    # Error context — critical for debug prompts
+    if error:
+        parts.append(f"Error: {error}")
+        components.append("error")
+
+    # Context — background information
+    if context:
+        parts.append(f"Context: {context}")
+        components.append("context")
+
+    # Examples
+    if examples:
+        parts.append(f"Example:\n{examples}")
+        components.append("examples")
+
+    # Constraints
+    if constraints:
+        if len(constraints) == 1:
+            parts.append(f"Constraint: {constraints[0]}")
+        else:
+            constraint_lines = "\n".join(f"- {c}" for c in constraints)
+            parts.append(f"Constraints:\n{constraint_lines}")
+        components.append("constraints")
+
+    # Output format
+    if output_format:
+        parts.append(f"Output format: {output_format}")
+        components.append("output_format")
+
+    # Model-specific formatting
+    prompt = _format_for_model(parts, model)
+
+    # Score the assembled prompt
+    from reprompt.core.extractors import extract_features
+    from reprompt.core.scorer import score_prompt
+
+    dna = extract_features(prompt, source="build", session_id="")
+    score_result = score_prompt(dna)
+
+    # Determine tier
+    tier = _get_tier(score_result.total)
+
+    # Generate suggestions for missing components
+    suggestions = _missing_suggestions(components)
+
+    return BuildResult(
+        prompt=prompt,
+        score=score_result.total,
+        tier=tier,
+        components_used=components,
+        suggestions=suggestions,
+    )
+
+
+def _ensure_imperative(task: str) -> str:
+    """Strip filler prefixes to get an imperative task statement."""
+    import re
+
+    # Remove common polite/filler prefixes
+    cleaned = re.sub(
+        r"^(?:please\s+|can you\s+|could you\s+|i need you to\s+|"
+        r"i want you to\s+|i would like you to\s+|help me\s+|"
+        r"i was wondering if you could\s+)",
+        "",
+        task,
+        flags=re.IGNORECASE,
+    )
+    # Capitalize first letter
+    if cleaned:
+        cleaned = cleaned[0].upper() + cleaned[1:]
+    return cleaned
+
+
+def _format_for_model(parts: list[str], model: str) -> str:
+    """Format prompt parts with model-appropriate structure."""
+    if model == "claude":
+        return _format_xml(parts)
+    elif model == "gpt":
+        return _format_markdown(parts)
+    else:
+        # Default: clean plain text with double newlines
+        return "\n\n".join(parts)
+
+
+def _format_xml(parts: list[str]) -> str:
+    """Format with XML tags (preferred by Claude)."""
+    if len(parts) <= 2:
+        # Short prompts don't need XML
+        return "\n\n".join(parts)
+
+    sections: list[str] = []
+    for part in parts:
+        lower = part.lower()
+        if lower.startswith("you are "):
+            sections.append(part)
+        elif lower.startswith("context:"):
+            content = part[len("Context:") :].strip()
+            sections.append(f"<context>\n{content}\n</context>")
+        elif lower.startswith("error:"):
+            content = part[len("Error:") :].strip()
+            sections.append(f"<context>\n{content}\n</context>")
+        elif lower.startswith("constraint"):
+            content = part.split(":", 1)[1].strip() if ":" in part else part
+            sections.append(f"<constraints>\n{content}\n</constraints>")
+        elif lower.startswith("example"):
+            content = part.split(":", 1)[1].strip() if ":" in part else part
+            content = part.split("\n", 1)[1].strip() if "\n" in part else content
+            sections.append(f"<examples>\n{content}\n</examples>")
+        elif lower.startswith("output format:"):
+            content = part[len("Output format:") :].strip()
+            sections.append(f"<output>\n{content}\n</output>")
+        else:
+            sections.append(part)
+
+    return "\n\n".join(sections)
+
+
+def _format_markdown(parts: list[str]) -> str:
+    """Format with markdown headers (preferred by GPT)."""
+    if len(parts) <= 2:
+        return "\n\n".join(parts)
+
+    sections: list[str] = []
+    for part in parts:
+        lower = part.lower()
+        if lower.startswith("you are "):
+            sections.append(part)
+        elif lower.startswith("context:"):
+            content = part[len("Context:") :].strip()
+            sections.append(f"## Context\n{content}")
+        elif lower.startswith("error:"):
+            content = part[len("Error:") :].strip()
+            sections.append(f"## Error\n{content}")
+        elif lower.startswith("constraint"):
+            content = part.split(":", 1)[1].strip() if ":" in part else part
+            sections.append(f"## Constraints\n{content}")
+        elif lower.startswith("example"):
+            content = part.split(":", 1)[1].strip() if ":" in part else part
+            content = part.split("\n", 1)[1].strip() if "\n" in part else content
+            sections.append(f"## Examples\n{content}")
+        elif lower.startswith("output format:"):
+            content = part[len("Output format:") :].strip()
+            sections.append(f"## Output Format\n{content}")
+        else:
+            sections.append(part)
+
+    return "\n\n".join(sections)
+
+
+def _get_tier(score: float) -> str:
+    """Map score to tier label."""
+    if score >= 85:
+        return "EXPERT"
+    if score >= 70:
+        return "STRONG"
+    if score >= 50:
+        return "GOOD"
+    if score >= 30:
+        return "BASIC"
+    return "DRAFT"
+
+
+def _missing_suggestions(components: list[str]) -> list[str]:
+    """Suggest components the user could add to improve the prompt."""
+    suggestions: list[str] = []
+
+    if "files" not in components:
+        suggestions.append("Add --file to reference specific files (+6 pts)")
+    if "error" not in components:
+        suggestions.append("Add --error with the actual error message (+6 pts)")
+    if "constraints" not in components:
+        suggestions.append("Add --constraint to set boundaries (+5 pts)")
+    if "context" not in components:
+        suggestions.append("Add --context for background information (+4 pts)")
+    if "examples" not in components:
+        suggestions.append("Add --example with expected input/output (+3 pts)")
+    if "role" not in components:
+        suggestions.append("Add --role to set the AI's perspective (+3 pts)")
+    if "output_format" not in components:
+        suggestions.append("Add --output-format to specify response structure (+2 pts)")
+
+    return suggestions

reprompt_cli-2.2.0/src/reprompt/core/check.py

@@ -0,0 +1,115 @@
+"""Unified prompt diagnostic — score + lint + rewrite in one pass.
+
+Single-command quality check that runs all engines and returns a combined result.
+Designed as the "one command" onboarding experience.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CheckResult:
+    """Combined result from all quality engines."""
+
+    # Score
+    total: float = 0.0
+    tier: str = ""
+    clarity: float = 0.0
+    context: float = 0.0
+    position: float = 0.0
+    structure: float = 0.0
+    repetition: float = 0.0
+
+    # Strengths
+    confirmations: list[dict] = field(default_factory=list)
+
+    # Suggestions with points
+    suggestions: list[dict] = field(default_factory=list)
+
+    # Lint violations
+    lint_issues: list[dict] = field(default_factory=list)
+
+    # Rewrite
+    rewritten: str = ""
+    rewrite_delta: float = 0.0
+    rewrite_changes: list[str] = field(default_factory=list)
+
+    # Meta
+    word_count: int = 0
+    token_count: int = 0
+
+
+def check_prompt(
+    text: str,
+    *,
+    model: str = "",
+    max_tokens: int = 0,
+) -> CheckResult:
+    """Run all quality checks on a prompt in one pass."""
+    from reprompt.core.extractors import extract_features
+    from reprompt.core.lint import LintConfig, lint_prompt
+    from reprompt.core.rewrite import rewrite_prompt
+    from reprompt.core.scorer import score_prompt
+
+    # 1. Score
+    dna = extract_features(text, source="check", session_id="")
+    breakdown = score_prompt(dna)
+
+    # 2. Lint
+    lint_config = LintConfig()
+    if model and model in ("claude", "gpt", "gemini"):
+        lint_config.model = model
+    if max_tokens > 0:
+        lint_config.max_tokens = max_tokens
+    violations = lint_prompt(text, lint_config)
+
+    # 3. Rewrite
+    rewrite_result = rewrite_prompt(text)
+
+    # Build result
+    tier = _get_tier(breakdown.total)
+
+    return CheckResult(
+        total=breakdown.total,
+        tier=tier,
+        clarity=breakdown.clarity,
+        context=breakdown.context,
+        position=breakdown.position,
+        structure=breakdown.structure,
+        repetition=breakdown.repetition,
+        confirmations=[
+            {"category": c.category, "message": c.message, "score": c.score}
+            for c in breakdown.confirmations
+        ],
+        suggestions=[
+            {
+                "category": s.category,
+                "message": s.message,
+                "impact": s.impact,
+                "points": s.points,
+            }
+            for s in breakdown.suggestions
+        ],
+        lint_issues=[
+            {"rule": v.rule, "severity": v.severity, "message": v.message} for v in violations
+        ],
+        rewritten=rewrite_result.rewritten,
+        rewrite_delta=rewrite_result.score_delta,
+        rewrite_changes=rewrite_result.changes,
+        word_count=dna.word_count,
+        token_count=dna.token_count,
+    )
+
+
+def _get_tier(score: float) -> str:
+    if score >= 85:
+        return "EXPERT"
+    if score >= 70:
+        return "STRONG"
+    if score >= 50:
+        return "GOOD"
+    if score >= 30:
+        return "BASIC"
+    return "DRAFT"