manage-project-tool 0.1.0__tar.gz

manage_project_tool-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# ManageProjectTool .gitignore
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnp.*
+
+# Logs
+logs/
+*.log
+*.log.*
+
+# Runtime / environment
+.env
+.env.*
+
+# Build outputs
+dist/
+build/
+
+# Coverage
+coverage/
+.nyc_output/
+htmlcov/
+
+# Python
+.venv/
+venv/
+ENV/
+env/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.coverage
+pip-wheel-metadata/
+*.egg-info/
+.eggs/
+*.egg
+*.whl
+
+# PyInstaller
+__pycache__/
+dist/
+build/
+
+# Caches
+.cache/
+
+# IDEs and editors
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.swp
+*~
+*.tmp
+*.bak
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Lint / tooling
+.eslintcache
+
+# Other
+node-repl.history
+

manage_project_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jaminsmoke
+
+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.

manage_project_tool-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: manage-project-tool
+Version: 0.1.0
+Summary: Python engine for ManageProjectTool — audits and manages repositories
+Project-URL: Homepage, https://github.com/jaminsmoke/ManageProjectTool
+Project-URL: Repository, https://github.com/jaminsmoke/ManageProjectTool
+Project-URL: Issues, https://github.com/jaminsmoke/ManageProjectTool/issues
+Author: jaminsmoke
+License: MIT
+License-File: LICENSE
+Keywords: manageprojecttool,mpt,project-audit,static-analysis
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ManageProjectTool
+
+ManageProjectTool audita repositorios con un engine Python, un coordinator
+Node.js, una app Electron y una GitHub Action reutilizable para CI.
+
+## Capacidades actuales
+
+- Ejecuta checks core y plugins sobre documentación, CI, dependencias y seguridad.
+- Aplica severidades efectivas (`error`, `warning`, `info`) y umbrales como
+  `thresholds.maxWarnings` desde `mpt.config.json`.
+- Expone un CLI standalone con `mpt scan` y `mpt init`.
+- Genera reportes en JSON, HTML y Markdown según el flujo de uso.
+
+## Uso local
+
+### CLI Python
+
+```bash
+python -m engine.cli scan .
+python -m engine.cli scan . --format json
+python -m engine.cli init .
+```
+
+### Validación del workspace
+
+```bash
+npm install
+npm run validate
+```
+
+`npm run validate` ejecuta formato, linters y tests en secuencia.
+
+### Preparación de release (Fase B)
+
+```bash
+npm run release:check
+```
+
+Este comando valida prerequisitos implementables en el repo para `v0.1.0`
+(`LICENSE`, artefactos de Action y assets de Electron) y lista pendientes
+externos como Trusted Publisher en PyPI, `NPM_TOKEN` y Marketplace.
+
+## GitHub Action
+
+La Action Docker definida en la raíz permite reutilizar el engine sin levantar
+el coordinator.
+
+```yaml
+name: Scan repository
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run ManageProjectTool
+        id: mpt
+        uses: jaminsmoke/ManageProjectTool@v0.1.0
+        with:
+          target-path: .
+          format: markdown
+          checks: readme-presence,lockfile,ci-workflow-presence
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mpt-report
+          path: ${{ steps.mpt.outputs.report-path }}
+```
+
+Entradas soportadas:
+
+- `target-path`: ruta relativa dentro de `GITHUB_WORKSPACE`.
+- `checks`: lista separada por comas; vacía usa `mpt.config.json` o todos los checks.
+- `format`: `markdown` o `json`.
+
+Salidas expuestas:
+
+- `report-path`: fichero generado en `reports/`.
+- `exit-code`: resultado efectivo de la política de severidad.
+- `summary-json`: resumen compacto para pasos posteriores.
+
+## Documentación
+
+- [docs/checks.md](docs/checks.md)
+- [docs/github-action.md](docs/github-action.md)
+- [docs/roadmaps/roadmap2.md](docs/roadmaps/roadmap2.md)

manage_project_tool-0.1.0/README.md

