Development Engine Vector

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
• Quick Start
• CLI Reference
• Configuration
• Architecture
• Development
• Contributing
• License

🚀 Installation

Prerequisites

• Python 3.9+

Install from PyPI

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.

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:

dev setup

Install from source

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

⚡ Quick Start

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.

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

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.

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.

dev build --project <path>

dev sync

Bootstrap or re-sync project dependencies.

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.

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.

dev selfcheck

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

dev config

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

dev ui

Manage the embedded web dashboard (port 9001).

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 otk

Manage the Ops Tool Kernel (OTK) and background services/tasks.

dev otk services                              # list services/tasks and status
dev otk status [service_id]                   # detailed status for one or all
dev otk start ui                              # start daemon service
dev otk start preflight --project <path>      # run preflight task service
dev otk start vet                             # run control vet task service
dev otk start build --project <path>          # run build task service
dev otk start publish-check                   # run dry-run publish validation
dev otk start release-dryrun --project <path> # run full dry-run release workflow
dev otk stop ui                               # stop daemon service
dev otk restart ui                            # restart daemon service
dev otk logs vet --tail 100                   # tail service/task logs
dev otk events --tail 20                      # inspect kernel event journal
dev otk up                                    # start default runtime services
dev otk install                               # register macOS LaunchAgent (auto-start)
dev otk uninstall                             # remove LaunchAgent

dev pmf ... remains available as a legacy alias for backward compatibility.

dev setup

Full onboarding wizard — run once after install.

dev setup                           # init dirs + otk install + ui start + open browser
dev setup --no-browser              # same, skip browser
dev setup --run-otk-chain           # also run the OTK preflight → vet chain

Steps:

1. Init — create ~/Library/goCosmix/tools/dev/ and all runtime subdirs; patch ~/.zprofile if dev is not on PATH
2. OTK install — register com.gocosmix.dev LaunchAgent so dev starts automatically on every login
3. Up — start the web UI via OTK kernel, open browser at http://127.0.0.1:9001
4. Phase 2 — optionally run preflight → vet against the dev source tree for a fresh post-setup validation pass

⚙️ Configuration

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

[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:

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

🏗 Architecture

dev is organized into five layers:

dev/
├── kernel/       — runtime foundation (OTK kernel, shared core, paths, 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 for the full design.

🛠 Development

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).

# 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.

📄 License

MIT — see license.