Metadata-Version: 2.4
Name: cpp-project-foundation
Version: 0.6.0
Summary: Manifest-driven engineering foundation for production C++ projects
Author: HoneyBury
License-Expression: MIT
Project-URL: Homepage, https://github.com/HoneyBury/cpp-project-foundation
Project-URL: Repository, https://github.com/HoneyBury/cpp-project-foundation
Project-URL: Issues, https://github.com/HoneyBury/cpp-project-foundation/issues
Project-URL: Changelog, https://github.com/HoneyBury/cpp-project-foundation/blob/main/CHANGELOG.md
Keywords: cpp,cmake,conan,ci-cd,devops,scaffold
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# C++ Project Foundation

[English](https://github.com/HoneyBury/cpp-project-foundation/blob/main/README.md) |
[简体中文](https://github.com/HoneyBury/cpp-project-foundation/blob/main/README.zh-CN.md)

`cpp-project-foundation` is a manifest-driven engineering foundation for C++ services.
It extracts reusable build, dependency, security, release, deployment and operations
contracts without importing any product-specific service topology.

The first supported production profile is deliberately narrow:

- Ubuntu 24.04 x86-64
- GCC 13, C++20, CMake, Ninja and sccache
- Conan 2.8.1 with project-owned profiles and lockfiles
- one independently deployable service per generated project
- GitHub-hosted Actions runners by default, with optional self-hosted runners for long gates

Multi-service orchestration, application protocols, databases, SDK generation and cloud
platform policy are extension points, not hidden assumptions in the foundation core.

## Create a project

Install an immutable release with `pipx` and generate a service from the maintained
reference template:

```bash
pipx install "git+https://github.com/HoneyBury/cpp-project-foundation.git@v0.6.0"
cpp-foundation init \
  --name order-service \
  --version 0.1.0 \
  --output ../order-service
```

The generated project owns its `foundation.toml`, Conan graph and lockfile. Review the
manifest, regenerate the lockfile for the approved dependency graph, and then enable the
reusable CI workflow.

## Manifest

`foundation.toml` is the boundary between the generic platform and application code. It
declares build targets, release inputs and fail-closed operation hooks. The toolkit never
guesses service names or rewrites thresholds after observing a failure.
Version 0.6 validates this contract strictly: unknown fields, incorrectly typed arrays,
invalid observability URLs and non-positive hook timeouts fail during `validate`.

```toml
schema_version = 1

[project]
name = "order-service"
version = "0.1.0"

[build]
target = "order_service"
test_target = "order_service_tests"
profile = "conan/profiles/linux-gcc-x64"
lockfile = "conan/locks/linux-gcc-x64-release.lock"

[release]
executables = ["build/release/bin/order-service"]
include = ["deploy"]

[operations]
activate = ["docker", "compose", "-f", "deploy/docker-compose.yml", "up", "-d"]
verify = ["sh", "deploy/verify.sh"]
deactivate = ["docker", "compose", "-f", "deploy/docker-compose.yml", "down"]
canary = ["bin/order-service", "--check"]
benchmark = ["bin/order-service", "--benchmark", "200000"]
```

## Capability levels

### P0: engineering and supply-chain baseline

- isolated Conan 2.8.1, explicit remotes, profiles and immutable graph lock
- CMake/Ninja/CTest and sccache
- reusable GitHub CI
- OSV, ASan/UBSan, TSan and bounded libFuzzer jobs
- full-SHA Action pinning, least-privilege tokens, CODEOWNERS and branch protection bootstrap
- foundation-owned reusable workflows use an immutable semantic release tag so consumers
  upgrade the platform explicitly; all third-party Actions remain pinned to full SHAs
- candidate/runner/configuration/lockfile provenance
- pinned clang-format, Ruff, ShellCheck and actionlint gates
- Clang 18 clang-tidy with high-confidence findings treated as errors
- zero-warning policy for every project-owned C++ target in CI

### P1: immutable release and deployment

- safe runtime archive, SHA-256, deterministic payload digest, validated SPDX 2.3 SBOM
  and candidate provenance
- GitHub artifact attestations and immutable tag release
- archive path traversal and digest verification
- idempotent install, serialized deployment operations, upgrade, rollback, status and verify
- failed candidate cleanup, automatic rollback and explicit interrupted-transaction recovery
- runtime-only Dockerfile, hardened Compose, systemd and Prometheus/Grafana reference files
- GCC 13 and Clang 18 compatibility builds, CodeQL and coverage thresholds
- Dependabot policies for Actions, Python tooling and Docker bases

### P2: operations evidence

- create-only evidence records with closed-world, content-addressed raw summaries
- package verification for off-host retention
- age-encrypted backup creation, verification and isolated restore
- application-defined external canary with fixed-window aggregation
- bounded smoke, 2h and 8h soak profiles
- repeated performance gates with explicit throughput and P99 thresholds
- operations evidence rendered directly in the GitHub job summary
- scheduled IWYU, cppcheck, Hadolint, Markdown and CMake quality checks
- clean-build time, release binary size and repeat-build digest budgets

## Common commands

On a fresh checkout, initialize the local development environment with Python 3.11 or
newer:

```bash
python3 scripts/bootstrap_dev.py
source .venv/bin/activate
```

```bash
cpp-foundation --manifest foundation.toml validate
cpp-foundation --manifest foundation.toml doctor --root .
cpp-foundation --manifest foundation.toml doctor --root . --strict-tools
cpp-foundation --manifest foundation.toml doctor --root . --probe-observability
cpp-foundation --manifest foundation.toml template-diff --root .
cpp-foundation quality --root . --mode deep --fix
cpp-foundation quality --root . --mode fast
cpp-foundation quality --root . --mode deep
cpp-foundation --manifest foundation.toml package --output-dir dist
cpp-foundation verify-release --archive dist/project-v0.1.0-linux-x64.tar.gz \
  --checksum dist/project-v0.1.0-linux-x64.tar.gz.sha256

sudo cpp-foundation deploy --root /opt/project --state-root /var/lib/project \
  install --archive /tmp/project-v0.1.0-linux-x64.tar.gz \
  --checksum /tmp/project-v0.1.0-linux-x64.tar.gz.sha256
sudo cpp-foundation deploy --root /opt/project --state-root /var/lib/project \
  activate --deployment-id <deployment-id>
sudo cpp-foundation deploy --root /opt/project --state-root /var/lib/project recover
```

Install the repository-pinned quality toolset before running the local quality commands:

```bash
python3 scripts/install_quality_tools.py \
  --venv .venv/quality --tools-dir .tools
export PATH="$PWD/.venv/quality/bin:$PWD/.tools/bin:$PWD/.tools/npm/node_modules/.bin:$PATH"
```

The fast quality gate is required on pull requests. Deep IWYU, cppcheck, documentation,
Dockerfile and reproducibility gates run on schedule or explicit dispatch. Analysis and
coverage options are isolated from the default Release build.

Long operations are opt-in. Ordinary pull requests run a two-second bounded stability
smoke. All generated workflows default to GitHub-hosted `ubuntu-24.04` runners. The 2h
profile can use that default. Before enabling `overnight-8h`, a consuming project must
explicitly configure an authorized self-hosted runner because GitHub-hosted jobs have a
shorter execution limit.

## Production boundaries

- A template cannot configure GitHub branch rules, runner groups, environments or
  secrets. Use `scripts/bootstrap_github.py --apply` after the first `main` commit. The
  script defaults to zero approvals for a single maintainer; team repositories should pass
  `--required-approvals 1` or higher and repeat `--required-check` for every exact context.
- Consumers reference the public reusable workflows through the immutable
  `HoneyBury/cpp-project-foundation@v0.6.0` release tag.
- GitHub-hosted attestations run automatically for public repositories. Private consumers
  still publish SHA-256, provenance JSON and SPDX; supported enterprise repositories can
  explicitly enable native attestations.
- Conan profiles may be shared; lockfiles are owned by each consuming dependency graph.
- Backup archives require an age recipient by default. Plaintext mode exists only for tests.
- The local evidence package reports `off_host_copy_verified=false`; a separate host must
  verify and record the transfer.
- A successful framework smoke test is not an availability, capacity or HA claim.

The independently governed
[`cpp-foundation-smoke`](https://github.com/HoneyBury/cpp-foundation-smoke) repository
exercises generation, pull-request gates, release attestations, Compose runtime and
operations profiles without sharing this repository's source tree.

Python publishing uses a separately permissioned PyPI trusted-publisher workflow. See
[publishing.md](docs/publishing.md) for the one-time external identity configuration and
mandatory dry-run.

See
[foundation-contract.md](https://github.com/HoneyBury/cpp-project-foundation/blob/main/docs/foundation-contract.md),
[compatibility.md](https://github.com/HoneyBury/cpp-project-foundation/blob/main/docs/compatibility.md),
[migrations.md](https://github.com/HoneyBury/cpp-project-foundation/blob/main/docs/migrations.md),
[publishing.md](https://github.com/HoneyBury/cpp-project-foundation/blob/main/docs/publishing.md),
[architecture.md](https://github.com/HoneyBury/cpp-project-foundation/blob/main/docs/architecture.md)
and
[operations.md](https://github.com/HoneyBury/cpp-project-foundation/blob/main/docs/operations.md).
