promptmint 0.1.0__py3-none-any.whl

promptmint/__init__.py

@@ -0,0 +1,3 @@
+"""PromptMint: turn a codebase into an AI-ready prompt."""
+
+__version__ = "0.1.0"

promptmint/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .renderer import MODE_REQUESTS, render_context_pack
+from .scanner import scan_project
+from .tokens import estimate_tokens
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="promptmint",
+        description="Turn any codebase into an AI-ready Markdown prompt pack.",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="Project directory to scan")
+    parser.add_argument("-g", "--goal", default=None, help="Task goal to include in the prompt")
+    parser.add_argument("-m", "--mode", choices=sorted(MODE_REQUESTS), default="debug", help="Prompt mode")
+    parser.add_argument("-e", "--error", dest="error_file", help="Path to an error log to include")
+    parser.add_argument("-i", "--include", action="append", default=[], help="Glob to include; can be repeated")
+    parser.add_argument("-x", "--exclude", action="append", default=[], help="Glob to exclude; can be repeated")
+    parser.add_argument("-o", "--output", default="promptmint-output.md", help="Output Markdown file")
+    parser.add_argument("-c", "--copy", action="store_true", help="Copy output to clipboard if a clipboard tool is available")
+    parser.add_argument("-s", "--max-file-bytes", type=int, default=50_000, help="Skip files larger than this size")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    root = Path(args.path).resolve()
+    error_log = None
+    if args.error_file:
+        error_log = Path(args.error_file).read_text(encoding="utf-8", errors="replace")
+
+    scan = scan_project(
+        root,
+        include=args.include,
+        exclude=args.exclude,
+        max_file_bytes=args.max_file_bytes,
+    )
+    output = render_context_pack(scan, goal=args.goal, mode=args.mode, error_log=error_log)
+    output_path = Path(args.output).resolve()
+    output_path.write_text(output, encoding="utf-8")
+
+    if args.copy:
+        _copy_to_clipboard(output)
+
+    print(f"Created: {output_path}")
+    print(f"Tokens estimate: {estimate_tokens(output):,}")
+    print(f"Files included: {len(scan.files)}")
+    return 0
+
+
+def _copy_to_clipboard(text: str) -> None:
+    commands = [
+        (["pbcopy"], None),
+        (["xclip", "-selection", "clipboard"], None),
+        (["xsel", "--clipboard", "--input"], None),
+        (["wl-copy"], None),
+    ]
+    for command, _ in commands:
+        if shutil.which(command[0]):
+            subprocess.run(command, input=text, text=True, check=False)
+            print("Copied to clipboard")
+            return
+    print("Clipboard tool not found; install pbcopy, xclip, xsel, or wl-copy.", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

promptmint/models.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ProjectFile:
+    relative_path: str
+    language: str
+    content: str
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    root: str
+    tree: str
+    files: list[ProjectFile] = field(default_factory=list)
+    dependency_files: list[ProjectFile] = field(default_factory=list)
+    git_diff: str = ""

promptmint/renderer.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from .models import ProjectFile, ScanResult
+
+MODE_REQUESTS = {
+    "debug": "Please find the root cause, explain it briefly, and suggest the smallest safe fix.",
+    "review": "Please review this code for bugs, security issues, performance, and maintainability.",
+    "explain": "Please explain how this project works, focusing on the included files.",
+    "refactor": "Please suggest a safe refactor plan and identify the smallest first change.",
+}
+
+
+def render_context_pack(
+    scan: ScanResult,
+    goal: str | None = None,
+    mode: str = "debug",
+    error_log: str | None = None,
+) -> str:
+    mode = mode if mode in MODE_REQUESTS else "debug"
+    sections = ["# Project Context Pack", ""]
+    sections.extend(["## Goal", goal or "Analyze this project context and help with the task.", ""])
+    sections.extend([f"## {mode.title()} Request", MODE_REQUESTS[mode], ""])
+    sections.extend(["## Project Root", f"`{scan.root}`", ""])
+    sections.extend(["## Project Tree", "```text", scan.tree or "(empty)", "```", ""])
+
+    if scan.dependency_files:
+        sections.append("## Dependency / Manifest Files")
+        sections.append("")
+        for file in scan.dependency_files:
+            sections.extend(_render_file(file))
+
+    if scan.git_diff:
+        sections.extend(["## Git Diff", "```diff", scan.git_diff, "```", ""])
+
+    relevant_files = [
+        file for file in scan.files
+        if all(file.relative_path != dep.relative_path for dep in scan.dependency_files)
+    ]
+    if relevant_files:
+        sections.append("## Relevant Files")
+        sections.append("")
+        for file in relevant_files:
+            sections.extend(_render_file(file))
+
+    if error_log:
+        sections.extend(["## Error Log", "```text", error_log.strip(), "```", ""])
+
+    sections.extend(["## Final Instruction", MODE_REQUESTS[mode], ""])
+    return "\n".join(sections).rstrip() + "\n"
+
+
+def _render_file(file: ProjectFile) -> list[str]:
+    return [
+        f"### `{file.relative_path}`",
+        f"```{file.language}",
+        file.content.rstrip(),
+        "```",
+        "",
+    ]

promptmint/scanner.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+from pathlib import Path
+
+from .models import ProjectFile, ScanResult
+
+DEFAULT_EXCLUDED_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".idea",
+    ".vscode",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "target",
+    ".next",
+    ".nuxt",
+    ".venv",
+    "venv",
+}
+
+DEFAULT_EXCLUDED_FILES = {
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".DS_Store",
+    "promptmint-output.md",
+}
+
+DEPENDENCY_FILES = {
+    "package.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "package-lock.json",
+    "requirements.txt",
+    "pyproject.toml",
+    "poetry.lock",
+    "Pipfile",
+    "composer.json",
+    "composer.lock",
+    "go.mod",
+    "go.sum",
+    "Cargo.toml",
+    "Cargo.lock",
+    "pubspec.yaml",
+    "pubspec.lock",
+    "Dockerfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+}
+
+LANGUAGE_BY_SUFFIX = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".go": "go",
+    ".php": "php",
+    ".dart": "dart",
+    ".rs": "rust",
+    ".java": "java",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".hpp": "cpp",
+    ".cs": "csharp",
+    ".rb": "ruby",
+    ".sh": "bash",
+    ".bash": "bash",
+    ".zsh": "zsh",
+    ".md": "markdown",
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".xml": "xml",
+    ".html": "html",
+    ".css": "css",
+    ".scss": "scss",
+    ".sql": "sql",
+}
+
+TEXT_SUFFIXES = set(LANGUAGE_BY_SUFFIX) | {
+    ".txt",
+    ".ini",
+    ".cfg",
+    ".conf",
+    ".gitignore",
+    ".dockerignore",
+}
+
+
+def scan_project(
+    root: str | Path,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    max_file_bytes: int = 50_000,
+) -> ScanResult:
+    root_path = Path(root).resolve()
+    exclude_patterns = exclude or []
+    include_patterns = include or []
+
+    files: list[ProjectFile] = []
+    dependency_files: list[ProjectFile] = []
+    tree_paths: list[str] = []
+
+    for path in sorted(root_path.rglob("*")):
+        rel = path.relative_to(root_path).as_posix()
+        if _is_excluded(path, rel, root_path, exclude_patterns):
+            continue
+        if path.is_dir():
+            tree_paths.append(rel + "/")
+            continue
+        if include_patterns and not _matches_any(rel, include_patterns):
+            continue
+        if not _is_text_file(path):
+            continue
+        if path.stat().st_size > max_file_bytes:
+            continue
+
+        project_file = ProjectFile(
+            relative_path=rel,
+            language=_language_for(path),
+            content=path.read_text(encoding="utf-8", errors="replace"),
+        )
+        files.append(project_file)
+        if path.name in DEPENDENCY_FILES:
+            dependency_files.append(project_file)
+        tree_paths.append(rel)
+
+    return ScanResult(
+        root=str(root_path),
+        tree=_render_tree(tree_paths),
+        files=files,
+        dependency_files=dependency_files,
+        git_diff=_git_diff(root_path),
+    )
+
+
+def _is_excluded(path: Path, rel: str, root: Path, extra_patterns: list[str]) -> bool:
+    parts = set(path.relative_to(root).parts)
+    if parts & DEFAULT_EXCLUDED_DIRS:
+        return True
+    if path.name in DEFAULT_EXCLUDED_FILES:
+        return True
+    return _matches_any(rel, extra_patterns)
+
+
+def _matches_any(rel: str, patterns: list[str]) -> bool:
+    path = Path(rel)
+    for pattern in patterns:
+        pattern = pattern.strip()
+        if not pattern:
+            continue
+        if fnmatch.fnmatch(rel, pattern) or path.match(pattern):
+            return True
+        if "**/" in pattern and fnmatch.fnmatch(rel, pattern.replace("**/", "")):
+            return True
+    return False
+
+
+def _is_text_file(path: Path) -> bool:
+    if path.name in DEPENDENCY_FILES or path.name in {"README", "LICENSE", "Makefile"}:
+        return True
+    if path.suffix in TEXT_SUFFIXES:
+        return True
+    try:
+        chunk = path.read_bytes()[:1024]
+    except OSError:
+        return False
+    return b"\0" not in chunk and path.suffix == ""
+
+
+def _language_for(path: Path) -> str:
+    if path.name == "Dockerfile":
+        return "dockerfile"
+    return LANGUAGE_BY_SUFFIX.get(path.suffix, "text")
+
+
+def _render_tree(paths: list[str]) -> str:
+    return "\n".join(paths)
+
+
+def _git_diff(root: Path) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--no-ext-diff"],
+            cwd=str(root),
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return result.stdout.strip()

