Metadata-Version: 2.4
Name: development-engine-vector
Version: 0.3.1
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/development-engine-vector.svg)](https://pypi.org/project/development-engine-vector)
[![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 development-engine-vector
```

> **macOS / system Python note**: pip installs the `dev` binary to `~/Library/Python/3.9/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.

### First-time setup (recommended)

After install, run the onboarding wizard — it creates your home directory, registers the macOS LaunchAgent, and opens the dashboard:

```bash
dev setup
```

### Install from source

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

## ⚡ Quick Start

```bash
pip install development-engine-vector
export PATH="$HOME/Library/Python/3.9/bin:$PATH"

# Full onboarding (creates ~/Library/goCosmix/tools/dev/, registers launchd, opens UI)
dev setup

# Or just start the dashboard manually
dev ui start

# Point at any goCosmix project
dev pf --project /path/to/project     # preflight check
dev version show --project /path/to/project
dev release --project /path/to/project --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
```

### `dev ui`

Manage the embedded web dashboard (port 9001).

```bash
dev ui start                        # start dashboard, open browser
dev ui start --no-browser           # start without opening browser
dev ui stop                         # stop dashboard
dev ui status                       # show pid, started time, log path
dev ui restart                      # restart
```

### `dev pmf`

Manage the embedded PMF kernel and background services.

```bash
dev pmf services                    # list all services and status
dev pmf status [service_id]         # detailed status for one or all services
dev pmf start ui                    # start a service
dev pmf stop ui                     # stop a service
dev pmf restart ui                  # restart a service
dev pmf logs ui [--tail 50]         # tail service log
dev pmf up                          # start all services (called by launchd on login)
dev pmf install                     # register macOS LaunchAgent (auto-start on login)
dev pmf uninstall                   # remove LaunchAgent
```

### `dev setup`

Full onboarding wizard — run once after install.

```bash
dev setup                           # init dirs + pmf install + ui start + open browser
dev setup --no-browser              # same, skip browser
```

Steps:
1. **Init** — create `~/Library/goCosmix/tools/dev/` and all runtime subdirs; patch `~/.zprofile` if `dev` is not on PATH
2. **PMF install** — register `com.gocosmix.dev` LaunchAgent so `dev` starts automatically on every login
3. **Up** — start the web UI via PMF kernel, open browser at `http://127.0.0.1:9001`

## ⚙️ 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 five layers:

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

Runtime home: `~/Library/goCosmix/tools/dev/` (tools tier — `9000` namespace)

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 all checks (lint + typecheck + tests)
python3 /Volumes/intel/systems/dev/control/scripts/vet.py

# Or individually
python3 -m flake8 dev/
python3 -m mypy dev/
python3 -m pytest tests/ -q
```

### Control plane

The control plane manages the `dev` system itself (not for managing other projects).

```bash
# Vet, seed, and publish
python3 /Volumes/intel/systems/dev/control/scripts/vet.py    # lint + typecheck + tests
python3 /Volumes/intel/systems/dev/control/scripts/seed.py   # re-seed control.db
python3 /Volumes/intel/systems/dev/control/scripts/push.py   # vet + git push + PyPI publish
```

## 🤝 Contributing

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

## 📄 License

MIT — see [license](license).
