pdd-cli 0.0.45__py3-none-any.whl → 0.0.118__py3-none-any.whl

pdd/template_expander.py

@@ -0,0 +1,161 @@
+# pdd/template_expander.py
+"""
+Template expansion utility for output path configuration.
+
+This module provides a function to expand path templates with placeholders
+like {name}, {category}, {ext}, etc. It enables extensible project layouts
+for different languages and frameworks (Python, TypeScript, Vue, Go, etc.).
+
+Supported placeholders:
+    {name}        - Base name (last segment of input path)
+    {category}    - Parent path segments (empty if none)
+    {dir_prefix}  - Full input directory prefix with trailing /
+    {ext}         - File extension from language (e.g., "py", "tsx")
+    {language}    - Full language name (e.g., "python", "typescript")
+    {name_snake}  - snake_case version of name
+    {name_pascal} - PascalCase version of name
+    {name_kebab}  - kebab-case version of name
+
+Example:
+    >>> expand_template(
+    ...     "frontend/src/components/{category}/{name}/{name}.tsx",
+    ...     {"name": "AssetCard", "category": "marketplace"}
+    ... )
+    'frontend/src/components/marketplace/AssetCard/AssetCard.tsx'
+"""
+
+import re
+import os
+from typing import Dict, Any
+
+
+def _to_snake_case(s: str) -> str:
+    """
+    Convert string to snake_case.
+
+    Handles PascalCase, camelCase, and existing snake_case.
+
+    Examples:
+        AssetCard -> asset_card
+        assetCard -> asset_card
+        already_snake -> already_snake
+    """
+    if not s:
+        return s
+    # Insert underscore before uppercase letters (except at start)
+    result = re.sub(r'(?<!^)(?=[A-Z])', '_', s)
+    return result.lower()
+
+
+def _to_pascal_case(s: str) -> str:
+    """
+    Convert string to PascalCase.
+
+    Handles snake_case, kebab-case, and existing PascalCase.
+
+    Examples:
+        asset_card -> AssetCard
+        asset-card -> AssetCard
+        AssetCard -> Assetcard (note: re-capitalizes)
+    """
+    if not s:
+        return s
+    # Split on underscores, hyphens, or other common delimiters
+    parts = re.split(r'[_\-\s]+', s)
+    return ''.join(part.title() for part in parts if part)
+
+
+def _to_kebab_case(s: str) -> str:
+    """
+    Convert string to kebab-case.
+
+    Handles PascalCase, camelCase, and existing kebab-case.
+
+    Examples:
+        AssetCard -> asset-card
+        assetCard -> asset-card
+        already-kebab -> already-kebab
+    """
+    if not s:
+        return s
+    # Insert hyphen before uppercase letters (except at start)
+    result = re.sub(r'(?<!^)(?=[A-Z])', '-', s)
+    return result.lower()
+
+
+def _normalize_path(path: str) -> str:
+    """
+    Normalize a path to remove double slashes and resolve . and ..
+
+    This handles edge cases like empty {category} producing paths like:
+    "src/components//Button" -> "src/components/Button"
+
+    Unlike os.path.normpath, this preserves relative paths without
+    converting them to absolute paths.
+    """
+    if not path:
+        return path
+
+    # Split path and filter empty segments (which cause double slashes)
+    parts = path.split('/')
+    normalized_parts = [p for p in parts if p]
+
+    # Rejoin with single slashes
+    result = '/'.join(normalized_parts)
+
+    # Use os.path.normpath for additional cleanup (handles . and ..)
+    # but it converts to OS-specific separators, so convert back
+    result = os.path.normpath(result)
+
+    # On Windows, normpath uses backslashes; convert back to forward slashes
+    result = result.replace('\\', '/')
+
+    return result
+
+
+def expand_template(template: str, context: Dict[str, Any]) -> str:
+    """
+    Expand a path template with placeholder values.
+
+    Args:
+        template: Path template with {placeholder} syntax
+        context: Dictionary of values to substitute
+
+    Returns:
+        Expanded path with normalized slashes
+
+    Example:
+        >>> expand_template(
+        ...     "frontend/src/components/{category}/{name}/{name}.tsx",
+        ...     {"name": "AssetCard", "category": "marketplace"}
+        ... )
+        'frontend/src/components/marketplace/AssetCard/AssetCard.tsx'
+    """
+    # Get base values from context (with empty string defaults)
+    name = context.get('name', '')
+    category = context.get('category', '')
+    dir_prefix = context.get('dir_prefix', '')
+    ext = context.get('ext', '')
+    language = context.get('language', '')
+
+    # Build the full set of available placeholders
+    placeholders = {
+        'name': name,
+        'category': category,
+        'dir_prefix': dir_prefix,
+        'ext': ext,
+        'language': language,
+        'name_snake': _to_snake_case(name),
+        'name_pascal': _to_pascal_case(name),
+        'name_kebab': _to_kebab_case(name),
+    }
+
+    # Perform substitution
+    result = template
+    for key, value in placeholders.items():
+        result = result.replace(f'{{{key}}}', str(value))
+
+    # Normalize the path to handle empty segments (double slashes)
+    result = _normalize_path(result)
+
+    return result

