Metadata-Version: 2.4
Name: intent-cli
Version: 0.1.0
Summary: Safety-first tool to generate tool-owned project files from intent.toml
Author: sankarebarri
License: MIT
Project-URL: Homepage, https://github.com/sankarebarri/intent
Project-URL: Repository, https://github.com/sankarebarri/intent
Project-URL: Issues, https://github.com/sankarebarri/intent/issues
Keywords: ci,github-actions,justfile,just,automation,scaffolding,generator,devtools,tooling,configuration
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# Intent

Intent is a small, boring tool that keeps project config in sync by generating tool-owned files from a single `intent.toml`.

## Who it's for

*   **Teams** that want one source of truth for Python versions and common commands.
*   **Projects** that want safe, repeatable generation of CI workflows and Justfiles.

## Files

*   **You edit:** `intent.toml`
*   **Intent reads:** `intent.toml`, `pyproject.toml`
*   **Intent writes:** tool-owned files only
*   **Example generated files:** `.github/workflows/ci.yml`, `justfile`

## Installations
### From PyPI

```bash
python -m pip install intent
```

### From source

```bash
python -m pip install -e .
```

## Configuration
### Intent file(intent.toml)
The only file you author
```toml
# use to verify that versions conform all around
[python]
version = "3.12"

[commands]
test = "pytest -q"
lint = "ruff check ."

# used to generate and install dependencies in ci.yml
[ci]
install = "-e .[dev]"
# This value is used verbatim when generating CI install steps.
# Intent does not infer dependencies, it only reflects what you declare.
```

This file describes **agreements**, not implementations.
If something is not declared in `intent.toml`, Intent will not guess.


---

### Canonical Files (Read-Only)

Some files are owned by the ecosystem, not by Intent.

Examples:

* `pyproject.toml`

Intent will:

* read them
* validate consistency
* fail loudly on mismatch

Intent will **never modify them**.

---

### Example
### ✅ Python version consistency

```bash
intent sync
```
will:
* Read `requires-python` from `pyproject.toml`
* Validate it against the `intent.toml` python declared version and return one of the following:

  * pyproject requires_python matches intent
  * Version mismatch (simple spec): intent=X.Y vs pyproject=A.B
  * Unsupported requires_python spec

---

### Generated Files (Tool-Owned)

Intent generates files it fully owns:

* `.github/workflows/ci.yml`
* `justfile`

These files:

* contain a `# GENERATED BY intent` marker
* are written atomically
* are overwritten safely
* refuse overwrite if user-edited

## Usage & Commands

All commands and what they do:

| Command | What it does |
| --- | --- |
| `intent --version` | Show version and exit. |
| `intent sync` | Read `intent.toml` + `pyproject.toml` and show config + version check. |
| `intent sync --show-ci` | `intent sync` plus preview generated CI. |
| `intent sync --show-just` | `intent sync` plus preview generated justfile. |
| `intent sync --dry-run` | Preview what would be written (no writes). |
| `intent sync --write` | Write tool-owned files. |
| `intent check` | Check drift without writing. |
| `intent check --strict` | Check drift with strict `requires_python` parsing. |
| `intent sync path/to/intent.toml` | Use a non-default config path for sync. |
| `intent check path/to/intent.toml` | Use a non-default config path for check. |

## Notes

Expected output:

| Command | Expected output |
| --- | --- |
| `intent --version` | Prints version like `0.3.0`. |
| `intent sync` | Lines like `Intent python version: 3.12`, `Intent commands:`, `test -> pytest -q`, `Version ok (range): intent 3.12 satisfies >=3.10,<3.13`. |
| `intent sync --show-ci` | Same as `intent sync`, then `--- ci.yml (preview) ---` and rendered `ci.yml`. |
| `intent sync --show-just` | Same as `intent sync`, then `--- justfile (preview) ---` and rendered `justfile`. |
| `intent sync --dry-run` | `--- dry-run ---`, then `Would write .github/workflows/ci.yml` and `Would update justfile` (or `No changes to ...`). |
| `intent sync --write` | `Wrote .github/workflows/ci.yml` and `Wrote justfile` (or `No changes to ...`). |
| `intent check` | `✓ Version ok (range): ...`, `✓ .github/workflows/ci.yml is up to date`, `✓ justfile is up to date`. |
| `intent check --strict` | Same as `intent check`, but unsupported specs are errors. |
| `intent sync path/to/intent.toml` | Same outputs as `intent sync`, using that file. |
| `intent check path/to/intent.toml` | Same outputs as `intent check`, using that file. |

## Safety & Ownership Rules
Intent is intentionally conservative.

* Intent **never edits user-owned files**.
* Intent **refuses to overwrite files** unless they contain a generated marker.
* All generated files are clearly marked as **tool-owned**.
* Output is **deterministic and idempotent**:
  running the same command twice produces no changes.
* File writes are **atomic**:
  files are written via a temporary file and replaced safely.

If a file exists but is not marked as tool-owned, Intent will fail loudly instead of guessing.

---

## Non-Goals

Intent does **not**:

* Edit existing CI workflows
* Merge or patch user files
* Guess dependencies
* Perform bidirectional sync

When in doubt, Intent refuses to act.

---

## License

MIT
