Metadata-Version: 2.4
Name: development-engine-vector
Version: 0.3.0
Summary: Development Engine Vector — internal developer workflow CLI.
Author-email: Ernie Butcher <ernie@fiosii.com>
License-Expression: MIT
Requires-Python: >=3.8
Requires-Dist: click>=8.1
Requires-Dist: tomli>=2.0
Description-Content-Type: text/markdown

# Development Engine Vector

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/dev-cli.svg)](https://pypi.org/project/dev-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Development Engine Vector** (`dev`) is the developer workflow coordination CLI for goCosmix systems. It provides a consistent, scriptable interface for preflight checks, version management, changelog automation, release orchestration, and git/GitHub operations — usable across every system in the federation.

`dev` is designed to be pointed at any goCosmix project directory and immediately useful: it reads project config, validates state, manages versions, and drives releases — without knowing anything specific about what the project does.

## ✨ Key Capabilities

- **Preflight checks**: version file, changelog entry, git state, dirty tree, sensitive files, pyproject sync
- **CDA-aware preflight**: extended checks for vscode-ark-specific pipeline and daemon health
- **Version management**: read, bump (major/minor/patch), sync to `pyproject.toml` and all tracked files
- **Changelog automation**: structured CHANGELOG management with version section creation and entry validation
- **Release orchestration**: full release workflow — preflight → version sync → build → git tag → publish
- **Project bootstrap**: install editable package, requirements, and dev dependencies in one command
- **Git/GitHub ops**: ensure remotes, create GitHub repos via API, push branches
- **Self-check**: engine health validation — install path, DB state, tool dependencies, version consistency
- **Config-driven**: per-project `.dev-cli.toml` for default bump level, skip flags, dry-run mode

## 📋 Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## 🚀 Installation

### Prerequisites

- Python 3.9+

### Install from PyPI

```bash
pip install dev-cli
```

> **macOS / system Python note**: pip installs the `dev` binary to `~/Library/Python/3.x/bin/` which may not be on `PATH` by default.
>
> ```bash
> export PATH="$HOME/Library/Python/3.9/bin:$PATH"
> ```
>
> Add this line to `~/.zprofile` for persistence.

### Install from source

```bash
git clone https://github.com/goCosmix/dev.git
cd dev/source
pip install -e .
```

### Install development dependencies

```bash
pip install -e ".[dev]"
```

## ⚡ Quick Start

```bash
pip install dev-cli
export PATH="$HOME/Library/Python/3.9/bin:$PATH"

# Point at any goCosmix project
dev pf --project /Volumes/intel/systems/cda/source     # preflight check
dev version show --project /Volumes/intel/systems/cda/source
dev release --project /Volumes/intel/systems/cda/source --dry-run
```

## 🔧 CLI Reference

### `dev pf` / `dev preflight`

Run pre-release preflight checks for a project.

```bash
dev pf --project <path>           # standard checks
dev pf --project <path> --full    # full check set (includes CDA-specific)
dev pf --project <path> --report report.json
```

Checks run: version file, changelog entry, git state (clean tree, committed), sensitive file exposure, pyproject.toml version sync.

### `dev version`

```bash
dev version show   --project <path>              # print current version
dev version bump   --project <path> --level patch  # bump major/minor/patch
dev version sync   --project <path>              # sync version → pyproject.toml
```

### `dev release`

Full release workflow: preflight → version bump → sync → build → git tag → publish.

```bash
dev release --project <path>
dev release --project <path> --bump minor
dev release --project <path> --version 2.1.0
dev release --project <path> --skip-publish     # build + tag, don't push to PyPI
dev release --project <path> --dry-run          # simulate, no writes
```

### `dev build`

Build source and wheel distributions.

```bash
dev build --project <path>
```

### `dev sync`

Bootstrap or re-sync project dependencies.

```bash
dev sync --project <path>
dev sync --project <path> --install-dev         # also install dev dependencies
dev sync --project <path> --no-install-editable # skip editable install
```

### `dev check`

Project health checks: compile validation, lint, optional pytest.

```bash
dev check --project <path>
dev check --project <path> --tests              # include pytest
dev check --project <path> --lint               # include flake8
dev check --project <path> --compile            # Python compile check
```

### `dev selfcheck`

Engine self-diagnostics — validates the `dev` installation itself.

```bash
dev selfcheck
```

Checks: version consistency, install path, DB state, required tools on PATH, Python dependencies.

### `dev config`

```bash
dev config show --project <path>    # display active config and resolved settings
```

## ⚙️ Configuration

Add a `.dev-cli.toml` or `dev-cli.toml` at any project root:

```toml
[release]
default_bump = "minor"
skip_build = false
skip_publish = false
dry_run = false

[bootstrap]
install_editable = true
install_dependencies = true
install_dev_dependencies = false

[check]
compile = true
tests = false
lint = false
```

Override the config file path at runtime:

```bash
dev --config ./custom.dev-cli.toml release --project /Volumes/intel/systems/cda/source
```

## 🏗 Architecture

`dev` is organized into four layers:

```
dev/
├── kernel/       — runtime foundation (paths, DB, config, self-check)
├── workflow/     — business logic (versioning, changelog, preflight, release)
├── vcs/          — version control ops (git, GitHub API)
└── cli/          — thin click wrappers
```

See [docs/architecture.md](docs/architecture.md) for the full design.

## 🛠 Development

```bash
cd /Volumes/intel/systems/dev/source
pip install -e .
export PATH="$HOME/Library/Python/3.9/bin:$PATH"

# Run checks
python3 -m flake8 dev/
python3 -m mypy dev/
python3 -m pytest tests/ -q

# Or via the control plane
python3 ../control/scripts/vet.py
python3 ../control/cli.py health
```

### Control plane

```bash
python3 control/cli.py --help

dev-control status        # version, paths, DB state
dev-control vet           # run lint + typecheck + tests, write history to DB
dev-control health        # show vet run history
dev-control health --checks  # list defined check definitions
dev-control push          # build + publish to PyPI
dev-control seed          # re-seed control.db
dev-control selfcheck     # engine self-diagnostics
dev-control runs          # show run history from dev.db
dev-control projects      # show registered projects
dev-control manifest      # query file manifest from control.db
```

## 🤝 Contributing

See [contributing.md](contributing.md).

## 📄 License

MIT — see [license](license).
