boilersync 0.1.1__tar.gz

boilersync-0.1.1/.cursor/rules/adding-commands.mdc

@@ -0,0 +1,25 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+Add commands to the `commands` dir. To define a command, name the python file after the command, e.g. `my_function.py`, and declare it with e.g.:
+
+```python
+def my_function(argument1: str) -> None:
+    ...logic here...
+
+
+@click.command(name="my-function")
+@click.argument("argument1")
+def my_function_cmd(argument1: str):
+    """Documentation goes here
+    """
+    my_function(argument1)
+```
+
+Then register it in `cli.py` with e.g.:
+
+```python
+main.add_command(common_command_wrapper(my_function_cmd))
+```

boilersync-0.1.1/.cursor/rules/project-description.mdc

@@ -0,0 +1,6 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+`boilersync` is a boilerplate CLI tool that can not only generate projects from boilerplate templates, but keep the boilerplate "alive" and updated as you continue to develop the derivative projects.

boilersync-0.1.1/.cursor/rules/python-conventions.mdc

@@ -0,0 +1,8 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+Only use `try` and `except` when you are truly implementing recovery-from-failure logic.
+Prefer `pathlib` over `os` operations for dealing with files/paths.
+Prefer `logger` calls over `print`.

boilersync-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*" # Only runs on version tags like v1.0.0
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    permissions: write-all
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine hatch
+
+      - name: Build PyPI package
+        run: hatch build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+
+  build-homebrew:
+    runs-on: macos-latest
+    permissions: write-all
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install pyinstaller
+
+      - name: Run PyInstaller build script
+        run: bash scripts/build.sh
+
+      - name: Create binary tarball
+        run: tar -czf boilersync.tar.gz -C dist/boilersync .
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: boilersync-binary
+          path: boilersync.tar.gz
+          retention-days: 5
+
+      - name: Upload to Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: boilersync.tar.gz
+
+      - name: Update Homebrew formula
+        uses: dawidd6/action-homebrew-bump-formula@v4
+        with:
+          token: ${{secrets.GH_TOKEN}}
+          # Optional, use the origin repository instead of forking
+          no_fork: true
+          # Optional, defaults to homebrew/core
+          tap: montaguegabe/homebrew-boilersync
+          # Formula name, required
+          formula: boilersync

boilersync-0.1.1/.gitignore

@@ -0,0 +1,186 @@
+.data/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.gha
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+# .vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+staticfiles
+
+.env
+_version.py
+
+playground/

boilersync-0.1.1/.vscode/launch.json

@@ -0,0 +1,35 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Pytest",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "args": [
+                "tests",
+                "-q",
+                "--tb=native",
+                "-s",
+                "-x"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "env": {
+                "PYTEST_ADDOPTS": "--no-cov"
+            }
+        },
+        {
+            "name": "Boilersync (zebra-crossing)",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "boilersync",
+            "args": [
+                "push"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "cwd": "${workspaceFolder}/playground/zebra-crossing"
+        }
+    ]
+}

boilersync-0.1.1/.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+    "python.testing.pytestArgs": [
+        ".",
+        "--no-cov",
+        "-q",
+        "--tb=native",
+        "-s",
+        "-x"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.experiments.optInto": [
+        "pythonTestAdapter"
+    ],
+    "python.experiments.enabled": true,
+    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
+}

boilersync-0.1.1/.vscode/tasks.json

@@ -0,0 +1,20 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Run pytest with coverage",
+            "type": "shell",
+            "command": "${workspaceFolder}/venv/bin/pytest . --cov=boilersync --cov-report=html && open htmlcov/index.html",
+            "group": {
+                "kind": "test",
+                "isDefault": true
+            },
+            "presentation": {
+                "reveal": "always",
+                "panel": "new",
+                "close": true
+            },
+            "problemMatcher": []
+        }
+    ]
+}

