devctl 1.2.3__tar.gz → 1.2.4__tar.gz

{devctl-1.2.3 → devctl-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devctl
-Version: 1.2.3
+Version: 1.2.4
 Summary: Local development orchestrator for Spring Boot, Angular, and Vue.js
 Author: Youssef Fellah
 License: MIT License
@@ -29,7 +29,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Build Tools
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typer>=0.12.3
@@ -64,6 +64,9 @@ containerization across Linux, macOS, and Windows.
 -   **Interactive Dashboard**: Real-time system monitoring (CPU/RAM/Disk) and service orchestration with side-by-side log streaming (`devctl tui`).
 -   **Security by Default**: Inject standardized JWT authentication and security
     configurations into new projects.
+-   **AI Agent Context Generation**: Automatically creates and updates `AGENTS.md`,
+    `CLAUDE.md`, and `.cursorrules` on project initialization, aligning coding agents
+    (Claude Code, Cursor, Copilot) with active ports, commands, and contract conventions.
 
 ## Interactive Dashboard (TUI)
 
@@ -153,5 +156,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 for details.
 
 ---
-Authored by Youssef Fellah.
-Professional Development Orchestrator.
+
+## Author
+
+- **Author:** Youssef Fellah ([ind4x_](https://github.com/ind4x))

{devctl-1.2.3 → devctl-1.2.4}/README.md

@@ -21,6 +21,9 @@ containerization across Linux, macOS, and Windows.
 -   **Interactive Dashboard**: Real-time system monitoring (CPU/RAM/Disk) and service orchestration with side-by-side log streaming (`devctl tui`).
 -   **Security by Default**: Inject standardized JWT authentication and security
     configurations into new projects.
+-   **AI Agent Context Generation**: Automatically creates and updates `AGENTS.md`,
+    `CLAUDE.md`, and `.cursorrules` on project initialization, aligning coding agents
+    (Claude Code, Cursor, Copilot) with active ports, commands, and contract conventions.
 
 ## Interactive Dashboard (TUI)
 
@@ -110,5 +113,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 for details.
 
 ---
-Authored by Youssef Fellah.
-Professional Development Orchestrator.
+
+## Author
+
+- **Author:** Youssef Fellah ([ind4x_](https://github.com/ind4x))

{devctl-1.2.3 → devctl-1.2.4}/devctl/commands/init.py

@@ -6,6 +6,7 @@ Django, Svelte, and Go.
 
 import typer
 
+from devctl.generators.agent import generate_agent_context
 from devctl.generators.angular import generate_angular_boilerplate
 from devctl.generators.django import generate_django_boilerplate
 from devctl.generators.fastapi import generate_fastapi_boilerplate
@@ -46,6 +47,7 @@ def init_spring(
 
     if success_download:
         generate_config(name, db_type=db, custom_port=port)
+        generate_agent_context()
         typer.secho("\nSpring project ready!", fg=typer.colors.GREEN)
 
 
@@ -61,6 +63,7 @@ def init_angular(name: str):
     success = generate_angular_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nAngular project ready!", fg=typer.colors.GREEN)
 
 
@@ -75,6 +78,7 @@ def init_vue(name: str):
     success = generate_vue_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nVue.js project ready!", fg=typer.colors.GREEN)
 
 
@@ -89,6 +93,7 @@ def init_nest(name: str):
     success = generate_nest_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nNestJS project ready!", fg=typer.colors.GREEN)
 
 
@@ -103,6 +108,7 @@ def init_nodejs(name: str):
     success = generate_nodejs_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nNodeJS project ready!", fg=typer.colors.GREEN)
 
 
@@ -117,6 +123,7 @@ def init_react(name: str):
     success = generate_react_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nReactJS project ready!", fg=typer.colors.GREEN)
 
 
@@ -131,6 +138,7 @@ def init_nextjs(name: str):
     success = generate_nextjs_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nNextJS project ready!", fg=typer.colors.GREEN)
 
 
@@ -145,6 +153,7 @@ def init_fastapi(name: str):
     success = generate_fastapi_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nFastAPI project ready!", fg=typer.colors.GREEN)
 
 
@@ -159,6 +168,7 @@ def init_django(name: str):
     success = generate_django_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nDjango project ready!", fg=typer.colors.GREEN)
 
 
@@ -173,6 +183,7 @@ def init_svelte(name: str):
     success = generate_svelte_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nSvelte project ready!", fg=typer.colors.GREEN)
 
 
@@ -187,4 +198,18 @@ def init_go(name: str):
     success = generate_go_boilerplate(name)
 
     if success:
+        generate_agent_context()
         typer.secho("\nGo project ready!", fg=typer.colors.GREEN)
+
+
+@app.command("agent")
+def init_agent():
+    """
+    Generates or refreshes AGENTS.md, CLAUDE.md, and .cursorrules for the current project.
+    """
+    success = generate_agent_context()
+    if success:
+        typer.secho("\nAgent context ready!", fg=typer.colors.GREEN)
+    else:
+        typer.secho("\nFailed to generate agent context.", fg=typer.colors.RED)
+        raise typer.Exit(code=1)

devctl-1.2.4/devctl/generators/agent/__init__.py

@@ -0,0 +1,7 @@
+"""
+Agent context generator package.
+"""
+
+from devctl.generators.agent.generator import generate_agent_context
+
+__all__ = ["generate_agent_context"]

devctl-1.2.4/devctl/generators/agent/generator.py

@@ -0,0 +1,269 @@
+"""
+Agent context generator.
+Produces AGENTS.md, CLAUDE.md, and .cursorrules for AI coding assistants.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+import typer
+import yaml
+from jinja2 import Environment, FileSystemLoader
+
+from devctl.generators.docker.scaffolder import IGNORED_DIRECTORIES, discover_docker_projects
+
+FRAMEWORK_METADATA: Dict[str, Dict[str, Any]] = {
+    "spring": {
+        "framework": "Spring Boot",
+        "category": "backend",
+        "default_port": 8080,
+        "run_cmd": "./mvnw spring-boot:run",
+        "test_cmd": "./mvnw test",
+    },
+    "fastapi": {
+        "framework": "FastAPI",
+        "category": "backend",
+        "default_port": 8000,
+        "run_cmd": "uvicorn main:app --reload",
+        "test_cmd": "pytest",
+    },
+    "django": {
+        "framework": "Django",
+        "category": "backend",
+        "default_port": 8000,
+        "run_cmd": "python manage.py runserver",
+        "test_cmd": "python manage.py test",
+    },
+    "nest": {
+        "framework": "NestJS",
+        "category": "backend",
+        "default_port": 3000,
+        "run_cmd": "npm run start:dev",
+        "test_cmd": "npm test",
+    },
+    "nodejs": {
+        "framework": "NodeJS / Express",
+        "category": "backend",
+        "default_port": 3000,
+        "run_cmd": "npm run dev",
+        "test_cmd": "npm test",
+    },
+    "go": {
+        "framework": "Go (Fiber)",
+        "category": "backend",
+        "default_port": 3000,
+        "run_cmd": "go run .",
+        "test_cmd": "go test ./...",
+    },
+    "angular": {
+        "framework": "Angular",
+        "category": "frontend",
+        "default_port": 4200,
+        "run_cmd": "npx ng serve",
+        "test_cmd": "npm test",
+    },
+    "vue": {
+        "framework": "Vue 3",
+        "category": "frontend",
+        "default_port": 5173,
+        "run_cmd": "npm run dev",
+        "test_cmd": "npm test",
+    },
+    "react": {
+        "framework": "React",
+        "category": "frontend",
+        "default_port": 5173,
+        "run_cmd": "npm run dev",
+        "test_cmd": "npm test",
+    },
+    "nextjs": {
+        "framework": "Next.js",
+        "category": "frontend",
+        "default_port": 3000,
+        "run_cmd": "npm run dev",
+        "test_cmd": "npm test",
+    },
+    "svelte": {
+        "framework": "Svelte",
+        "category": "frontend",
+        "default_port": 5173,
+        "run_cmd": "npm run dev",
+        "test_cmd": "npm test",
+    },
+}
+
+
+def _detect_service_port(project_path: Path, kind: str, default_port: int) -> int:
+    """Extract configured service port or fallback to default."""
+    if kind == "spring":
+        props_path = project_path / "src" / "main" / "resources" / "application.properties"
+        if props_path.exists():
+            try:
+                content = props_path.read_text(encoding="utf-8")
+                match = re.search(r"^server\.port\s*=\s*(\d+)", content, re.MULTILINE)
+                if match:
+                    return int(match.group(1))
+            except Exception:
+                pass
+    return default_port
+
+
+def _discover_databases(root: Path) -> List[Dict[str, Any]]:
+    """Scan for docker-compose-db.yml files and extract service configuration."""
+    databases: List[Dict[str, Any]] = []
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in IGNORED_DIRECTORIES]
+        if "docker-compose-db.yml" in filenames:
+            compose_path = Path(dirpath) / "docker-compose-db.yml"
+            try:
+                content = yaml.safe_load(compose_path.read_text(encoding="utf-8")) or {}
+                services = content.get("services", {})
+                for s_name, s_conf in services.items():
+                    image = str(s_conf.get("image", "unknown"))
+                    ports = s_conf.get("ports", [])
+                    host_port = "unknown"
+                    if ports:
+                        raw_port = str(ports[0])
+                        host_port = raw_port.split(":")[0] if ":" in raw_port else raw_port
+
+                    env_vars = s_conf.get("environment", {})
+                    if isinstance(env_vars, list):
+                        parsed_env = {}
+                        for item in env_vars:
+                            if isinstance(item, str) and "=" in item:
+                                k, v = item.split("=", 1)
+                                parsed_env[k.strip()] = v.strip()
+                        env_vars = parsed_env
+
+                    db_user = (
+                        env_vars.get("POSTGRES_USER")
+                        or env_vars.get("MYSQL_USER")
+                        or env_vars.get("MONGO_INITDB_ROOT_USERNAME")
+                        or "admin"
+                    )
+                    db_password = (
+                        env_vars.get("POSTGRES_PASSWORD")
+                        or env_vars.get("MYSQL_PASSWORD")
+                        or env_vars.get("MONGO_INITDB_ROOT_PASSWORD")
+                        or "password"
+                    )
+                    db_name = (
+                        env_vars.get("POSTGRES_DB")
+                        or env_vars.get("MYSQL_DATABASE")
+                        or env_vars.get("MONGO_INITDB_DATABASE")
+                        or "default_db"
+                    )
+
+                    image_lower = image.lower()
+                    if "postgres" in image_lower:
+                        db_type = "PostgreSQL"
+                    elif "mysql" in image_lower:
+                        db_type = "MySQL"
+                    elif "mongo" in image_lower:
+                        db_type = "MongoDB"
+                    else:
+                        db_type = "Database"
+
+                    rel_compose = compose_path.relative_to(root).as_posix()
+                    databases.append(
+                        {
+                            "service_name": s_name,
+                            "db_type": db_type,
+                            "image": image,
+                            "port": host_port,
+                            "db_name": db_name,
+                            "db_user": db_user,
+                            "db_password": db_password,
+                            "compose_file": f"./{rel_compose}",
+                        }
+                    )
+            except Exception:
+                pass
+
+    return databases
+
+
+def generate_agent_context(root_path: Union[str, Path] = ".") -> bool:
+    """
+    Scans the repository and generates AGENTS.md, CLAUDE.md, and .cursorrules.
+    """
+    root = Path(root_path).resolve()
+    if not root.exists() or not root.is_dir():
+        return False
+
+    try:
+        discovered = discover_docker_projects(root)
+    except Exception:
+        discovered = []
+
+    services: List[Dict[str, Any]] = []
+    backends: List[Dict[str, Any]] = []
+    frontends: List[Dict[str, Any]] = []
+
+    for p in discovered:
+        meta = FRAMEWORK_METADATA.get(
+            p.kind,
+            {
+                "framework": p.kind.capitalize(),
+                "category": "backend",
+                "default_port": 8080,
+                "run_cmd": "devctl run",
+                "test_cmd": "npm test",
+            },
+        )
+        port = _detect_service_port(p.path, p.kind, meta["default_port"])
+        try:
+            rel_path = f"./{p.path.relative_to(root).as_posix()}"
+        except ValueError:
+            rel_path = f"./{p.name}"
+
+        service_data = {
+            "name": p.name,
+            "kind": p.kind,
+            "framework": meta["framework"],
+            "category": meta["category"],
+            "relative_path": rel_path,
+            "port": port,
+            "run_cmd": meta["run_cmd"],
+            "test_cmd": meta["test_cmd"],
+        }
+        services.append(service_data)
+        if meta["category"] == "backend":
+            backends.append(service_data)
+        else:
+            frontends.append(service_data)
+
+    databases = _discover_databases(root)
+
+    template_dir = Path(__file__).parent / "templates"
+    env = Environment(loader=FileSystemLoader(str(template_dir)), autoescape=False)
+
+    context = {
+        "services": services,
+        "backends": backends,
+        "frontends": frontends,
+        "databases": databases,
+    }
+
+    try:
+        agents_tpl = env.get_template("AGENTS.md.j2")
+        claude_tpl = env.get_template("CLAUDE.md.j2")
+        cursor_tpl = env.get_template(".cursorrules.j2")
+
+        (root / "AGENTS.md").write_text(agents_tpl.render(context), encoding="utf-8")
+        (root / "CLAUDE.md").write_text(claude_tpl.render(context), encoding="utf-8")
+        (root / ".cursorrules").write_text(cursor_tpl.render(context), encoding="utf-8")
+
+        typer.secho(
+            "Agent context generated (AGENTS.md, CLAUDE.md, .cursorrules).",
+            fg=typer.colors.CYAN,
+        )
+        return True
+    except Exception as e:
+        typer.secho(f"Warning: Failed to generate agent context: {e}", fg=typer.colors.YELLOW)
+        return False

devctl-1.2.4/devctl/generators/agent/templates/AGENTS.md.j2

@@ -0,0 +1,87 @@
+# Project Development Guide for AI Agents
+
+> This project is orchestrated using `devctl`. All commands, multi-tier processes,
+> and scaffolding workflows must adhere to the boundaries documented below.
+
+## 1. Project Architecture & Active Topology
+{% if backends %}
+### Backend Services
+{% for b in backends %}
+- **{{ b.name }}** ({{ b.framework }})
+  - Path: `{{ b.relative_path }}`
+  - Local Port: `{{ b.port }}`
+  - Run Command: `{{ b.run_cmd }}`
+  - Test Suite: `{{ b.test_cmd }}`
+{% endfor %}
+{% endif %}
+{% if frontends %}
+### Frontend Services
+{% for f in frontends %}
+- **{{ f.name }}** ({{ f.framework }})
+  - Path: `{{ f.relative_path }}`
+  - Local Dev Port: `{{ f.port }}`
+  - Run Command: `{{ f.run_cmd }}`
+  - Test Suite: `{{ f.test_cmd }}`
+{% endfor %}
+{% endif %}
+{% if databases %}
+### Databases & Infrastructure
+{% for db in databases %}
+- **Service**: `{{ db.service_name }}`
+  - Type: `{{ db.db_type }}`
+  - Image: `{{ db.image }}`
+  - Host Port: `{{ db.port }}`
+  - Database Name: `{{ db.db_name }}`
+  - Credentials: User=`{{ db.db_user }}`, Password=`{{ db.db_password }}`
+  - Compose File: `{{ db.compose_file }}`
+{% endfor %}
+{% endif %}
+{% if not backends and not frontends and not databases %}
+- Topology: No active microservices detected yet. Run `devctl init <framework> <name>` to add services.
+{% endif %}
+
+## 2. Devctl Orchestration & Lifecycle Commands
+
+Always use `devctl` to orchestrate services. Do NOT start background daemons, manually detached docker processes, or raw ad-hoc runners unless debugging an isolated failure.
+
+- **Start entire stack** (Databases + Backends + Frontends in parallel with unified log streaming):
+  ```bash
+  devctl run
+  ```
+- **Interactive TUI Dashboard** (System metrics, real-time log inspection, process management):
+  ```bash
+  devctl tui
+  ```
+- **Vertical Full-Stack Scaffolding** (Generates Entity, DTOs, Repository, Service, Controller, and Frontend client):
+  ```bash
+  devctl add resource <ResourceName> -f "<field1>:<type>,<field2>:<type>"
+  ```
+- **Containerization & Deployment Scaffolding**:
+  ```bash
+  devctl docker scaffold
+  devctl docker generate
+  ```
+
+## 3. Full-Stack Contract & Coding Conventions
+
+When adding or modifying API endpoints or data models:
+- **API Endpoints**: Use standard RESTful patterns with `/api/v1` prefixes.
+- **DTOs / Contracts**:
+  - Request payloads must be modeled with `<Entity>Request` DTOs.
+  - Response payloads must be modeled with `<Entity>Response` DTOs.
+- **Type Compatibility**:
+  - Backend numeric IDs / Long / Integer -> Frontend TypeScript `number`
+  - Backend UUID / String -> Frontend TypeScript `string`
+  - Backend Instant / LocalDateTime / DateTime -> Frontend TypeScript `string` (ISO 8601 formatted)
+  - Backend Boolean -> Frontend TypeScript `boolean`
+- **Synchronization**: Any change to backend DTO fields or endpoints MUST be immediately reflected in the corresponding frontend API client, models, and interfaces.
+
+## 4. Agent Operational Guardrails
+
+- **Process Management**: Do NOT run detached background processes (`nohup`, `&`, `screen`, `tmux`) that outlive the session. Use `devctl run` for execution.
+- **Testing Before Completion**: Always run the respective test suite for modified services before concluding any task:
+{% for s in services %}
+  - `{{ s.name }}`: `{{ s.test_cmd }}`
+{% endfor %}
+- **Docker Compose Boundaries**: Do NOT alter database port mappings in `docker-compose-db.yml` without updating application configuration files in lockstep.
+- **Dependency Checks**: Ensure required tools are available using `devctl` verification conventions before executing framework-specific build scripts.

devctl-1.2.4/devctl/generators/agent/templates/CLAUDE.md.j2

@@ -0,0 +1,8 @@
+# Claude Code Guidelines
+
+This project is managed and orchestrated by `devctl`.
+
+- Review [AGENTS.md](AGENTS.md) for complete architecture topology, active services, port allocations, and devctl lifecycle commands.
+- Use `devctl run` to boot services and `devctl add resource` for full-stack CRUD scaffolding.
+- Ensure backend DTOs and frontend TypeScript interfaces remain strictly synchronized.
+- Execute unit and integration tests before finishing tasks.

{devctl-1.2.3 → devctl-1.2.4}/devctl/tui/app.py

@@ -55,6 +55,7 @@ from devctl.commands.init import (
     generate_svelte_boilerplate,
     generate_vue_boilerplate,
 )
+from devctl.generators.agent import generate_agent_context
 from devctl.generators.docker import discover_docker_projects, scaffold_docker_assets
 from devctl.orchestrator.config_builder import generate_config
 from devctl.orchestrator.process_manager import ProcessManager
@@ -789,6 +790,7 @@ class DevctlTUI(App):
                     generate_go_boilerplate(name)
                 else:
                     print(f"Error: Unknown framework boilerplate '{framework}'")
+                generate_agent_context(".")
                 print("\nProject initialized successfully!")
         except Exception as e:
             print(f"Error during initialization: {e}", file=f)