pdd/template_registry.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import re
+import shutil
+from collections.abc import Iterable as IterableABC
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from importlib.resources import as_file
+
+try:
+    from importlib.resources import files as pkg_files
+except ImportError:  # pragma: no cover
+    # Fallback for Python < 3.11 if needed.
+    from importlib_resources import files as pkg_files  # type: ignore[attr-defined]
+
+
+_FRONT_MATTER_PATTERN = re.compile(r"^---\s*\r?\n(.*?)\r?\n---\s*\r?\n?", re.DOTALL)
+_SOURCE_PRIORITY = {"packaged": 0, "project": 1}
+
+
+@dataclass
+class TemplateMeta:
+    name: str
+    path: Path
+    description: str = ""
+    version: str = ""
+    tags: List[str] = field(default_factory=list)
+    language: str = ""
+    output: str = ""
+    variables: Dict[str, Any] = field(default_factory=dict)
+    usage: Dict[str, Any] = field(default_factory=dict)
+    discover: Dict[str, Any] = field(default_factory=dict)
+    output_schema: Dict[str, Any] = field(default_factory=dict)
+    notes: str = ""
+    source: str = "packaged"
+
+    @property
+    def alias(self) -> str:
+        return self.path.stem
+
+
+def _safe_load_yaml(text: str) -> Optional[Dict[str, Any]]:
+    try:
+        import yaml  # type: ignore
+    except ImportError as exc:  # pragma: no cover - PyYAML is an install requirement
+        raise RuntimeError("PyYAML is required to parse template front matter") from exc
+
+    try:
+        data = yaml.safe_load(text) or {}
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _parse_front_matter(text: str) -> Tuple[Optional[Dict[str, Any]], str]:
+    match = _FRONT_MATTER_PATTERN.match(text)
+    if not match:
+        return None, text
+    meta_text = match.group(1)
+    rest = text[match.end():]
+    meta = _safe_load_yaml(meta_text)
+    return meta, rest
+
+
+def _normalize_tags(tags: Any) -> List[str]:
+    if tags is None:
+        return []
+    if isinstance(tags, str):
+        return [tags.lower()]
+    if isinstance(tags, IterableABC):
+        normalized: List[str] = []
+        for tag in tags:
+            if tag is None:
+                continue
+            normalized.append(str(tag).lower())
+        return normalized
+    return []
+
+
+def _ensure_mapping(value: Any) -> Dict[str, Any]:
+    if isinstance(value, dict):
+        return dict(value)
+    return {}
+
+
+def _normalize_meta(raw: Dict[str, Any], path: Path, source: str) -> TemplateMeta:
+    name = str(raw.get("name") or path.stem)
+    description = str(raw.get("description") or "")
+    version = str(raw.get("version") or "")
+    language = str(raw.get("language") or "")
+    output = str(raw.get("output") or "")
+    tags = _normalize_tags(raw.get("tags"))
+    notes_raw = raw.get("notes")
+    notes = "" if notes_raw is None else str(notes_raw)
+
+    return TemplateMeta(
+        name=name,
+        path=path.resolve(),
+        description=description,
+        version=version,
+        tags=tags,
+        language=language,
+        output=output,
+        variables=_ensure_mapping(raw.get("variables")),
+        usage=_ensure_mapping(raw.get("usage")),
+        discover=_ensure_mapping(raw.get("discover")),
+        output_schema=_ensure_mapping(raw.get("output_schema")),
+        notes=notes,
+        source=source,
+    )
+
+
+def _iter_project_templates() -> Iterable[Path]:
+    root = Path.cwd() / "prompts"
+    if not root.exists():
+        return ()
+    return (path for path in root.rglob("*.prompt") if path.is_file())
+
+
+def _iter_packaged_templates() -> Iterable[Path]:
+    try:
+        pkg_root = pkg_files("pdd").joinpath("templates")
+    except ModuleNotFoundError:  # pragma: no cover - package missing
+        return ()
+    if not pkg_root.is_dir():
+        return ()
+
+    resolved: List[Path] = []
+    for entry in pkg_root.rglob("*.prompt"):  # type: ignore[attr-defined]
+        try:
+            with as_file(entry) as concrete:
+                path = Path(concrete)
+                if path.is_file():
+                    resolved.append(path)
+        except FileNotFoundError:
+            continue
+    return resolved
+
+
+def _load_meta_from_path(path: Path, source: str) -> Optional[TemplateMeta]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    front_matter, _ = _parse_front_matter(text)
+    if not front_matter:
+        return None
+    return _normalize_meta(front_matter, path, source)
+
+
+def _index_templates() -> Tuple[Dict[str, TemplateMeta], Dict[str, TemplateMeta]]:
+    by_name: Dict[str, TemplateMeta] = {}
+    priority: Dict[str, int] = {}
+
+    def register(meta: TemplateMeta) -> None:
+        current_priority = priority.get(meta.name, -1)
+        new_priority = _SOURCE_PRIORITY.get(meta.source, 0)
+        if new_priority < current_priority:
+            return
+        by_name[meta.name] = meta
+        priority[meta.name] = new_priority
+
+    for path in _iter_packaged_templates():
+        meta = _load_meta_from_path(Path(path), "packaged")
+        if meta:
+            register(meta)
+
+    for path in _iter_project_templates():
+        meta = _load_meta_from_path(Path(path), "project")
+        if meta:
+            register(meta)
+
+    lookup = dict(by_name)
+    lookup_priority = priority.copy()
+
+    for meta in by_name.values():
+        alias = meta.alias
+        alias_priority = lookup_priority.get(alias, -1)
+        meta_priority = priority.get(meta.name, 0)
+        if alias_priority <= meta_priority:
+            lookup[alias] = meta
+            lookup_priority[alias] = meta_priority
+
+    return by_name, lookup
+
+
+def _meta_to_payload(meta: TemplateMeta) -> Dict[str, Any]:
+    return {
+        "name": meta.name,
+        "path": str(meta.path),
+        "description": meta.description,
+        "version": meta.version,
+        "tags": list(meta.tags),
+        "language": meta.language,
+        "output": meta.output,
+        "variables": dict(meta.variables),
+        "usage": dict(meta.usage),
+        "discover": dict(meta.discover),
+        "output_schema": dict(meta.output_schema),
+        "notes": meta.notes,
+    }
+
+
+def list_templates(filter_tag: Optional[str] = None) -> List[Dict[str, Any]]:
+    by_name, _ = _index_templates()
+    normalized_tag = filter_tag.lower() if filter_tag else None
+    items: List[Dict[str, Any]] = []
+    for meta in by_name.values():
+        if normalized_tag and normalized_tag not in meta.tags:
+            continue
+        items.append({
+            "name": meta.name,
+            "path": str(meta.path),
+            "description": meta.description,
+            "version": meta.version,
+            "tags": list(meta.tags),
+        })
+    items.sort(key=lambda item: item["name"].lower())
+    return items
+
+
+def load_template(name: str) -> Dict[str, Any]:
+    _, lookup = _index_templates()
+    meta = lookup.get(name)
+    if not meta:
+        raise FileNotFoundError(f"Template '{name}' not found.")
+    return _meta_to_payload(meta)
+
+
+def show_template(name: str) -> Dict[str, Any]:
+    meta = load_template(name)
+    summary = {
+        "name": meta["name"],
+        "path": meta["path"],
+        "description": meta.get("description", ""),
+        "version": meta.get("version", ""),
+        "tags": meta.get("tags", []),
+        "language": meta.get("language", ""),
+        "output": meta.get("output", ""),
+    }
+    return {
+        "summary": summary,
+        "variables": meta.get("variables", {}),
+        "usage": meta.get("usage", {}),
+        "discover": meta.get("discover", {}),
+        "output_schema": meta.get("output_schema", {}),
+        "notes": meta.get("notes", ""),
+    }
+
+
+def copy_template(name: str, dest_dir: str) -> str:
+    meta = load_template(name)
+    src = Path(meta["path"])
+    if not src.exists():
+        raise FileNotFoundError(f"Template '{name}' file is missing at {src}")
+    dest_root = Path(dest_dir)
+    dest_root.mkdir(parents=True, exist_ok=True)
+    dest_path = dest_root / src.name
+    shutil.copy2(src, dest_path)
+    return str(dest_path.resolve())

