Metadata-Version: 2.4
Name: eai-supmig
Version: 0.2.1
Summary: Contract-first migration assistant for legacy Google-repo superbuild workspaces
Author-email: Michel Gillet <michel.gillet@libesys.org>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/libesys/ai-workflows/superbuild-workflow
Project-URL: Repository, https://gitlab.com/libesys/ai-workflows/superbuild-workflow.git
Project-URL: Documentation, https://gitlab.com/libesys/ai-workflows/superbuild-workflow/-/blob/develop/docs/package-publishing.md
Keywords: superbuild,cmake,conan,migration,repo,cli
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# superbuild-workflow

Authoritative shared workflow repository for superbuild-style software workspaces.

**GitLab path:** `ai-workflows/superbuild-workflow`
**Local mount in consuming repos:** `tools/ai-rules/`

This repository is **not** a product superbuild. It defines how superbuild workspaces are structured, built, governed, and assisted by AI tools. Consuming repositories coordinate multiple Git repositories under a CMake/Conan superbuild and mount this repo as a submodule for shared policy.

## What this is

- Portable workflow documentation (Markdown, `AGENTS.md`)
- Shared AI guidance for humans and coding agents
- Rationale and governance for how shared policy evolves
- Cursor adapter rules (thin wrappers over canonical docs)
- Templates for bootstrapping consuming repositories
- **Migration assistant CLI** (`eai-supmig`) — contract-first prep for legacy Google-repo superbuilds

## Migration assistant (`eai-supmig`)

Install and run from a legacy superbuild workspace (recommended order — see
[docs/migration-assistant.md](docs/migration-assistant.md) for the read-only alternative):

```bash
pip install eai-supmig
# or from this clone:
pip install -e ".[dev]"
eai-supmig bootstrap --with-ai-rules --with-cursor --yes
eai-supmig assess
eai-supmig plan
eai-supmig prompt
eai-supmig doctor
```

Module invocation: `python -m eai_supmig assess`

See [docs/migration-assistant.md](docs/migration-assistant.md) and [docs/package-publishing.md](docs/package-publishing.md).

## What this is not

- A consuming product superbuild or application codebase
- A replacement for a consuming repo's CMake superbuild
- The sole source of truth for Cursor-specific rules (adapters only)
- A place to fork shared policy silently from a consumer

## Architectural principle

| Layer | Role |
|-------|------|
| **This repo** (`tools/ai-rules/` in consumers) | Canonical shared workflow policy |
| **Consuming superbuild repo** | Product workspace, build orchestration, local exceptions |
| **Local tool adapters** (e.g. `.cursor/rules/`) | Materialized or symlinked rules; overlays only |

Plain Markdown and `AGENTS.md` are the long-term authoritative content. Cursor `.mdc` files in `cursor/rules/` are adapters, not the primary source of truth.

## Documentation portal

Published documentation is mirrored to [`ai-workflows/docs-portal`](../docs-portal) via GitLab downstream pipelines. Edit docs here first; see `docs/portal-integration.md` and `docs/workflow-manifest.yaml`.

## Repository layout

```
superbuild-workflow/
├── README.md                 # This file
├── AGENTS.md                 # Agent-oriented entry point (authoritative)
├── pyproject.toml            # Python package (eai-supmig)
├── src/eai_supmig/           # Migration assistant implementation
├── tests/                    # Unit tests
├── docs/                     # Portable workflow documentation
│   ├── architecture.md
│   ├── rationale.md
│   ├── workflow.md
│   ├── governance.md
│   ├── cursor-integration.md
│   ├── alternative-tool-integration.md
│   ├── repository-layout.md
│   ├── cmake-conan-policy.md
│   └── superbuild-philosophy.md
├── cursor/rules/             # Shared Cursor adapter rule sources
├── .cursor/rules/            # Governance rules for this repo itself
└── templates/                # Templates for consuming repos
```

## Consuming repositories

A typical superbuild workspace:

1. Adds this repo as a Git submodule at `tools/ai-rules/`
2. Maintains a root `AGENTS.md` that references shared policy and documents local exceptions
3. Materializes Cursor rules from `tools/ai-rules/cursor/rules/` into `.cursor/rules/` (copy or symlink)
4. Keeps repo-specific overlays in local `.cursor/rules/` without changing shared policy here

