Metadata-Version: 2.4
Name: axm-init
Version: 0.9.0
Summary: AXM Init — Python project scaffolding CLI with Copier templates.
Project-URL: Homepage, https://github.com/axm-protocols/axm-init
Project-URL: Documentation, https://axm-protocols.github.io/axm-init/
Project-URL: Repository, https://github.com/axm-protocols/axm-init.git
Project-URL: Issues, https://github.com/axm-protocols/axm-init/issues
Author-email: Gabriel Jarry <gabriel@axm-protocols.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,governance,project,python,scaffolding,standards
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: axm
Requires-Dist: copier>=9.11.2
Requires-Dist: cyclopts>=4.5.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/axm-protocols/axm-init/main/assets/logo.png" alt="AXM Logo" width="180" />
</p>

<p align="center">
  <strong>axm-init — Python project scaffolding, quality checks & governance CLI</strong>
</p>


<p align="center">
  <a href="https://github.com/axm-protocols/axm-init/actions/workflows/ci.yml"><img src="https://github.com/axm-protocols/axm-init/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://axm-protocols.github.io/axm-init/explanation/check-grades/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-init/gh-pages/badges/axm-init.json" alt="axm-init"></a>
  <a href="https://axm-protocols.github.io/axm-audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-init/gh-pages/badges/axm-audit.json" alt="axm-audit"></a>
  <a href="https://coveralls.io/github/axm-protocols/axm-init?branch=main"><img src="https://coveralls.io/repos/github/axm-protocols/axm-init/badge.svg?branch=main" alt="Coverage"></a>
  <a href="https://pypi.org/project/axm-init/"><img src="https://img.shields.io/pypi/v/axm-init" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
  <a href="https://axm-protocols.github.io/axm-init/"><img src="https://img.shields.io/badge/docs-live-brightgreen" alt="Docs"></a>
</p>


---

## Features

- 🚀 **Scaffold** — Bootstrap production-grade Python projects, workspaces, and member packages
- 📋 **Check** — Score any project against the AXM gold standard (44 checks, A–F grade)
- 📦 **Reserve** — Claim a package name on PyPI before you're ready to publish

## Installation

```bash
uv add axm-init
```

## Quick Start

```bash
# Scaffold a new project
axm-init scaffold my-project \
  --org axm-protocols \
  --author "Your Name" --email "you@example.com"

# Check against AXM standards
axm-init check
# Score: 100/100 — Grade A 🏆

# Reserve a name on PyPI
axm-init reserve my-cool-lib --dry-run
```

## CLI Commands

### `axm-init scaffold`

Scaffold a production-grade Python project (src layout, PEP 621, CI, docs).

| Option | Short | Default | Description |
|---|---|---|---|
| `PATH` | | `.` | Directory to initialize |
| `--org` | `-o` | *required* | GitHub org or username |
| `--author` | `-a` | *required* | Author name |
| `--email` | `-e` | *required* | Author email |
| `--name` | `-n` | *dir name* | Project name |
| `--license` | `-l` | `Apache-2.0` | License (MIT, Apache-2.0, EUPL-1.2) |
| `--license-holder` | | *--org* | License holder |
| `--description` | `-d` | | One-line description |
| `--workspace` | `-w` | `False` | Scaffold a UV workspace instead of a standalone package |
| `--member` | `-m` | | Scaffold a member sub-package with this name |
| `--check-pypi` | | `False` | Verify PyPI availability first |
| `--json` | | `False` | Output as JSON |

> **Note:** `--workspace` and `--member` are mutually exclusive.

### `axm-init check`

Score a project against the AXM gold standard (44 checks across 8 categories).

| Option | Short | Default | Description |
|---|---|---|---|
| `PATH` | | `.` | Directory to check |
| `--category` | `-c` | *all* | Filter to one category |
| `--json` | | `False` | Output as JSON |
| `--agent` | | `False` | Compact agent-friendly output |

**Categories:** `pyproject`, `ci`, `tooling`, `docs`, `structure`, `deps`, `changelog`, `workspace`

### `axm-init reserve`

Reserve a package name on PyPI with a minimal placeholder.

| Option | Short | Default | Description |
|---|---|---|---|
| `NAME` | | *required* | Package name to reserve |
| `--author` | `-a` | *git config* | Author name (**required**) |
| `--email` | `-e` | *git config* | Author email (**required**) |
| `--dry-run` | | `False` | Skip actual publish |
| `--json` | | `False` | Output as JSON |

> **Note:** `--author` and `--email` fall back to `git config user.name` / `user.email`.
> If both are empty, `axm-init` exits with an error.

## Workspace Support

`axm-init` detects three **project contexts** and adapts checks accordingly:

| Context | Detection | Behavior |
|---|---|---|
| **STANDALONE** | No `[tool.uv.workspace]` | All checks enabled |
| **WORKSPACE** | Has `[tool.uv.workspace]` at root | CI, tooling, and workspace checks enabled |
| **MEMBER** | Is a `packages/*/` sub-directory | CI checks excluded (handled at workspace root) |

### Per-Package Check Exclusions

Workspace members can exclude inapplicable checks via `pyproject.toml`:

```toml
[tool.axm-init]
exclude = ["ci.ci_workflow_exists", "tooling.makefile"]
```

### Scaffold Modes

```bash
# Standalone package (default)
axm-init scaffold my-project --org myorg --author A --email e@e.com

# UV workspace
axm-init scaffold my-workspace --workspace --org myorg --author A --email e@e.com

# Member sub-package (run from inside workspace)
axm-init scaffold --member my-lib --org myorg --author A --email e@e.com
```

The `--member` flag auto-detects the workspace root, creates the package under `packages/<name>/`, and patches root files (Makefile, mkdocs.yml, pyproject.toml, CI workflows).

## CI Check Badge

Projects scaffolded with `axm-init scaffold` include an automated **check badge** that updates on every push. The badge shows your score and grade using the AXM logo.

```
push → axm-init check → badge JSON → gh-pages → shields.io
```

The badge is already in your README — just push to `main` and it appears after the first CI run.

**Existing projects** can add the badge too — copy `.github/workflows/axm-init.yml` from a scaffolded project and add the badge markup. See the [howto guide](https://axm-protocols.github.io/axm-init/howto/check/#ci-badge) for details.

## Development

```bash
git clone https://github.com/axm-protocols/axm-init.git
cd axm-init
uv sync --all-groups
uv run pytest           # 534 tests (fast subset, ~8s)
uv run pytest -m slow   # real Copier scaffold tests (~15s)
uv run ruff check src/  # lint
```

## License

Apache License 2.0