@@ -0,0 +1,91 @@
+# ManageProjectTool
+
+ManageProjectTool audita repositorios con un engine Python, un coordinator
+Node.js, una app Electron y una GitHub Action reutilizable para CI.
+
+## Capacidades actuales
+
+- Ejecuta checks core y plugins sobre documentación, CI, dependencias y seguridad.
+- Aplica severidades efectivas (`error`, `warning`, `info`) y umbrales como
+  `thresholds.maxWarnings` desde `mpt.config.json`.
+- Expone un CLI standalone con `mpt scan` y `mpt init`.
+- Genera reportes en JSON, HTML y Markdown según el flujo de uso.
+
+## Uso local
+
+### CLI Python
+
+```bash
+python -m engine.cli scan .
+python -m engine.cli scan . --format json
+python -m engine.cli init .
+```
+
+### Validación del workspace
+
+```bash
+npm install
+npm run validate
+```
+
+`npm run validate` ejecuta formato, linters y tests en secuencia.
+
+### Preparación de release (Fase B)
+
+```bash
+npm run release:check
+```
+
+Este comando valida prerequisitos implementables en el repo para `v0.1.0`
+(`LICENSE`, artefactos de Action y assets de Electron) y lista pendientes
+externos como Trusted Publisher en PyPI, `NPM_TOKEN` y Marketplace.
+
+## GitHub Action
+
+La Action Docker definida en la raíz permite reutilizar el engine sin levantar
+el coordinator.
+
+```yaml
+name: Scan repository
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run ManageProjectTool
+        id: mpt
+        uses: jaminsmoke/ManageProjectTool@v0.1.0
+        with:
+          target-path: .
+          format: markdown
+          checks: readme-presence,lockfile,ci-workflow-presence
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mpt-report
+          path: ${{ steps.mpt.outputs.report-path }}
+```
+
+Entradas soportadas:
+
+- `target-path`: ruta relativa dentro de `GITHUB_WORKSPACE`.
+- `checks`: lista separada por comas; vacía usa `mpt.config.json` o todos los checks.
+- `format`: `markdown` o `json`.
+
+Salidas expuestas:
+
+- `report-path`: fichero generado en `reports/`.
+- `exit-code`: resultado efectivo de la política de severidad.
+- `summary-json`: resumen compacto para pasos posteriores.
+
+## Documentación
+
+- [docs/checks.md](docs/checks.md)
+- [docs/github-action.md](docs/github-action.md)
+- [docs/roadmaps/roadmap2.md](docs/roadmaps/roadmap2.md)

manage_project_tool-0.1.0/docs/README.md

@@ -0,0 +1,21 @@
+# Documentación del proyecto ManageProjectTool
+
+Este directorio contiene los documentos que definen el alcance, diseño y roadmap del proyecto.
+
+Archivos:
+
+- `vision.md` — Visión y objetivos
+- `requirements.md` — Requisitos y alcance
+- `architecture.md` — Arquitectura y decisiones
+- `structure_conventions.md` — Estructura del repositorio y convenciones
+- `metrics.md` — Métricas y reglas para auditoría automática
+- `checks.md` — Catálogo de checks, severidades y política de salida
+- `github-action.md` — Uso de la GitHub Action Docker y sus outputs
+- `roadmaps/roadmap2.md` — Roadmap activo y milestones vigentes
+- `contribution.md` — Guía para contribuir
+
+Cómo usar:
+
+- Completa y revisa cada documento.
+- Los cambios en la carpeta `docs` deben discutirse en PRs.
+- Próximo paso: cerrar los pendientes externos de la Fase B y validar el primer release público.

manage_project_tool-0.1.0/electron/assets/README.md

@@ -0,0 +1,10 @@
+# Electron Assets
+
+Esta carpeta contiene los iconos usados por `electron-builder`:
+
+- `icon.ico` (Windows)
+- `icon.icns` (macOS)
+- `icon.png` (Linux)
+
+Las referencias `icon:` ya están habilitadas en
+[electron-builder.yml](../../electron-builder.yml).

manage_project_tool-0.1.0/engine/__init__.py

@@ -0,0 +1 @@
+"""ManageProjectTool engine package."""

manage_project_tool-0.1.0/engine/checks/__init__.py