See [docs/repository-layout.md](docs/repository-layout.md) and [templates/](templates/) for details.

## Getting started

### As a maintainer of this repo

1. Clone and run `./scripts/setup-dev.sh` (installs pre-commit + commit-msg gitlint)
2. Check out **`develop`** for day-to-day work — see [docs/development-workflow.md](docs/development-workflow.md)
3. Read [AGENTS.md](AGENTS.md) and [docs/governance.md](docs/governance.md)
4. Use [docs/commit-messages.md](docs/commit-messages.md) for commit format
5. Propose shared workflow changes here first; update docs in the same change set
6. Fast-forward **`master`** from `develop` when CI is green (or after review if CI is not yet configured)
7. Use `.cursor/rules/` when editing with Cursor in this repository

### As a consumer

1. Add the submodule:

   ```bash
   git submodule add <gitlab-url>/ai-workflows/superbuild-workflow.git tools/ai-rules
   ```

2. Copy or adapt [templates/repo-AGENTS.template.md](templates/repo-AGENTS.template.md) to your root `AGENTS.md`
3. Run or adapt [templates/setup-dev.template.sh](templates/setup-dev.template.sh) to materialize Cursor rules and initialize submodules
4. Point agents and developers at `tools/ai-rules/AGENTS.md` and relevant `docs/`

## How to update shared workflow

1. **Change policy here first** — never treat a consuming repo's local copy as the source of truth
2. **Keep changes coherent** — one logical change per commit; update rationale/governance docs when semantics change
3. **Release via submodule** — consumers update with `git submodule update --remote tools/ai-rules` (or pin to a specific commit)
4. **Document local exceptions** — in the consumer's root `AGENTS.md` and local overlay rules, not by forking shared files

See [docs/workflow.md](docs/workflow.md) for the full change and rollout process.

## Documentation index

| Document | Purpose |
|----------|---------|
| [architecture.md](docs/architecture.md) | Layered model, remote vs local paths |
| [rationale.md](docs/rationale.md) | Why centralized shared workflow exists |
| [workflow.md](docs/workflow.md) | How changes flow from discovery to rollout |
| [governance.md](docs/governance.md) | What belongs here vs in consumers |
| [cursor-integration.md](docs/cursor-integration.md) | Cursor adapter usage |
| [alternative-tool-integration.md](docs/alternative-tool-integration.md) | Non-Cursor AI tools |
| [repository-layout.md](docs/repository-layout.md) | Expected consuming repo layout |
| [cmake-conan-policy.md](docs/cmake-conan-policy.md) | Build and dependency policy |
| [superbuild-philosophy.md](docs/superbuild-philosophy.md) | Multi-repo coordination model |
| [legacy-superbuild-migration.md](docs/legacy-superbuild-migration.md) | Phased migration from legacy CMake / `.vcxproj` |
| [legacy-superbuild-assessment.md](docs/legacy-superbuild-assessment.md) | Pre-migration inventory |
| [visual-studio-to-cmake-mapping.md](docs/visual-studio-to-cmake-mapping.md) | VS project → CMake target mapping |
| [conan-cmake-rollout.md](docs/conan-cmake-rollout.md) | Incremental Conan and presets |
| [superbuild-integration-plan.md](docs/superbuild-integration-plan.md) | `tools/ai-rules/` submodule rollout |
| [development-workflow.md](docs/development-workflow.md) | Branches, pre-commit, ff-merge to `master` |
| [commit-messages.md](docs/commit-messages.md) | Conventional Commits (gitlint) |
| [commit-checklist.md](docs/commit-checklist.md) | Pre-commit checklist |
| [migration-assistant.md](docs/migration-assistant.md) | `eai-supmig` CLI for legacy superbuild prep |
| [package-publishing.md](docs/package-publishing.md) | PyPI / GitLab package CI |

## License

This repository is licensed under the [MIT License](LICENSE). Shared workflow content may be used in consuming superbuild workspaces via the `tools/ai-rules/` submodule.
