git-repokit 0.9.10__py3-none-any.whl

repokit/template_engine.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""
+Template engine for RepoKit.
+
+Handles loading and rendering templates from the package's template directory.
+"""
+
+import datetime
+import json
+import os
+import logging
+import re
+import string
+import uuid
+import importlib.resources as resources
+from pathlib import Path
+from typing import Dict, Any, Optional, List, Union
+
+# The second placeholder dialect: __RK_NAME__ tokens, used by the code-type
+# layers (repokit/layers.py) in file contents AND file names, where a `$` is
+# shell-hostile and collides with CMake's ${VAR}, Make's $$ and Actions' ${{ }}.
+# The structure templates (*.template) keep string.Template's $var; both
+# dialects read one context (token_context) so a project has one set of names.
+RK_TOKEN = re.compile(r"__RK_([A-Z_]+?)__")
+
+
+def token_context(context: Dict[str, Any], archetype: Optional[str] = None) -> Dict[str, Any]:
+    """The context plus the RK_* names the token dialect resolves.
+
+    Derived from the same values the $var templates use (project_name,
+    description, author, author_email, the GitHub user), after the proof's
+    assemble.py names(): PROJECT (my-tool), SNAKE (my_tool), MACRO (MY_TOOL),
+    PASCAL (MyTool), ORG, DESCRIPTION, ARCHETYPE, YEAR, DATE, and two GUIDs
+    for Visual Studio files. Call it once per project so every file shares
+    the GUIDs.
+    """
+    name = str(context.get("project_name") or "project")
+    words = [w for w in re.split(r"[-_\s]+", name) if w] or [name]
+    github = context.get("github")
+    # github_org is the repository's owner the structure templates use, so
+    # both dialects name the same owner (0.9.6)
+    org = (context.get("github_org")
+           or context.get("organization")
+           or (github.get("username") if isinstance(github, dict) else None)
+           or context.get("github_user") or "your-org")
+    today = datetime.date.today()
+    tokens = {
+        "RK_PROJECT": name,
+        "RK_SNAKE": "_".join(words).lower(),
+        "RK_MACRO": "_".join(words).upper(),
+        "RK_PASCAL": "".join(w[:1].upper() + w[1:] for w in words),
+        "RK_ORG": str(org),
+        "RK_DESCRIPTION": str(context.get("description") or ""),
+        "RK_ARCHETYPE": archetype or "",
+        "RK_YEAR": str(today.year),
+        "RK_DATE": today.isoformat(),
+        "RK_GUID_PROJECT": str(uuid.uuid4()).upper(),
+        "RK_GUID_SOLUTION": str(uuid.uuid4()).upper(),
+        "RK_AUTHOR": str(context.get("author") or context.get("author_name") or ""),
+        "RK_EMAIL": str(context.get("author_email") or ""),
+        # 0.9.6: the licence the create wrote and the topics as keywords (one
+        # form valid in a TOML or a JSON array). RK_LICENSE is a manifest's
+        # string (plugin.json); the pyproject lines are whole lines (0.9.8,
+        # PEP 639): `license = "<SPDX>"` only for a catalogue licence, and
+        # `license-files` whenever a LICENSE is written, else nothing.
+        "RK_LICENSE": str(context.get("license_expression") or "UNLICENSED"),
+        "RK_LICENSE_FIELD": (f'license = "{context["license_spdx"]}"' if context.get("license_spdx") else ""),
+        "RK_LICENSE_FILES": ('license-files = ["LICENSE"]' if context.get("license_file_written") else ""),
+        "RK_KEYWORDS": ", ".join(json.dumps(str(t)) for t in (context.get("topics") or [])),
+    }
+    return {**context, **tokens}
+
+
+class TemplateEngine:
+    """
+    Template engine for loading and rendering templates.
+    """
+
+    def __init__(self, templates_dir: Optional[str] = None, verbose: int = 0):
+        """
+        Initialize the template engine.
+
+        Args:
+            templates_dir: Path to template directory (or use package's templates)
+            verbose: Verbosity level (0=normal, 1=info, 2=debug)
+        """
+        self.verbose = verbose
+
+        # Configure logging
+        self.logger = logging.getLogger("repokit.templates")
+
+        # Try multiple locations for templates
+        self.templates_dirs = []
+
+        # 1. Use provided template directory if specified
+        if templates_dir:
+            self.templates_dirs.append(templates_dir)
+
+        # 2. Try to find templates in the package via importlib.resources
+        try:
+            pkg_templates = resources.files("repokit").joinpath("templates")
+            # resources.as_file will give us a real filesystem path
+            with resources.as_file(pkg_templates) as tpl_path:
+                self.templates_dirs.append(str(tpl_path))
+        except (ImportError, FileNotFoundError):
+            # either stdlib importlib.resources is missing (very old Python)
+            # or the package isn’t installed with that resource
+            pass
+
+        # 3. Check current script directory
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        self.templates_dirs.append(os.path.join(script_dir, "templates"))
+
+        # 4. Check current working directory
+        cwd_templates = os.path.join(os.getcwd(), "repokit", "templates")
+        self.templates_dirs.append(cwd_templates)
+
+        # 5. Check parent directories (for development mode)
+        current_dir = os.getcwd()
+        for _ in range(3):  # Check up to 3 levels up
+            parent_dir = os.path.dirname(current_dir)
+            if parent_dir == current_dir:  # Reached root
+                break
+            current_dir = parent_dir
+            self.templates_dirs.append(
+                os.path.join(current_dir, "repokit", "templates")
+            )
+
+        # Find first valid template directory
+        self.templates_dir = None
+        for dir_path in self.templates_dirs:
+            if os.path.exists(dir_path) and os.path.isdir(dir_path):
+                self.templates_dir = dir_path
+                break
+
+        if self.templates_dir:
+            if self.verbose >= 1:
+                self.logger.info(f"Using templates from: {self.templates_dir}")
+        else:
+            self.logger.warning(
+                f"No template directory found. Tried: {self.templates_dirs}"
+            )
+            # Use fallback templates
+            self.templates_dir = None
+
+        # Fallback templates for critical files
+        self.fallback_templates = {
+            "common/README.md.template": """# $project_name\n\n$description\n""",
+            "common/gitignore.template": """# Ignore common files\n.DS_Store\n*.log\n""",
+        }
+
+    def get_template_path(
+        self, template_name: str, category: str = "common"
+    ) -> Optional[str]:
+        """
+        Get the path to a template file.
+
+        Args:
+            template_name: Name of the template file
+            category: Category of the template (common, github, languages/python, etc.)
+
+        Returns:
+            Path to the template file or None if not found
+        """
+        if not self.templates_dir:
+            return None
+
+        # Try direct path first (if template_name includes a category)
+        if "/" in template_name:
+            direct_path = os.path.join(self.templates_dir, template_name)
+            if os.path.exists(direct_path):
+                return direct_path
+
+        # Try with .template extension
+        if not template_name.endswith(".template"):
+            template_name = f"{template_name}.template"
+
+        # Look in multiple possible locations
+        possible_paths = []
+
+        # 1. Look in the specified category
+        possible_paths.append(os.path.join(self.templates_dir, category, template_name))
+
+        # 2. Try common category if not found and not already looking there
+        if category != "common":
+            possible_paths.append(
+                os.path.join(self.templates_dir, "common", template_name)
+            )
+
+        # 3. Try languages subdirectory
+        if "/" not in category and not category.startswith("languages/"):
+            possible_paths.append(
+                os.path.join(self.templates_dir, "languages", category, template_name)
+            )
+
+        # 4. Try root templates directory
+        possible_paths.append(os.path.join(self.templates_dir, template_name))
+
+        # Check all possible paths
+        for path in possible_paths:
+            if os.path.exists(path):
+                if self.verbose >= 2:
+                    self.logger.debug(f"Found template at: {path}")
+                return path
+
+        # Log the paths we tried
+        if self.verbose >= 2:
+            self.logger.debug(f"Tried looking for template in: {possible_paths}")
+
+        return None
+
+    def load_template(
+        self, template_name: str, category: str = "common"
+    ) -> Optional[str]:
+        """
+        Load a template file.
+
+        Args:
+            template_name: Name of the template file
+            category: Category of the template (common, github, languages/python, etc.)
+
+        Returns:
+            Template content as string or None if not found
+        """
+        # First try to find the template file
+        template_path = self.get_template_path(template_name, category)
+        if template_path:
+            try:
+                with open(template_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+
+                if self.verbose >= 2:
+                    self.logger.debug(f"Loaded template: {template_path}")
+                return content
+            except Exception as e:
+                self.logger.error(f"Error loading template {template_path}: {str(e)}")
+
+        # If not found, try fallback templates
+        fallback_key = f"{category}/{template_name}"
+        if not fallback_key.endswith(".template"):
+            fallback_key += ".template"
+
+        if fallback_key in self.fallback_templates:
+            if self.verbose >= 1:
+                self.logger.info(f"Using fallback template for: {fallback_key}")
+            return self.fallback_templates[fallback_key]
+
+        # Final fallback for specific template types
+        base_template_name = os.path.basename(template_name)
+        if base_template_name == "README.md.template":
+            return """# $project_name\n\n$description\n"""
+        elif base_template_name == "gitignore.template":
+            return """# Ignore patterns\n*.log\n.DS_Store\n"""
+
+        self.logger.warning(
+            f"Template not found: {template_name} in category {category}"
+        )
+        return None
+
+    def load_template_bytes(self, template_name: str, category: str = "common") -> Optional[bytes]:
+        """load_template, but the file's bytes (a fallback template is UTF-8)."""
+        template_path = self.get_template_path(template_name, category)
+        if template_path:
+            try:
+                with open(template_path, "rb") as f:
+                    return f.read()
+            except OSError as e:
+                self.logger.error(f"Error loading template {template_path}: {str(e)}")
+        text = self.load_template(template_name, category)
+        return text.encode("utf-8") if text is not None else None
+
+    def render_bytes(self, data: bytes, context: Dict[str, Any], dollar: bool) -> bytes:
+        """Substitute placeholders in a file's bytes, changing nothing else.
+
+        latin-1 maps every byte to one character and back, so a BOM, CRLF
+        line endings and bytes outside UTF-8 all survive; the substituted
+        values are encoded as UTF-8 first. With ``dollar`` the $var dialect
+        (string.Template.safe_substitute: unknown and malformed placeholders
+        such as ${CMAKE_VAR}, $<GENEX>, ${{ github }} and $1 are left alone)
+        runs first; the __RK_NAME__ tokens are replaced in every case, and an
+        unknown token is left in place. Proven on both template populations
+        by tests/one-offs/thinking/poc-one-engine/poc_one_engine.py.
+        """
+        values = {k: str(v).encode("utf-8").decode("latin-1") for k, v in context.items()}
+        text = data.decode("latin-1")
+        if dollar:
+            text = string.Template(text).safe_substitute(values)
+        text = RK_TOKEN.sub(lambda m: values.get("RK_" + m.group(1), m.group(0)), text)
+        return text.encode("latin-1")
+
+    def render_template(self, template_content: str, context: Dict[str, Any]) -> str:
+        """
+        Render a template with the given context.
+
+        Args:
+            template_content: Template content as string
+            context: Dictionary of variables for template rendering
+
+        Returns:
+            Rendered template as string
+        """
+        try:
+            template = string.Template(template_content)
+            return template.safe_substitute(context)
+        except Exception as e:
+            self.logger.error(f"Error rendering template: {str(e)}")
+            # Return original content in case of error
+            return template_content
+
+    def render_template_to_file(
+        self,
+        template_name: str,
+        output_path: str,
+        context: Dict[str, Any],
+        category: str = "common",
+        preserve_existing: bool = False,
+    ) -> bool:
+        """
+        Load, render, and write a template to a file.
+
+        Args:
+            template_name: Name of the template file
+            output_path: Path to write the rendered template
+            context: Dictionary of variables for template rendering
+            category: Category of the template (common, github, languages/python, etc.)
+            preserve_existing: If True, don't overwrite existing files
+
+        Returns:
+            True if successful, False otherwise
+        """
+        # Check if file exists and should be preserved
+        if preserve_existing and os.path.exists(output_path):
+            self.logger.info(f"Preserving existing file: {output_path}")
+            return True
+            
+        data = self.load_template_bytes(template_name, category)
+        if not data:
+            return False
+
+        # Bytes in, bytes out: the template's own line endings reach the file
+        # (the templates are pinned to LF by .gitattributes), where the text
+        # path used to write CRLF on Windows.
+        rendered = self.render_bytes(data, context, dollar=True)
+
+        try:
+            # Create directory if it doesn't exist
+            os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+            with open(output_path, "wb") as f:
+                f.write(rendered)
+
+            if self.verbose >= 2:
+                self.logger.debug(f"Rendered template {template_name} to {output_path}")
+            return True
+        except Exception as e:
+            self.logger.error(f"Error writing template to {output_path}: {str(e)}")
+            return False
+
+    def list_templates(self, category: str = None) -> List[str]:
+        """
+        List available templates.
+
+        Args:
+            category: Category to list templates from (or all if None)
+
+        Returns:
+            List of template names
+        """
+        templates = []
+
+        # Return fallback templates if no templates directory
+        if not self.templates_dir:
+            return list(self.fallback_templates.keys())
+
+        if category:
+            category_path = os.path.join(self.templates_dir, category)
+            if os.path.exists(category_path) and os.path.isdir(category_path):
+                for file in os.listdir(category_path):
+                    if file.endswith(".template"):
+                        templates.append(file)
+        else:
+            # List all templates
+            for root, _, files in os.walk(self.templates_dir):
+                for file in files:
+                    if file.endswith(".template"):
+                        rel_path = os.path.relpath(
+                            os.path.join(root, file), self.templates_dir
+                        )
+                        templates.append(rel_path)
+
+        return templates

repokit/templates/ai/claude/CLAUDE-nested.md.template

@@ -0,0 +1,25 @@
+# CLAUDE.md -- $project_name
+
+$description
+
+Guidance for Claude Code sessions in this repository. It stays short: the project's notes, designs and boards live in the private vault.
+
+## Start here
+
+- `private/CLAUDE.md` -- the vault: where the design documents, postmortems, notes and boards are, and how to write there.
+- `README.md` -- what the project is, and how to install, run and test it.
+
+## Commands
+
+Setup:
+
+$setup_block
+
+Tests:
+
+$test_block
+
+## Rules
+
+- `private/` is its own git repository, ignored by this one and never pushed. Commit vault files from inside it, by named path.
+- Commit and push only when the person asks.

repokit/templates/ai/claude/CLAUDE.md.template

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Project**: $project_name
+**Description**: $description
+**Language**: $language
+**Created**: $date
+
+## Common Development Commands
+
+```bash
+# Run tests
+$test_command
+
+# Lint/Format code  
+$lint_command
+
+# Build/Run
+$build_command
+```
+
+## Test Development Guidelines
+
+### Test Script Management
+- **One-off test scripts**: Store in `tests/one-offs/` directory
+- **Test runs**: Always use `test_runs/` directory (not test-runs)
+- **Keep test artifacts**: Don't delete one-off scripts - they may be useful later
+
+Example:
+```bash
+# Create test script
+mkdir -p tests/one-offs
+vim tests/one-offs/test_feature.py
+
+# Run tests that create artifacts
+cd test_runs  # Standardized location
+python test_feature.py
+```
+
+## Architecture Notes
+
+<!-- Add your project-specific architecture notes here -->
+
+## Private Branch Guidelines
+
+### Documentation Requirements
+
+- **ALWAYS** document all work performed in timestamped files under `./private/claude/`
+- Use filename format: `YYYY_MM_DD__HH_MM_SS__(TOPIC).md`
+- Include all commands executed, their outputs, and summaries
+
+### Version Control Practices
+
+- The `private` branch is LOCAL ONLY - never push to remote repositories
+- Commit frequently to track all changes and edits
+- Make minimal edits to preserve diff readability:
+  - Avoid unnecessary variable/function/class name changes
+  - Only rename when truly warranted for clarity or correctness
+  - Preserve existing code structure when possible
+
+### Private Content Structure
+
+```
+private/
+├── claude/         # All Claude-assisted work documentation
+│   ├── instructions/   # Core workflow instructions
+│   └── YYYY_MM_DD__HH_MM_SS__(TOPIC).md
+├── convos/         # Conversation logs (protected from commits)
+└── logs/           # System logs (protected from commits)
+```
+
+## The Dev Workflow Process
+
+When tackling complex problems or making significant decisions, use **THE PROCESS** - a 5-stage systematic approach:
+
+### 🔁 The 5 Stages:
+
+1. **Problem Analysis** - Define and understand the full context
+2. **Conceptual Exploration** - Explore the nature and relationships  
+3. **Brainstorming Solutions** - Generate and evaluate multiple approaches
+4. **Synthesis and Recommendation** - Combine best elements into optimal solution
+5. **Implementation Plan** - Create actionable roadmap
+
+**When to use**: For any complex problem, design decision, bug investigation, or strategic choice.
+
+## Additional Instructions
+
+Detailed workflow instructions are available in `./private/claude/instructions/`:
+- Context rebuilding between sessions
+- The full Dev Workflow Process
+- Creating conversation summaries
+
+## Project-Specific Notes
+
+<!-- Add any project-specific guidelines, patterns, or warnings here -->

repokit/templates/ai/claude/instructions/step1_context_rebuilder.md

@@ -0,0 +1,33 @@
+# Context Rebuilder Instructions
+
+When resuming work or switching between sessions, follow these steps to rebuild context:
+
+## 1. Initial Context Evaluation
+- Review any provided summaries, notes, or partial conversations
+- Identify the main topic/goal and current project status
+- Note important artifacts, files, or references mentioned
+
+## 2. Reconstructing Full Context
+- **Project Objectives**: Clearly restate what is being aimed for
+- **Current Situation**: Summarize current phase, tasks in progress, recent developments
+- **Prior Decisions**: State decisions made with their justification
+- **Known Constraints**: Time, resources, technical limitations
+- **Outstanding Issues**: Open questions, risks, or ambiguities
+
+## 3. Handling Ambiguous Context
+If information is unclear, ask specific questions:
+- "Could you clarify the main objective?"
+- "What is the current status of [specific feature]?"
+- "Are there any critical constraints I should know about?"
+
+## 4. Context Verification
+Summarize the reconstructed context back to confirm accuracy:
+- "Based on the provided information, here's my understanding..."
+- "Please confirm or correct any misunderstandings"
+
+## 5. For Code Projects
+When context is missing, ask for:
+1. Summary of previous conversation
+2. List of project files (`tree` or `ls` output)
+3. Key source files currently being worked on
+4. Any specific technical constraints or requirements

repokit/templates/ai/claude/instructions/step2_dev_workflow_process.md

@@ -0,0 +1,67 @@
+# The Dev Workflow Process (The Process)
+
+A systematic 5-stage approach for tackling complex problems, making design decisions, and solving technical challenges.
+
+## 🔁 The 5 Stages
+
+### 1. Problem Analysis
+> *"Clarify before solving. Understand before deciding."*
+
+- Define the core problem with precision
+- Break into sub-problems or dimensions
+- Explore pros, cons, edge cases, and risks
+- Consider short-term vs long-term implications
+- Identify ambiguities and dependencies
+
+### 2. Conceptual Exploration
+> *"Think about how the system works. What are the forces at play?"*
+
+- Understand WHY the problem exists
+- Explore mental models and analogies
+- Consider different approach types
+- Examine relationships between elements
+- Think systemically about cause and effect
+
+### 3. Brainstorming Solutions
+> *"Don't jump to the first good idea. Explore the option space."*
+
+- Generate 3-5 distinct solutions
+- For each: analyze pros, cons, trade-offs
+- Evaluate feasibility, cost, and risks
+- Consider hybrid approaches
+- Think about edge cases each handles
+
+### 4. Synthesis and Recommendation
+> *"Choose what's most balanced, strategic, and resilient."*
+
+- Combine best elements from various solutions
+- Select approach that best:
+  - Solves the core problem
+  - Handles edge cases
+  - Aligns with long-term goals
+  - Balances constraints
+- Justify with evidence from analysis
+
+### 5. Implementation Plan
+> *"Make it real. Turn insight into execution."*
+
+- Define step-by-step roadmap
+- Include milestones and checkpoints
+- Identify tools and resources needed
+- Plan for contingencies
+- Define success criteria
+
+## When to Use The Process
+
+**Use for:**
+- Complex multi-faceted problems
+- Important design decisions
+- Performance optimization
+- Architecture choices
+- Debugging mysterious issues
+
+**Maybe skip for:**
+- Simple, well-defined tasks
+- Following established patterns
+- Time-critical emergencies (do quick version)
+- Reversible, low-impact changes

repokit/templates/ai/claude/instructions/step3_context_bridge.md

@@ -0,0 +1,52 @@
+# Context Bridge - Conversation Summaries
+
+When approaching token limits or needing to transfer context between sessions, create a structured summary.
+
+## Summary Structure
+
+### 1. Topic Overview
+- Detailed but concise summary of the conversation
+- Main problem, context, and domain area
+
+### 2. Current Situation  
+- What we're working on right now
+- Current step or phase
+- Recent changes or decisions
+
+### 3. Key Artifacts
+- Important files, functions, or systems
+- Code snippets with context
+- External tools or dependencies
+
+### 4. Unresolved Issues
+- Open questions or bugs
+- Assumptions to validate
+- Known risks or concerns
+
+### 5. Next Steps
+- Clear list of pending actions
+- Priority order if applicable
+- Dependencies between tasks
+
+### 6. Assumptions & Constraints
+- Technical constraints
+- Time or resource limits
+- Design assumptions made
+
+### 7. Decisions Made
+- What has been decided
+- What has been ruled out
+- Brief justification
+
+### 8. External References
+- Links, documentation
+- File paths
+- Tool configurations
+
+## Usage Tips
+
+- Make summaries copy-pasteable
+- Include enough context for cold start
+- Focus on actionable information
+- Preserve important reasoning
+- Note any time-sensitive items

repokit/templates/common/CHANGELOG.md.template

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to $project_name are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - $date
+
+### Added
+- The project's structure, from git-repokit.
+
+[Unreleased]: https://github.com/$github_org/$project_name/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/$github_org/$project_name/releases/tag/v0.1.0