pdd/templates/architecture/architecture_json.prompt

@@ -0,0 +1,237 @@
+---
+name: architecture/architecture_json
+description: Unified architecture template for multiple tech stacks
+version: 1.0.0
+tags: [architecture, template, json]
+language: json
+output: architecture.json
+post_process_python: ./pdd/render_mermaid.py
+post_process_args:
+  - "{INPUT_FILE}"
+  - "{APP_NAME}"
+  - "{OUTPUT_HTML}"
+variables:
+  APP_NAME:
+    required: false
+    type: string
+    description: Optional app name for context.
+    example: Shop
+  PRD_FILE:
+    required: true
+    type: path
+    description: Primary product requirements document (PRD) describing scope and goals.
+    example_paths: [PRD.md, docs/specs.md, docs/product/prd.md]
+    example_content: |
+      Title: Order Management MVP
+      Goals: Enable customers to create and track orders end-to-end.
+      Key Features:
+        - Create Order: id, user_id, items[], total, status
+        - View Order: details page with status timeline
+        - List Orders: filter by status, date, user
+      Non-Functional Requirements:
+        - P95 latency < 300ms for read endpoints
+        - Error rate < 0.1%
+  TECH_STACK_FILE:
+    required: false
+    type: path
+    description: Tech stack overview (languages, frameworks, infrastructure, and tools).
+    example_paths: [docs/tech_stack.md, docs/architecture/stack.md]
+    example_content: |
+      Backend: Python (FastAPI), Postgres (SQLAlchemy), PyTest
+      Frontend: Next.js (TypeScript), shadcn/ui, Tailwind CSS
+      API: REST
+      Auth: Firebase Auth (GitHub Device Flow), JWT for API
+      Infra: Vercel (frontend), Cloud Run (backend), Cloud SQL (Postgres)
+      Observability: OpenTelemetry traces, Cloud Logging
+  DOC_FILES:
+    required: false
+    type: list
+    description: Additional documentation files (comma/newline-separated).
+    example_paths: [docs/ux.md, docs/components.md]
+    example_content: |
+      Design overview, patterns and constraints
+  INCLUDE_FILES:
+    required: false
+    type: list
+    description: Specific source files to include (comma/newline-separated).
+    example_paths: [src/app.py, src/api.py, frontend/app/layout.tsx, frontend/app/page.tsx]
+usage:
+  generate:
+    - name: Minimal (PRD only)
+      command: pdd generate --template architecture/architecture_json -e PRD_FILE=docs/specs.md --output architecture.json
+    - name: With tech stack overview
+      command: pdd generate --template architecture/architecture_json -e PRD_FILE=docs/specs.md -e TECH_STACK_FILE=docs/tech_stack.md --output architecture.json
+
+discover:
+  enabled: false
+  max_per_pattern: 5
+  max_total: 10
+
+output_schema:
+  type: array
+  items:
+    type: object
+    required: [reason, description, dependencies, priority, filename, filepath]
+    properties:
+      reason: { type: string }
+      description: { type: string }
+      dependencies: { type: array, items: { type: string } }
+      priority: { type: integer, minimum: 1 }
+      filename: { type: string }
+      filepath: { type: string }
+      tags: { type: array, items: { type: string } }
+      interface:
+        type: object
+        properties:
+          type: { type: string, enum: [component, page, module, api, graphql, cli, job, message, config] }
+          component: { type: object }
+          page:
+            type: object
+            properties:
+              route: { type: string }
+              params:
+                type: array
+                items:
+                  type: object
+                  required: [name, type]
+                  properties:
+                    name: { type: string }
+                    type: { type: string }
+                    description: { type: string }
+              dataSources:
+                type: array
+                items:
+                  type: object
+                  required: [kind, source]
+                  properties:
+                    kind: { type: string, enum: [api, query, stream, file, cache, message, job, other] }
+                    source: { type: string }
+                    method: { type: string }
+                    description: { type: string }
+                    auth: { type: string }
+                    inputs: { type: array, items: { type: string } }
+                    outputs: { type: array, items: { type: string } }
+                    refreshInterval: { type: string }
+                    notes: { type: string }
+              layout: { type: object }
+          module: { type: object }
+          api: { type: object }
+          graphql: { type: object }
+          cli: { type: object }
+          job: { type: object }
+          message: { type: object }
+          config: { type: object }
+---
+
+Purpose: Produce an architecture JSON that enumerates prompt files to generate code files for the project.
+
+<PRD_FILE><include>${PRD_FILE}</include></PRD_FILE>
+<TECH_STACK_FILE><include>${TECH_STACK_FILE}</include></TECH_STACK_FILE>
+<DOC_FILES><include-many>${DOC_FILES}</include-many></DOC_FILES>
+
+<INCLUDE_FILES><include-many>${INCLUDE_FILES}</include-many></INCLUDE_FILES>
+
+INSTRUCTIONS:
+- Use only the facts from the included documents and files. Do not invent technologies or filenames.
+- If TECH_STACK_FILE is absent, infer a reasonable tech stack from the PRD and included files; state key assumptions within each item's description.
+- Output a single top-level JSON array of items. Each item must include:
+  - reason (briefly explain why this code module needs to exist), description, dependencies (filenames), priority (1 = highest), filename, filepath, optional tags.
+  - interface: include only the applicable sub-object (component, page, module, api, graphql, cli, job, message, or config). Omit all non-applicable sub-objects entirely.
+  - When interface.type is "page", each entry in `dataSources` must be an object with at least `kind` and `source` (e.g., URL or identifier). The `kind` field MUST be exactly one of: `"api"`, `"query"`, `"stream"`, `"file"`, `"cache"`, `"message"`, `"job"`, or `"other"`. Do not invent new values like `"api/mutation"`; instead, use `"api"` (for any HTTP/REST/GraphQL endpoint) or `"other"` and describe details such as queries vs. mutations in `description` or `notes`. Provide `method`, `description`, and any other useful metadata when known.
+- Valid JSON only. No comments or trailing commas.
+
+OUTPUT FORMAT - CRITICAL: Return a raw JSON array, NOT an object with "items" or "data" wrapper:
+```json
+[
+  {
+    "reason": "Core data models needed by all other modules",
+    "description": "Defines Order, User, and Item data models with validation",
+    "dependencies": [],
+    "priority": 1,
+    "filename": "models_Python.prompt",
+    "filepath": "src/models.py",
+    "tags": ["backend", "data"],
+    "interface": {
+      "type": "module",
+      "module": {
+        "functions": [
+          {"name": "Order", "signature": "class Order(BaseModel)", "returns": "Order instance"}
+        ]
+      }
+    }
+  },
+  {
+    "reason": "API endpoints for order management",
+    "description": "REST API for creating, reading, updating orders",
+    "dependencies": ["models_Python.prompt"],
+    "priority": 2,
+    "filename": "orders_api_Python.prompt",
+    "filepath": "src/api/orders.py",
+    "tags": ["backend", "api"],
+    "interface": {
+      "type": "api",
+      "api": {
+        "endpoints": [
+          {"method": "POST", "path": "/orders", "auth": "jwt"},
+          {"method": "GET", "path": "/orders/{id}", "auth": "jwt"}
+        ]
+      }
+    }
+  }
+]
+```
+WRONG (do NOT do this):
+```json
+{"items": [...]}  // WRONG - no wrapper objects!
+{"data": [...]}   // WRONG - no wrapper objects!
+{"type": "array", "items": [...]}  // WRONG - this is schema, not output!
+```
+
+INTERFACE TYPES (emit only applicable):
+- page: route (string), params? (array of {name, type, description?}), dataSources? (array), layout? (object)
+- component: props (array of {name, type, required?}), emits? (array), context? (array)
+- module: functions (array of {name, signature, returns?, errors?, sideEffects?})
+- api: endpoints (array of {method, path, auth?, requestSchema?, responseSchema?, errors?})
+- graphql: sdl? (string) or operations {queries?[], mutations?[], subscriptions?[]}
+- cli: commands (array of {name, args?[], flags?[], exitCodes?[]}), io? {stdin?, stdout?}
+- job: trigger {schedule? | event?}, inputs? (array), outputs? (array), retryPolicy? (string)
+- message: topics (array of {name, direction: "publish"|"subscribe", schema?, qos?})
+- config: keys (array of {name, type, default?, required?, source: "env"|"file"|"secret"})
+
+FILENAME CONVENTIONS:
+- The "filename" field is the prompt filename to generate (not the code file). Use PDD convention: <base>_<LangOrFramework>.prompt where <LangOrFramework> matches the tech stack.
+- Examples (adapt to your stack):
+  - Next.js (TypeScript React): page_TypeScriptReact.prompt -> generates page.tsx; layout_TypeScriptReact.prompt -> layout.tsx
+  - Python backend: api_Python.prompt -> api.py; orders_Python.prompt -> orders.py
+- Choose descriptive <base> names (e.g., orders_page, orders_api) and keep names consistent across dependencies.
+
+FILEPATH CONVENTIONS:
+- The "filepath" field specifies the path of the output source file from the source tree root, using conventions appropriate for the language and framework.
+- Examples (adapt to your stack):
+  - Next.js app router: app/orders/page.tsx, app/layout.tsx, app/api/orders/route.ts
+  - Next.js pages router: pages/orders.tsx, pages/api/orders.ts
+  - Python FastAPI: src/api.py, src/orders.py, src/models/order.py
+  - React components: src/components/OrderList.tsx, src/hooks/useOrders.ts
+  - Config files: .env.example, pyproject.toml, package.json
+- Use forward slashes (/) for path separators regardless of OS.
+- Include the appropriate file extension for the target language (.tsx, .py, .rs, .go, etc.).
+- Follow standard directory structures for the framework (e.g., app/ for Next.js 13+, src/ for typical React/Python projects).
+
+DEPENDENCY RULES:
+- The "dependencies" array must list other items by their prompt filenames (the "filename" values), not code filenames.
+- Do not reference files that are not part of this array unless they were explicitly provided via INCLUDE_FILES/DOC_FILES.
+- Avoid cycles; if a cycle is necessary, justify it in the description and clarify initialization order.
+
+PRIORITY AND ORDERING:
+- Use unique integer priorities starting at 1 without gaps (1,2,3,...).
+- Sort the top-level array by ascending priority.
+
+TAGS (optional):
+- Use short, lower-case tags for slicing (e.g., ["frontend","nextjs"], ["backend","api"], ["config"]).
+
+CONTENT GUIDANCE:
+- Descriptions must be architectural and actionable: responsibilities, interfaces, error handling, cross-cutting concerns.
+- For API items, outline endpoints (method, path, auth) and high-level request/response shapes.
+- For page/component items, include the route, key props, and data sources.
+
+DO NOT INCLUDE the schema or these conventions in the output; return only the JSON array.