Metadata-Version: 2.4
Name: boilersync
Version: 1.2.15
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 CLI

`boilersync` scaffolds projects from templates and keeps templates alive as projects evolve.

## BoilerSync Ensemble

BoilerSync works as a small ensemble of tools:

- `boilersync-cli` for scaffold, pull, and push workflows.
- `boilersync-desktop` for repository diff review, staging, commit, and push workflows.
- Editor integration (Cursor/VS Code extension workflows) for fast editing and context switching.

For the full workflow guide, read [docs/ensemble.md](docs/ensemble.md).
For template metadata reference, read [docs/template-metadata.md](docs/template-metadata.md).

## Quick Start

```bash
# 1) Clone a template source into your local BoilerSync cache
boilersync templates init https://github.com/your-org/your-templates.git

# 2) Initialize a project from a source-qualified template ref
boilersync init your-org/your-templates#python/service-template

# Well-defaulted templates can be initialized without prompts
mkdir my-app-workspace
cd my-app-workspace
boilersync init your-org/your-templates#python/service-template --non-interactive

# 3) Pull template updates into the current project when needed
boilersync pull

# 4) Push committed project changes back into the template source
boilersync push
```

## Command Overview

- `boilersync init TEMPLATE_REF`: create a project from a template (empty target directory).
- `boilersync init TEMPLATE_REF --non-interactive`: create a project without prompts when defaults and automatic values cover all inputs.
- `boilersync check-pull`: compare the project's recorded template repo commit against the current cached template repo HEAD.
- `boilersync pull [TEMPLATE_REF]`: apply template updates to an existing project.
- `boilersync push`: review and copy committed project changes back to the template.
- `boilersync templates init`: clone a template source repository into the local cache.

Use command help for full flags:

```bash
boilersync --help
boilersync init --help
boilersync check-pull --help
boilersync pull --help
boilersync push --help
boilersync templates --help
```

## Template References

Template commands accept:

- `org/repo#path/to/template`
- `https://github.com/org/repo#path/to/template`
- `https://github.com/org/repo.git#path/to/template`

GitHub is the only supported host for source-qualified template refs.

Source-qualified refs clone (if missing) into:

```bash
${BOILERSYNC_TEMPLATE_DIR:-~/.boilersync/templates}/<org>/<repo>
```

## Project Tracking

After scaffold or pull, BoilerSync writes `.boilersync` metadata in the project root so future `pull`/`push` operations can resolve the original template source. That metadata now includes the last pulled template repo commit so `boilersync check-pull` can tell whether the project is behind template HEAD.
For the field-by-field schema and validation rules, see [docs/project-metadata.md](docs/project-metadata.md).

## Template Conventions

- Files ending in `.boilersync` are rendered and emitted without that extension.
- Files with `.starter` as the first extension are starter-only files.
- Every template root must include `template.json`, which supports inheritance (`extends`/`parent`), defaults, child templates, hooks, and optional GitHub repo creation.
- Project naming is provided through standard template variables such as `name_snake` and `name_pretty`.
- `template.json` `defaults` can derive variables from naming values, such as `"api_package_name": "$${name_snake}_api"` or `"web_package_name": "$${name_kebab}-web"`.
- Default project-name inference strips a trailing `-workspace` / `_workspace` suffix from the target directory name.
- If a template references `github_user`, BoilerSync tries to populate it with `gh api user --jq .login` before prompting or failing in non-interactive mode.

## Documentation Policy

This repository intentionally avoids hand-written API reference docs. If API docs are ever included, they should be generated and linked from this README.