@@ -0,0 +1,49 @@
+"""A1 checks package — nuevos checks estándar del roadmap v2 Fase A."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from engine.checks import (
+    changelog_presence,
+    contributing_presence,
+    dependency_freshness,
+    env_example_presence,
+    gitignore_presence,
+    license_presence,
+    package_json_fields,
+    secrets_scan,
+    security_audit,
+    test_presence,
+)
+
+if TYPE_CHECKING:
+    from engine.engine import CheckDefinition, CheckRunner
+
+ALL_DEFINITIONS: list[CheckDefinition] = [
+    contributing_presence.DEFINITION,
+    changelog_presence.DEFINITION,
+    license_presence.DEFINITION,
+    env_example_presence.DEFINITION,
+    package_json_fields.DEFINITION,
+    gitignore_presence.DEFINITION,
+    dependency_freshness.DEFINITION,
+    test_presence.DEFINITION,
+    security_audit.DEFINITION,
+    secrets_scan.DEFINITION,
+]
+
+ALL_RUNNERS: dict[str, CheckRunner] = {
+    contributing_presence.DEFINITION["id"]: contributing_presence.run,
+    changelog_presence.DEFINITION["id"]: changelog_presence.run,
+    license_presence.DEFINITION["id"]: license_presence.run,
+    env_example_presence.DEFINITION["id"]: env_example_presence.run,
+    package_json_fields.DEFINITION["id"]: package_json_fields.run,
+    gitignore_presence.DEFINITION["id"]: gitignore_presence.run,
+    dependency_freshness.DEFINITION["id"]: dependency_freshness.run,
+    test_presence.DEFINITION["id"]: test_presence.run,
+    security_audit.DEFINITION["id"]: security_audit.run,
+    secrets_scan.DEFINITION["id"]: secrets_scan.run,
+}
+
+__all__ = ["ALL_DEFINITIONS", "ALL_RUNNERS"]

manage_project_tool-0.1.0/engine/checks/changelog_presence.py

@@ -0,0 +1,36 @@
+"""Check: changelog-presence — verifica que existe CHANGELOG.md o RELEASES.md."""
+
+from __future__ import annotations
+
+import os
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from engine.engine import CheckDefinition, CheckResult
+
+DEFINITION: CheckDefinition = {
+    "id": "changelog-presence",
+    "name": "CHANGELOG presente",
+    "category": "docs",
+    "severity": "medium",
+}
+
+_CANDIDATES = [
+    "CHANGELOG.md",
+    "CHANGELOG.rst",
+    "CHANGELOG.txt",
+    "CHANGELOG",
+    "RELEASES.md",
+    "RELEASES.rst",
+    "HISTORY.md",
+    "CHANGES.md",
+    "docs/CHANGELOG.md",
+]
+
+
+def run(repo_path: str) -> CheckResult:
+    for candidate in _CANDIDATES:
+        if os.path.isfile(os.path.join(repo_path, candidate)):
+            return {"ok": True, "file": candidate, "candidates": _CANDIDATES}
+    return {"ok": False, "file": None, "candidates": _CANDIDATES}

manage_project_tool-0.1.0/engine/checks/contributing_presence.py

@@ -0,0 +1,33 @@
+"""Check: contributing-presence — verifica que existe CONTRIBUTING.md."""
+
+from __future__ import annotations
+
+import os
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from engine.engine import CheckDefinition, CheckResult
+
+DEFINITION: CheckDefinition = {
+    "id": "contributing-presence",
+    "name": "CONTRIBUTING presente",
+    "category": "docs",
+    "severity": "medium",
+}
+
+_CANDIDATES = [
+    "CONTRIBUTING.md",
+    "CONTRIBUTING.rst",
+    "CONTRIBUTING.txt",
+    "CONTRIBUTING",
+    ".github/CONTRIBUTING.md",
+    "docs/CONTRIBUTING.md",
+]
+
+
+def run(repo_path: str) -> CheckResult:
+    for candidate in _CANDIDATES:
+        if os.path.isfile(os.path.join(repo_path, candidate)):
+            return {"ok": True, "file": candidate, "candidates": _CANDIDATES}
+    return {"ok": False, "file": None, "candidates": _CANDIDATES}

manage_project_tool-0.1.0/engine/checks/dependency_freshness.py

@@ -0,0 +1,98 @@
+"""Check: dependency-freshness — detecta dependencias muy desactualizadas."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from engine.engine import CheckDefinition, CheckResult
+
+DEFINITION: CheckDefinition = {
+    "id": "dependency-freshness",
+    "name": "Dependencias actualizadas",
+    "category": "dependencies",
+    "severity": "medium",
+}
+
+_SUBPROCESS_TIMEOUT = 30
+
+
+def _run_npm_outdated(repo_path: str) -> dict[str, object] | None:
+    """Run `npm outdated --json`. Returns parsed output or None if unavailable."""
+    pkg_path = os.path.join(repo_path, "package.json")
+    if not os.path.isfile(pkg_path):
+        return None
+    try:
+        proc = subprocess.run(
+            ["npm", "outdated", "--json"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT,
+            check=False,
+        )
+        if proc.stdout.strip():
+            return json.loads(proc.stdout)
+        return {}
+    except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def _run_pip_outdated(repo_path: str) -> list[dict[str, str]] | None:
+    """Run `pip list --outdated --format json`. Returns list or None if unavailable."""
+    has_reqs = any(
+        os.path.isfile(os.path.join(repo_path, f))
+        for f in (
+            "requirements.txt",
+            "pyproject.toml",
+            "Pipfile",
+            "setup.py",
+            "setup.cfg",
+        )
+    )
+    if not has_reqs:
+        return None
+    try:
+        proc = subprocess.run(
+            ["pip", "list", "--outdated", "--format", "json"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT,
+            check=False,
+        )
+        if proc.stdout.strip():
+            return json.loads(proc.stdout)
+        return []
+    except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def run(repo_path: str) -> CheckResult:
+    npm_outdated = _run_npm_outdated(repo_path)
+    pip_outdated = _run_pip_outdated(repo_path)
+
+    if npm_outdated is None and pip_outdated is None:
+        return {
+            "ok": True,
+            "skipped": True,
+            "reason": "No supported ecosystems detected or tools unavailable",
+            "npm_outdated": None,
+            "pip_outdated": None,
+        }
+
+    npm_count = len(npm_outdated) if npm_outdated else 0
+    pip_count = len(pip_outdated) if pip_outdated else 0
+    total_outdated = npm_count + pip_count
+
+    return {
+        "ok": total_outdated == 0,
+        "skipped": False,
+        "total_outdated": total_outdated,
+        "npm_outdated": npm_outdated,
+        "pip_outdated": pip_outdated,
+    }

manage_project_tool-0.1.0/engine/checks/env_example_presence.py

@@ -0,0 +1,73 @@
+"""Check: env-example-presence — si hay referencias a .env en el repo, existe .env.example."""
+
+from __future__ import annotations
+
+import os
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from engine.engine import CheckDefinition, CheckResult
+
+DEFINITION: CheckDefinition = {
+    "id": "env-example-presence",
+    "name": ".env.example presente cuando se usan variables de entorno",
+    "category": "hygiene",
+    "severity": "high",
+}
+
+_ENV_INDICATORS = [
+    ".env",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "docker-compose.override.yml",
+]
+
+_DOCKER_COMPOSE_ENV_MARKER = ".env"
+
+
+def _has_env_usage(repo_path: str) -> bool:
+    """Return True if the repo shows signs of relying on a .env file."""
+    if os.path.isfile(os.path.join(repo_path, ".env")):
+        return True
+
+    for compose_name in ("docker-compose.yml", "docker-compose.yaml"):
+        compose_path = os.path.join(repo_path, compose_name)
+        if not os.path.isfile(compose_path):
+            continue
+        try:
+            with open(compose_path, encoding="utf-8") as f:
+                if ".env" in f.read():
+                    return True
+        except OSError:
+            pass
+
+    makefile_path = os.path.join(repo_path, "Makefile")
+    if os.path.isfile(makefile_path):
+        try:
+            with open(makefile_path, encoding="utf-8") as f:
+                if ".env" in f.read():
+                    return True
+        except OSError:
+            pass
+
+    return False
+
+
+def run(repo_path: str) -> CheckResult:
+    if not _has_env_usage(repo_path):
+        return {
+            "ok": True,
+            "skipped": True,
+            "reason": "No .env usage detected",
+            "file": None,
+        }
+
+    example_path = os.path.join(repo_path, ".env.example")
+    found = os.path.isfile(example_path)
+    return {
+        "ok": found,
+        "skipped": False,
+        "file": ".env.example" if found else None,
+        "has_env_usage": True,
+    }