nexus-dev-toolkit 3.0.0__py3-none-any.whl

tools/epav/package_resolver.py

@@ -0,0 +1,271 @@
+"""
+resolve_package_versions — MCP tool for Day 0 APPLY.
+
+Given a package manager type and a list of packages with optional major-version
+constraints (derived from the arch doc), spins up a temp directory, runs the
+package manager's resolution command, reads the lock file, and returns exact
+pinned versions. Never hardcodes versions or stack-specific logic beyond what
+is needed to dispatch the right CLI.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from mcp.server.fastmcp import FastMCP
+
+_PM_REGISTRY: dict[str, dict] = {
+    "npm": {
+        "detect": ["package.json", "package-lock.json", ".npmrc"],
+        "init": ["npm", "init", "-y"],
+        "resolve": ["npm", "install", "--package-lock-only", "--legacy-peer-deps"],
+        "lock_file": "package-lock.json",
+    },
+    "pnpm": {
+        "detect": ["pnpm-lock.yaml", "pnpm-workspace.yaml"],
+        "init": ["pnpm", "init"],
+        "resolve": ["pnpm", "install", "--lockfile-only"],
+        "lock_file": "pnpm-lock.yaml",
+    },
+    "yarn": {
+        "detect": ["yarn.lock", ".yarnrc.yml"],
+        "init": ["yarn", "init", "-y"],
+        "resolve": ["yarn", "install", "--frozen-lockfile"],
+        "lock_file": "yarn.lock",
+    },
+    "maven": {
+        "detect": ["pom.xml"],
+        "init": None,
+        "resolve": ["mvn", "dependency:resolve", "-q"],
+        "lock_file": None,
+    },
+    "gradle": {
+        "detect": ["build.gradle", "build.gradle.kts"],
+        "init": None,
+        "resolve": ["gradle", "dependencies", "--configuration", "runtimeClasspath"],
+        "lock_file": "gradle.lockfile",
+    },
+    "pub": {
+        "detect": ["pubspec.yaml"],
+        "init": None,
+        "resolve": ["flutter", "pub", "get"],
+        "lock_file": "pubspec.lock",
+    },
+    "go": {
+        "detect": ["go.mod"],
+        "init": None,
+        "resolve": ["go", "mod", "tidy"],
+        "lock_file": "go.sum",
+    },
+    "cargo": {
+        "detect": ["Cargo.toml"],
+        "init": None,
+        "resolve": ["cargo", "update"],
+        "lock_file": "Cargo.lock",
+    },
+    "pip": {
+        "detect": ["requirements.txt", "pyproject.toml"],
+        "init": None,
+        "resolve": ["pip", "install", "--dry-run", "--report", "-"],
+        "lock_file": None,
+    },
+}
+
+
+def _detect_package_manager(hint: str | None) -> str:
+    if not hint:
+        return "npm"
+    hint_lower = hint.lower()
+    for pm in _PM_REGISTRY:
+        if pm in hint_lower:
+            return pm
+    if any(k in hint_lower for k in ["node", "next", "react", "vite", "typescript"]):
+        return "npm"
+    if any(k in hint_lower for k in ["flutter", "dart"]):
+        return "pub"
+    if any(k in hint_lower for k in ["java", "spring", "kotlin"]):
+        return "maven"
+    if "python" in hint_lower:
+        return "pip"
+    if "rust" in hint_lower:
+        return "cargo"
+    return "npm"
+
+
+def _strip_version_spec(pkg: str) -> str:
+    if pkg.startswith("@"):
+        rest = pkg[1:]
+        if "@" in rest:
+            return f"@{rest[:rest.index('@')]}"
+        return pkg
+    return pkg.split("@")[0] if "@" in pkg else pkg
+
+
+def _read_npm_lock(lock_path: Path, packages: list[str]) -> dict[str, str]:
+    try:
+        lock = json.loads(lock_path.read_text())
+        deps = lock.get("packages", {})
+        return {
+            _strip_version_spec(pkg): deps.get(f"node_modules/{_strip_version_spec(pkg)}", {}).get("version", "unknown")
+            for pkg in packages
+            if f"node_modules/{_strip_version_spec(pkg)}" in deps
+        }
+    except Exception:
+        return {}
+
+
+def _read_pubspec_lock(lock_path: Path, packages: list[str]) -> dict[str, str]:
+    versions: dict[str, str] = {}
+    try:
+        current_pkg = None
+        for line in lock_path.read_text().splitlines():
+            stripped = line.strip()
+            if stripped.endswith(":") and not stripped.startswith(" "):
+                current_pkg = stripped[:-1]
+            elif current_pkg and stripped.startswith("version:"):
+                ver = stripped.split(":", 1)[1].strip().strip('"')
+                if current_pkg in packages:
+                    versions[current_pkg] = ver
+    except Exception:
+        pass
+    return versions
+
+
+def _read_go_sum(lock_path: Path, packages: list[str]) -> dict[str, str]:
+    versions: dict[str, str] = {}
+    try:
+        for line in lock_path.read_text().splitlines():
+            parts = line.split()
+            if len(parts) >= 2:
+                mod, ver = parts[0], parts[1].split("/")[0]
+                for pkg in packages:
+                    if pkg in mod and pkg not in versions:
+                        versions[pkg] = ver.lstrip("v")
+    except Exception:
+        pass
+    return versions
+
+
+def _read_cargo_lock(lock_path: Path, packages: list[str]) -> dict[str, str]:
+    versions: dict[str, str] = {}
+    try:
+        current_name = None
+        for line in lock_path.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("name ="):
+                current_name = line.split("=", 1)[1].strip().strip('"')
+            elif line.startswith("version =") and current_name:
+                ver = line.split("=", 1)[1].strip().strip('"')
+                if current_name in packages and current_name not in versions:
+                    versions[current_name] = ver
+    except Exception:
+        pass
+    return versions
+
+
+def _read_lock_file(pm: str, lock_path: Path, packages: list[str]) -> dict[str, str]:
+    if pm in ("npm", "pnpm", "yarn"):
+        return _read_npm_lock(lock_path, packages)
+    if pm == "pub":
+        return _read_pubspec_lock(lock_path, packages)
+    if pm == "go":
+        return _read_go_sum(lock_path, packages)
+    if pm == "cargo":
+        return _read_cargo_lock(lock_path, packages)
+    return {}
+
+
+def _build_install_args(pm: str, packages: list[str]) -> list[str]:
+    if pm == "npm":
+        return ["npm", "install", "--package-lock-only", "--legacy-peer-deps"] + packages
+    if pm == "pnpm":
+        return ["pnpm", "add", "--lockfile-only"] + packages
+    if pm == "yarn":
+        return ["yarn", "add"] + packages
+    if pm == "pub":
+        return ["flutter", "pub", "add"] + packages
+    if pm == "go":
+        return ["go", "get"] + packages
+    if pm == "cargo":
+        return ["cargo", "add"] + packages
+    return _PM_REGISTRY[pm]["resolve"]
+
+
+def register_package_resolver_tool(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def resolve_package_versions(
+        packages: list[str],
+        package_manager: str = "",
+        stack_hint: str = "",
+    ) -> str:
+        """
+        Resolve exact pinned package versions using the real package manager.
+
+        Runs in a temp directory — does not modify the project. Returns exact
+        versions so Day 0 APPLY can write deterministic package manifests.
+
+        Args:
+            packages: List of packages with optional constraints,
+                      e.g. ["next@16", "react", "@supabase/supabase-js@2"]
+            package_manager: npm | pnpm | yarn | pub | maven | gradle | go | cargo | pip.
+                             Auto-detected from stack_hint if omitted.
+            stack_hint: Free-text hint from arch doc, e.g. "Next.js 16 + TypeScript".
+
+        Returns:
+            JSON: { "versions": {"next": "16.3.2", ...}, "package_manager": "npm",
+                    "lock_file": "package-lock.json", "errors": [...] }
+        """
+        pm = package_manager.strip().lower() if package_manager.strip() else _detect_package_manager(stack_hint)
+
+        if pm not in _PM_REGISTRY:
+            return json.dumps({
+                "error": f"Unknown package manager: {pm}. Supported: {list(_PM_REGISTRY.keys())}"
+            })
+
+        pm_config = _PM_REGISTRY[pm]
+        tmpdir = tempfile.mkdtemp(prefix="nexus-resolve-")
+        errors: list[str] = []
+
+        try:
+            if pm_config["init"]:
+                subprocess.run(pm_config["init"], cwd=tmpdir, capture_output=True, timeout=30)
+
+            if pm == "npm":
+                (Path(tmpdir) / "package.json").write_text(
+                    json.dumps({"name": "resolve-temp", "version": "0.0.1", "private": True})
+                )
+
+            cmd = _build_install_args(pm, packages)
+            result = subprocess.run(cmd, cwd=tmpdir, capture_output=True, text=True, timeout=120)
+
+            if result.returncode != 0:
+                errors.append(result.stderr[:500])
+
+            lock_file = pm_config.get("lock_file")
+            versions: dict[str, str] = {}
+            if lock_file:
+                lock_path = Path(tmpdir) / lock_file
+                if lock_path.exists():
+                    pkg_names = [
+                        p.split("@")[0] if "@" in p and not p.startswith("@")
+                        else p.rsplit("@", 1)[0] if p.count("@") > 1
+                        else p
+                        for p in packages
+                    ]
+                    versions = _read_lock_file(pm, lock_path, pkg_names)
+
+            return json.dumps({
+                "versions": versions,
+                "package_manager": pm,
+                "lock_file": lock_file,
+                "errors": errors,
+            })
+
+        except subprocess.TimeoutExpired:
+            return json.dumps({"error": "Resolution timed out after 120s", "package_manager": pm})
+        except Exception as e:
+            return json.dumps({"error": str(e), "package_manager": pm})
+        finally:
+            shutil.rmtree(tmpdir, ignore_errors=True)

tools/epav/project_rules.py

@@ -0,0 +1,208 @@
+import json
+import logging
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+_KNOWLEDGE_DIRS = [
+    "knowledge/rules",
+    "knowledge/patterns",
+    "knowledge/prompts/dev",
+    "knowledge/agents",
+    "knowledge/retros",
+    "knowledge/templates",
+]
+
+_AGENTS_MD_TEMPLATE = """\
+# AGENTS.md
+
+> Cross-tool project rules. Every AI assistant working on this project must read this file first.
+> Generated by nexus-dev-toolkit — update as the project evolves.
+
+## Project
+
+**Stack:** {stack}
+**Repo:** {repo}
+
+## Coding Standards
+
+See `knowledge/rules/coding-standards.md` for the full ruleset.
+
+### Non-negotiable rules
+
+{rules}
+
+## Git Conventions
+
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`
+- One logical change per commit
+- Branch naming: `feat/`, `fix/`, `chore/`
+
+## Quality Gates
+
+- All acceptance criteria from the task CSV must pass before marking done
+- Run `/validate` after every `/apply`
+- Contribute new patterns to `knowledge/patterns/` via PR
+
+## E→P→A→V Cycle
+
+Every dev task follows: `/evaluate` → `/plan` → `/apply` → `/validate`
+The task CSV provides the prompt — do not write prompts from scratch.
+"""
+
+_CODING_STANDARDS_TEMPLATE = """\
+# Coding Standards
+
+_Derived from architecture document. Update via PR when conventions change._
+
+## Stack
+
+{stack_detail}
+
+## Rules
+
+{rules_detail}
+
+## Rationale
+
+Rules without rationale get ignored. Every rule here links to the architecture
+decision that produced it. When in doubt, read the arch doc in `docs/arch-docs/`.
+"""
+
+
+def _load_arch_summary() -> dict:
+    summary_path = Path("knowledge/rules/arch-summary.md")
+    if summary_path.exists():
+        return {"source": str(summary_path), "text": summary_path.read_text(encoding="utf-8")}
+    return {}
+
+
+def _infer_stack(arch_text: str) -> str:
+    text_lower = arch_text.lower()
+    parts = []
+    if "next.js" in text_lower or "nextjs" in text_lower:
+        parts.append("Next.js")
+    if "react native" in text_lower:
+        parts.append("React Native")
+    if "flutter" in text_lower:
+        parts.append("Flutter")
+    if "trpc" in text_lower or "t3" in text_lower:
+        parts.append("tRPC / T3")
+    if "prisma" in text_lower:
+        parts.append("Prisma")
+    if "postgres" in text_lower or "postgresql" in text_lower:
+        parts.append("PostgreSQL")
+    if "tailwind" in text_lower:
+        parts.append("Tailwind CSS")
+    if "supabase" in text_lower:
+        parts.append("Supabase")
+    return ", ".join(parts) if parts else "(update with your stack)"
+
+
+def register_project_rules_tool(mcp: FastMCP) -> None:
+
+    @mcp.tool()
+    async def generate_project_rules(
+        arch_doc_path: str = "",
+        project_name: str = "",
+        overwrite: bool = False,
+    ) -> str:
+        """
+        Generate AGENTS.md and knowledge/ directory structure from an architecture document.
+
+        Args:
+            arch_doc_path: Path to the architecture doc (.md). If empty, uses
+                           knowledge/rules/arch-summary.md if ingest_architecture_doc
+                           has already run.
+            project_name:  Name used in AGENTS.md header. Defaults to current dir name.
+            overwrite:     If False (default), returns error if AGENTS.md already exists.
+
+        Returns:
+            JSON with list of files created/updated.
+        """
+        try:
+            agents_path = Path("AGENTS.md")
+            if agents_path.exists() and not overwrite:
+                return json.dumps({
+                    "error": "AGENTS.md already exists. Pass overwrite=true to replace it.",
+                    "existing_path": str(agents_path.resolve()),
+                })
+
+            arch_text = ""
+            source_used = ""
+
+            if arch_doc_path and Path(arch_doc_path).exists():
+                arch_text = Path(arch_doc_path).read_text(encoding="utf-8")
+                source_used = arch_doc_path
+            else:
+                summary = _load_arch_summary()
+                if summary:
+                    arch_text = summary["text"]
+                    source_used = summary["source"]
+
+            if not arch_text:
+                return json.dumps({
+                    "error": "No architecture doc found. Run ingest_architecture_doc first, "
+                             "or provide arch_doc_path.",
+                })
+
+            repo = project_name or Path(".").resolve().name
+            stack = _infer_stack(arch_text)
+            rules = (
+                "- Follow the conventions in the architecture document\n"
+                "- No console.log in production code — use the project logger\n"
+                "- All secrets via environment variables — never hardcoded\n"
+                "- Pin exact dependency versions (no ^ or ~)\n"
+                "- Every task must pass /validate before moving on"
+            )
+
+            dirs_created = []
+            for d in _KNOWLEDGE_DIRS:
+                p = Path(d)
+                if not p.exists():
+                    p.mkdir(parents=True, exist_ok=True)
+                    dirs_created.append(d)
+
+            files_written = []
+
+            agents_path.write_text(
+                _AGENTS_MD_TEMPLATE.format(stack=stack, repo=repo, rules=rules),
+                encoding="utf-8",
+            )
+            files_written.append(str(agents_path))
+
+            standards_path = Path("knowledge/rules/coding-standards.md")
+            standards_path.write_text(
+                _CODING_STANDARDS_TEMPLATE.format(
+                    stack_detail=f"**{stack}** — see arch doc for full decisions.",
+                    rules_detail=rules,
+                ),
+                encoding="utf-8",
+            )
+            files_written.append(str(standards_path))
+
+            pattern_path = Path("knowledge/patterns/implement-and-test.md")
+            if not pattern_path.exists():
+                pattern_path.write_text(
+                    "# Implement and Test Pattern\n\n"
+                    "Every dev task follows the E→P→A→V cycle:\n\n"
+                    "1. `/evaluate <task>` — orient, load context, graphify blast radius\n"
+                    "2. `/plan` — blueprint, wait for approval\n"
+                    "3. `/apply` — implement, graphify auto-updates\n"
+                    "4. `/validate` — acceptance criteria, classify issues, contribute patterns\n",
+                    encoding="utf-8",
+                )
+                files_written.append(str(pattern_path))
+
+            return json.dumps({
+                "source_used": source_used,
+                "stack_detected": stack,
+                "dirs_created": dirs_created,
+                "files_written": files_written,
+            }, indent=2)
+
+        except Exception as e:
+            logger.exception("Unexpected error in generate_project_rules")
+            return json.dumps({"error": f"Unexpected error: {e}"})

tools/epav/skills/apply.md

@@ -0,0 +1,41 @@
+# /apply
+
+**APPLY** — Step 3 of the E→P→A→V cycle. Implement the approved plan.
+
+## Prerequisite
+
+A plan must be approved. If `/plan` has not run and been approved, stop and ask.
+
+## Steps
+
+### 1 — Implement exactly what the plan says
+
+- Follow the numbered steps from PLAN in order.
+- Reference AGENTS.md coding standards for every file written.
+- Do not add features, refactor unrelated code, or expand scope beyond the plan.
+
+### 2 — graphify updates automatically
+
+The `PostToolUse` hook runs `graphify update .` after every file edit — no manual step needed. The graph stays current as you write.
+
+### 3 — Stay in scope
+
+If you discover something unexpected that requires scope change:
+- Stop implementing.
+- Flag it: "Discovered: <X>. This is outside the plan scope. Revise plan before continuing?"
+- Wait for direction.
+
+### 4 — When done
+
+State:
+```
+APPLY COMPLETE
+──────────────
+Created:   <files>
+Modified:  <files>
+Skipped:   <anything intentionally deferred>
+```
+
+Then prompt:
+
+> "Ready to /validate. Type `/validate` to check against acceptance criteria."

tools/epav/skills/epav.md

@@ -0,0 +1,46 @@
+# /epav
+
+**E→P→A→V** — Full cycle orchestrator. Runs all four steps in sequence with a gate before APPLY.
+
+## Usage
+
+`/epav <task description, CSV path, or feature name>`
+
+## Cycle
+
+```
+EVALUATE → PLAN → [approval gate] → APPLY → VALIDATE
+```
+
+## Steps
+
+### Step 1 — EVALUATE
+
+Follow the `/evaluate` skill exactly. Output the EVALUATE SUMMARY.
+
+### Step 2 — PLAN
+
+Follow the `/plan` skill exactly. Output the blueprint with blast radius.
+
+**GATE: Stop here. Do not proceed to APPLY until the user explicitly approves.**
+
+Say:
+> "Plan ready. Reply **go** or `/apply` to implement, or give feedback to revise."
+
+### Step 3 — APPLY (only after approval)
+
+Follow the `/apply` skill exactly. Implement the plan step by step.
+
+graphify updates automatically after every file edit via the PostToolUse hook.
+
+### Step 4 — VALIDATE
+
+Follow the `/validate` skill exactly. Check all acceptance criteria, fix all BLOCKERs and FIX NOWs, contribute patterns back to knowledge/.
+
+## Abort at any step
+
+If the user says "stop", "abort", or "cancel" at any point — stop immediately and summarize what was completed and what was not.
+
+## Scope discipline
+
+The EPAV cycle covers **one task at a time**. If additional work surfaces during APPLY, log it to `knowledge/retros/` and finish the current task first.

tools/epav/skills/evaluate.md

@@ -0,0 +1,42 @@
+# /evaluate
+
+**EVALUATE** — Step 1 of the E→P→A→V cycle. Orient fully before writing any plan or code.
+
+## Arguments
+
+`/evaluate <task description, CSV path, or feature name>`
+
+## Steps
+
+### 1 — Orient with graphify (if graph exists)
+
+```bash
+graphify query "<task context from args>"
+```
+
+Note which communities and god nodes are in the blast radius. If no graph exists, suggest `/graphify .` then continue.
+
+### 2 — Load context in priority order
+
+1. **CSV task** — if `docs/dev-tasks/` exists, load the matching row. Fields `user_story`, `description`, `acceptance_criteria`, `dependencies` are the context.
+2. **AGENTS.md** — load coding standards from project root if present.
+3. **Architecture doc** — scan `docs/arch-docs/` for the relevant section.
+4. **knowledge/** — check `knowledge/rules/`, `knowledge/patterns/`, `knowledge/prompts/dev/` for prior patterns.
+
+### 3 — Output this summary, nothing else
+
+```
+EVALUATE SUMMARY
+────────────────
+Task:        <what we are building>
+Touches:     <files / modules / graphify communities>
+Depends on:  <what must already exist>
+Constraints: <from AGENTS.md, arch doc, acceptance criteria>
+Risk:        <god nodes or high-degree nodes in blast radius>
+```
+
+### 4 — Stop
+
+Do NOT plan. Do NOT write code. End with:
+
+> "Ready to /plan. Type `/plan` when you want the implementation blueprint."

tools/epav/skills/plan.md

@@ -0,0 +1,46 @@
+# /plan
+
+**PLAN** — Step 2 of the E→P→A→V cycle. Produce a blueprint. No code yet.
+
+## Prerequisite
+
+EVALUATE must have run first. If it hasn't, run `/evaluate <task>` before continuing.
+
+## Steps
+
+### 1 — Blast radius check
+
+```bash
+graphify path "<primary file/module>" "<secondary file/module>"
+```
+
+Run for every significant file the plan will touch. State what else will be affected.
+
+### 2 — Write the implementation blueprint
+
+Structure the plan as numbered steps:
+
+```
+PLAN
+────
+1. <file or module> — <what changes and why>
+2. <file or module> — <what changes and why>
+...
+
+Files created:   <list>
+Files modified:  <list>
+Files deleted:   <list>
+
+Blast radius:    <from graphify — what else references these>
+God nodes touched: <list any with degree > 10>
+```
+
+### 3 — State constraints
+
+List which AGENTS.md rules and architecture decisions apply to this plan.
+
+### 4 — Stop and wait
+
+Do NOT write code. End with:
+
+> "Waiting for approval. Reply `/apply` to implement, or give feedback to revise the plan."