Metadata-Version: 2.4
Name: devfabeco-buildcore
Version: 0.3.0
Summary: Deterministic DAG executor for NGKsGraph build plans (MSVC/Qt C++ focus)
Author: NGKsSystems
License: Proprietary
Project-URL: Homepage, https://github.com/NGKsSystems/NGKsDevFabEco
Project-URL: Repository, https://github.com/NGKsSystems/NGKsDevFabEco
Project-URL: Bug Tracker, https://github.com/NGKsSystems/NGKsDevFabEco/issues
Keywords: build,dag,executor,msvc,deterministic,cpp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"

# NGKsBuildCore

NGKsBuildCore is a Python MVP build runner that executes a DAG build plan with deterministic scheduling, parallel workers, and auditable proof logs.

## Commands

- `python -m ngksbuildcore --help`
- `python -m ngksbuildcore doctor`
- `python -m ngksbuildcore run --plan examples\hello_plan.json -j 8`
- `python -m ngksbuildcore explain --plan examples\hello_plan.json`

## Plan Contract

Plan JSON fields:

- `base_dir` optional, defaults to plan file directory
- `nodes` array of objects with:
  - `id` (string)
  - `desc` (string, optional)
  - `cwd` (string, optional)
  - `cmd` (string or string array)
  - `deps` (string array)
  - `inputs` (path array)
  - `outputs` (path array)
  - `env` (dict, optional)

## Proof Output

Each run writes to timestamped proof directory under `_proof` (or `NGKS_PROOF_ROOT`):

- `events.jsonl`
- `commands.jsonl`
- `summary.json`
- `summary.txt`
- `environment.txt`
- `tool_versions.txt`
- `git_status.txt`
- `git_head.txt`

## Long-Running Node Indicator

During long compile/link steps, NGKsBuildCore emits liveness heartbeats so users can tell a node is still active.

- `NGKS_NODE_HEARTBEAT_SEC` - heartbeat interval in seconds (default: `15`, set `0` to disable)
- `NGKS_NODE_HEARTBEAT_STYLE` - output style: `line` (default) or `spinner`

Example:

```powershell
$env:NGKS_NODE_HEARTBEAT_SEC = "10"
$env:NGKS_NODE_HEARTBEAT_STYLE = "spinner"
python -m ngksbuildcore run --plan examples\hello_plan.json -j 8
```

## Integration Adapters

- `ngksbuildcore.adapters.graph_adapter.run_graph_plan`
- `ngksbuildcore.adapters.devfabric_adapter.build_from_manifest`