boilersync-0.1.1/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: boilersync
+Version: 0.1.1
+Summary: BoilerSync
+Project-URL: Repository, https://github.com/gabemontague/boilersync
+Project-URL: Issues, https://github.com/gabemontague/boilersync/issues
+Author-email: Gabe Montague <gabemontague@outlook.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Requires-Dist: click>=8.2.0
+Requires-Dist: gitpython>=3.1.44
+Requires-Dist: jinja2>=3.1.6
+Provides-Extra: dev
+Requires-Dist: pyinstaller>=6.9.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Requires-Dist: ruff>=0.11.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# boilersync
+
+`boilersync` is a boilerplate CLI tool that can not only generate projects from boilerplate templates, but keep the boilerplate "alive" and updated as you continue to develop the derivative projects.
+
+## Quick Start
+
+```bash
+# Initialize a new project from a template
+boilersync init my-template-name
+
+# Show pusherences between your project and the original template
+boilersync push
+```
+
+When you run the init command, you'll be prompted for project details:
+
+```bash
+$ boilersync init my-web-app
+
+🚀 Initializing project from template 'my-web-app'
+==================================================
+Project name (snake_case) [my_awesome_project]: my_cool_app
+Pretty name for display [My Cool App]: My Cool Application
+==================================================
+```
+
+## Template System
+
+### Project Name Variables
+
+When initializing a project, `boilersync` prompts you for a snake_case project name and a pretty display name, then generates variables in pusherent naming conventions:
+
+**For file/folder names (uppercase, no special symbols):**
+
+- `NAME_SNAKE`: `my_awesome_project`
+- `NAME_PASCAL`: `MyAwesomeProject`
+- `NAME_KEBAB`: `my-awesome-project`
+- `NAME_CAMEL`: `myAwesomeProject`
+- `NAME_PRETTY`: `My Awesome Project`
+
+**For file contents (lowercase, used with Jinja2 delimiters):**
+
+- `name_snake`: `my_awesome_project`
+- `name_pascal`: `MyAwesomeProject`
+- `name_kebab`: `my-awesome-project`
+- `name_camel`: `myAwesomeProject`
+- `name_pretty`: `My Awesome Project`
+
+### File and Folder Name Interpolation
+
+Use the naming variables directly in file and folder names:
+
+```
+src/NAME_SNAKE_service.py → src/my_awesome_project_service.py
+docs/NAME_KEBAB-guide.md → docs/my-awesome-project-guide.md
+NAME_PASCAL/ → MyAwesomeProject/
+```
+
+### Template Content Processing
+
+Template files use custom Jinja2 delimiters to avoid conflicts:
+
+- **Variables**: `$${variable_name}`
+- **Blocks**: `$${% if condition %}...$${% endif %}`
+- **Comments**: `$${# This is a comment #}`
+
+Example template file:
+
+```python
+class $${name_pascal}Service:
+    def __init__(self):
+        self.name = "$${name_snake}"
+        self.kebab_name = "$${name_kebab}"
+
+$${# This comment will be removed #}
+$${% if include_logging %}
+import logging
+$${% endif %}
+```
+
+### Interactive Variable Collection
+
+When initializing a template, `boilersync` automatically scans template files (`.boilersync` files) for variables used in Jinja2 syntax. If it finds variables that aren't predefined (like the project name variables), it will prompt you to provide values:
+
+```bash
+$ boilersync init my-web-app
+
+🔧 Additional variables needed for this template:
+==================================================
+Enter value for 'author_email' (email address): user@example.com
+Enter value 'author_name' (name): John Doe
+Enter value for 'api_version' (version number): v1.0
+Enter value for 'database_url' (URL): postgresql://localhost:5432/mydb
+==================================================
+✅ All variables collected!
+```
+
+The system provides helpful prompts based on variable name patterns:
+
+- Variables ending in `_email` → prompts for "email address"
+- Variables ending in `_name` → prompts for "name"
+- Variables ending in `_url` → prompts for "URL"
+- Variables ending in `_version` → prompts for "version number"
+- Variables ending in `_description` → prompts for "description"
+
+Once collected, these values are remembered and reused if the same variable appears in multiple files.
+
+## Project Tracking
+
+After initialization, `boilersync` creates a `.boilersync` file in your project root to track the template and project information:
+
+```json
+{
+  "template": "web-app",
+  "name_snake": "my_awesome_project",
+  "name_pretty": "My Awesome Project"
+}
+```
+
+This file uses the same variable names that templates reference, making it easy to understand and potentially use in other tools.
+
+## Push Command
+
+The `push` command helps you see how your project has diverged from its original template. This is useful for:
+
+- Understanding what changes you've made
+- Deciding what to sync when templates are updated
+- Reviewing project evolution
+
+### How It Works
+
+1. **Finds your project root**: Locates the nearest `.boilersync` file (created during `init`)
+2. **Reads project info**: Gets the original template name and project names from `.boilersync`
+3. **Creates fresh template**: Initializes the template in a temporary directory using saved names
+4. **Sets up git**: Creates a git repo and commits the fresh template
+5. **Overlays your changes**: Copies your current project files over the fresh template
+6. **Opens push viewer**: Launches GitHub Desktop to show the pusherences
+
+### Usage
+
+```bash
+$ cd my-project
+$ boilersync push
+
+🔍 Creating push for template 'web-app'...
+📦 Initializing fresh template in temporary directory...
+🚀 Initializing project from template 'web-app'
+📝 Using saved project name: my_project
+📝 Using saved pretty name: My Project
+🔧 Setting up git repository...
+📋 Copying current project files...
+🚀 Opening in GitHub Desktop...
+📂 Temporary directory created and opened in GitHub Desktop.
+⏳ Press Enter when you're done reviewing the push...
+```
+
+The push will show:
+
+- **Green (additions)**: Your custom changes and new files
+- **Red (deletions)**: Template parts you've removed or modified
+- **Modified files**: Side-by-side comparison of your changes vs template
+
+### Special File Extensions
+
+#### `.boilersync` Extension
+
+Files ending with `.boilersync` are processed as templates and have the extension removed:
+
+- `package.json.boilersync` → `package.json` (processed)
+- `README.md.boilersync` → `README.md` (processed)
+- `config.yaml` → `config.yaml` (copied as-is)
+
+#### `.starter` Extension
+
+Files with `.starter` as the first extension are "starter files" - they're used only during initialization and won't be synced in future updates:
+
+- `example.starter.py` → `example.py` (init only, no future sync)
+- `sample.starter.config.json` → `sample.config.json` (init only)
+- `tutorial.starter.md.boilersync` → `tutorial.md` (processed + init only)
+
+### Template Directory Structure
+
+```
+boilerplate/
+├── my-template/
+│   ├── src/
+│   │   ├── NAME_SNAKE_service.py.boilersync
+│   │   └── utils.py
+│   ├── docs/
+│   │   ├── README.md.boilersync
+│   │   └── getting-started.starter.md.boilersync
+│   └── package.json.boilersync
+```
+
+After `boilersync init my-template` in directory `MyAwesomeProject`:
+
+```
+MyAwesomeProject/
+├── src/
+│   ├── my_awesome_project_service.py
+│   └── utils.py
+├── docs/
+│   ├── README.md
+│   └── getting-started.md
+└── package.json
+```