promptmint/tokens.py

@@ -0,0 +1,9 @@
+def estimate_tokens(text: str) -> int:
+    """Return a simple dependency-free token estimate.
+
+    Most English/code prompts average around 3-5 chars per token. We use 4 and
+    round up so the estimate is useful without requiring tiktoken.
+    """
+    if not text:
+        return 0
+    return (len(text) + 3) // 4

promptmint-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: promptmint
+Version: 0.1.0
+Summary: Turn any codebase into an AI-ready prompt context pack.
+Author: Asim Awdah
+License: MIT
+Keywords: ai,prompt,developer-tools,cli,codebase,context
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PromptMint
+
+Turn any codebase into an AI-ready prompt.
+
+PromptMint scans your project, collects useful source files, dependency manifests, git diff, and optional error logs, then generates a clean Markdown context pack you can paste into ChatGPT, Claude, Gemini, or any coding agent.
+
+## Why?
+
+Copying files into AI chats is slow and messy. PromptMint gives you one command that creates a structured, safe context file for debugging, code review, refactoring, and project explanation.
+
+## Install
+
+```bash
+pip install promptmint
+```
+
+## Install locally for development
+
+```bash
+git clone https://github.com/YOUR_USERNAME/promptmint.git
+cd promptmint
+python3 -m pip install -e .
+```
+
+## Usage
+
+```bash
+promptmint -g "Fix this bug" -m debug
+```
+
+```bash
+promptmint --goal "Review this PR" --mode review --output review-context.md
+```
+
+```bash
+promptmint --goal "Explain this project" --mode explain
+```
+
+```bash
+promptmint -e error.log -m debug -c
+```
+
+## CLI Shortcuts
+
+- `-g`, `--goal`: task goal
+- `-m`, `--mode`: prompt mode
+- `-e`, `--error`: error log file
+- `-i`, `--include`: include glob, repeatable
+- `-x`, `--exclude`: exclude glob, repeatable
+- `-o`, `--output`: output Markdown file
+- `-c`, `--copy`: copy output to clipboard
+- `-s`, `--max-file-bytes`: skip files larger than this size
+
+## Modes
+
+- `debug`: root cause + smallest safe fix
+- `review`: bugs, security, performance, maintainability
+- `explain`: explain how the project works
+- `refactor`: safe refactor plan
+
+## What it includes
+
+- Project tree
+- Dependency/manifest files like `package.json`, `pyproject.toml`, `composer.json`, `go.mod`, `pubspec.yaml`
+- Git diff, if available
+- Text source files
+- Optional error log
+- Final instruction tailored to the selected mode
+
+## What it ignores by default
+
+- `.git`, `node_modules`, `vendor`, `dist`, `build`, virtual environments, caches
+- `.env` files
+- Binary files
+- Large files over 50KB by default
+
+## Examples
+
+```bash
+promptmint . --include "src/**/*.py" --goal "Find the bug"
+```
+
+```bash
+promptmint . --exclude "tests/fixtures/**" --max-file-bytes 20000
+```
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## Roadmap
+
+- [x] Markdown context pack generator
+- [x] Project tree + file scanner
+- [x] Dependency manifest detection
+- [x] Git diff inclusion
+- [x] Debug/review/explain/refactor modes
+- [ ] Better `.gitignore` support
+- [ ] Token budget smart trimming
+- [ ] Interactive file picker
+- [ ] JSON output
+- [ ] MCP server integration
+
+## License
+
+MIT

