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

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

@@ -2,6 +2,29 @@
 
 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
+- **Model-specific lint rules** — `reprompt lint --model claude/gpt/gemini` checks prompts against model-specific best practices. 8 rules: XML tag preference (Claude), markdown structure (GPT), JSON instruction requirements (GPT), CoT anti-pattern for o-series (GPT), prompt length limits (Gemini), broad negative detection (Gemini). Based on official model documentation.
+- **Diff preview for rewrite** — `reprompt rewrite --diff` shows a git-style unified diff between original and rewritten prompt. Color-coded: red removals, green additions, cyan range markers.
+- **Token budget lint** — `reprompt lint --max-tokens 4096` warns when prompts exceed a token budget. Configurable via `.reprompt.toml` (`max-tokens`) or CLI flag. Uses locale-aware token estimation from cost module.
+- Tests: 1716 → 1741
+
+## [2.0.2] - 2026-04-01
+
+### Changed
+- **Scoring rebalance** — Structure weight reduced 25→15, Clarity increased 15→25. Plain-text prompts now score 55-65 instead of 35-45. Real-world conversational prompts are no longer penalized for lacking markdown structure.
+- **Tier labels** — Scores display as EXPERT (85+), STRONG (70+), GOOD (50+), BASIC (30+), DRAFT (<30) instead of raw numbers. Applied across CLI, extension badge, popup, and HTML dashboard.
+- **Positive UX feedback** — Score output now includes "Strengths" section showing what the prompt does well. Suggestions show expected point gain (`+N pts`). Badge color thresholds adjusted: 85/60/40/25.
+
 ## [2.0.1] - 2026-03-31
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reprompt-cli
-Version: 2.0.2
+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.0.1
+    rev: v2.2.0
     hooks:
       - id: reprompt-lint
 ```

{reprompt_cli-2.0.2 → 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.0.1
+    rev: v2.2.0
     hooks:
       - id: reprompt-lint
 ```

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

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

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

@@ -797,6 +797,12 @@ def lint(
     score_threshold: int = typer.Option(
         0, "--score-threshold", help="Fail if avg prompt score < threshold (CI mode)"
     ),
+    model: str = typer.Option(
+        None, "--model", "-m", help="Target model for model-specific rules (claude/gpt/gemini)"
+    ),
+    max_tokens: int = typer.Option(
+        0, "--max-tokens", help="Warn when prompts exceed token budget (0 = disabled)"
+    ),
     copy: bool = typer.Option(False, "--copy", help="Copy result to clipboard"),
 ) -> None:
     """Check prompt quality against lint rules.
@@ -806,6 +812,12 @@ def lint(
     - short-prompt: prompts under 40 chars (warning)
     - vague-prompt: overly vague prompts like "fix it"
     - debug-needs-reference: debug prompts without file/function references
+    - max-tokens: prompt exceeds token budget
+
+    Model-specific rules (--model):
+    - claude: suggests XML tags for structure
+    - gpt: warns on XML tags (may echo verbatim), prefers markdown
+    - gemini: warns on very long prompts
 
     CI mode: use --score-threshold to fail if average score is below a threshold.
 
@@ -813,6 +825,8 @@ def lint(
 
         reprompt lint                                    # lint stored prompts
 
+        reprompt lint --model claude                     # with Claude-specific hints
+
         reprompt lint --score-threshold 50               # fail if avg score < 50 (CI mode)
 
         reprompt lint --strict --json                    # strict mode with JSON output
@@ -832,6 +846,10 @@ def lint(
 
     # CLI flags override config file
     effective_threshold = score_threshold if score_threshold > 0 else lint_config.score_threshold
+    if model:
+        lint_config.model = model.lower()
+    if max_tokens > 0:
+        lint_config.max_tokens = max_tokens
 
     # Collect prompts from DB (already scanned)
     rows = db.get_all_prompts()
@@ -928,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"),
@@ -1087,6 +1210,7 @@ def compress(
 def rewrite(
     text: str = typer.Argument(..., help="Prompt text to improve"),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    diff: bool = typer.Option(False, "--diff", help="Show unified diff (red/green)"),
     copy: bool = typer.Option(False, "--copy", help="Copy rewritten text to clipboard"),
 ) -> None:
     """Rewrite a prompt to improve its score. Rule-based, no LLM needed.
@@ -1099,9 +1223,9 @@ def rewrite(
 
         reprompt rewrite "I was wondering if you could fix the authentication bug"
 
-        reprompt rewrite "please help me refactor this code to be better" --copy
+        reprompt rewrite "fix the login" --diff
 
-        reprompt rewrite "fix the login" --json
+        reprompt rewrite "please help me refactor this code to be better" --copy
     """
     from reprompt.core.rewrite import rewrite_prompt
 
@@ -1120,6 +1244,10 @@ def rewrite(
             "manual_suggestions": result.manual_suggestions,
         }
         typer.echo(json_mod.dumps(data, indent=2, ensure_ascii=False))
+    elif diff:
+        from reprompt.output.rewrite_terminal import render_rewrite_diff
+
+        typer.echo(render_rewrite_diff(result))
     else:
         from reprompt.output.rewrite_terminal import render_rewrite
 
@@ -1135,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"),
@@ -2042,6 +2237,13 @@ def init(
 # Useful for CI: reprompt lint --score-threshold reads this value
 # score-threshold = 50
 
+# Target model for model-specific rules (claude, gpt, gemini)
+# Enables rules like "prefer XML tags" (Claude) or "avoid XML tags" (GPT)
+# model = "claude"
+
+# Token budget — warn when prompts exceed this limit (0 = disabled)
+# max-tokens = 4096
+
 [lint.rules]
 # min-length: error if prompt < N chars (0 = disabled)
 min-length = 20

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