promptmint-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+promptmint/__init__.py,sha256=KOUPYVNGNu1kRsZGnOzGS7_zl-6Zy0d6zSXeBJ4OlXk,82
+promptmint/cli.py,sha256=kxvv7DQoBnLDZgzTft9xFZ-1gbxxQNSFoqBm1X3A7g8,2837
+promptmint/models.py,sha256=z8N5Jna4OxRrZerh6FGKvevK8M-VyHXLiBz-ApKGbeU,368
+promptmint/renderer.py,sha256=006E_ddfLgD9x0ebGf4nAJT-mUHRbFA2k8YQQOaF-ms,2125
+promptmint/scanner.py,sha256=fxfwmiH29G9RiTpFYH6k2GCkqVNLCF64H1HgKIjdUhw,4831
+promptmint/tokens.py,sha256=6Jwa7_AOP66qSSTQMxOrUTO4Qwn8cmhsGDGhRRbON2c,315
+promptmint-0.1.0.dist-info/licenses/LICENSE,sha256=WeKhaawhmMJlph1tsbWuzf3Fo3wj3Gdfrdd40n1uraI,1067
+promptmint-0.1.0.dist-info/METADATA,sha256=FZK2Yx2OsfDK8NH9ybz4CgGTNfrnSjG6gnfsMwN0baY,3143
+promptmint-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+promptmint-0.1.0.dist-info/entry_points.txt,sha256=O_X23VJ199FimxyB3CR53hl8EQE8PnCgTNVePTHPufk,51
+promptmint-0.1.0.dist-info/top_level.txt,sha256=swbI5q-U0IiTX-0OW4wPZlUms5Cj9H9Gz1_PUDBEOkY,11
+promptmint-0.1.0.dist-info/RECORD,,

promptmint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

promptmint-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+promptmint = promptmint.cli:main

promptmint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asim Awdah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptmint-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+promptmint