bijux-cli 0.1.2

Lean, plug-in-driven CLI kernel

Bijux CLI

A modern, predictable CLI framework for Python — strict global flag precedence, first-class plugins, a DI kernel, and an interactive REPL. Build robust, extensible command-line tools that are easy to test, maintain, and scale.

At a glance: Plugin-driven • deterministic flags • DI for testability • REPL • structured JSON/YAML
Quality: 2,600+ tests across layers with 98%+ coverage (see Test Artifacts and HTML coverage). Multi-version CI. Docs build enforced. No telemetry.

---

Table of Contents

• Why Bijux CLI?
• Try It in 20 Seconds
• Key Features
• Installation
• Quick Start
• Plugins in 60 Seconds
• Structured Output
• Developer Introspection
• Global Flags: Strict Precedence
• Built-in Commands
• When to Use (and Not Use)
• Shell Completion
• Configuration & Paths
• Tests & Quality
• Project Tree
• Roadmap
• Docs & Resources
• Contributing
• Acknowledgments
• License

Back to top

---

Why Bijux CLI?

Click and Typer excel at simple tools. Bijux emphasizes predictability and modularity for complex ones:

• Deterministic flags for reliable CI/scripting.
• Dependency Injection kernel for testable, decoupled services.
• First-class plugins to extend without touching the core.
• Interactive REPL for exploration and debugging.

Back to top

---

Try It in 20 Seconds

pipx install bijux-cli  # Or: pip install bijux-cli
bijux --version
bijux doctor
bijux status -f json --no-pretty

Back to top

---

Key Features

• Plugin-Driven Extensibility — Scaffold, install, validate; plugins become top-level commands.
• Deterministic Behavior ⚖ — Strict flag precedence (see ADR-0002).
• DI Kernel — Decouple internals; inspect graphs for debugging/tests.
• REPL Shell — Persistent session with history; great for exploration/demos.
• Structured Output — JSON/YAML (+ pretty/compact, verbosity, consistent errors).
• Diagnostics — Built-in doctor, audit, docs for workflows.
• Shell Completion — Bash, Zsh, Fish, PowerShell support.

Back to top

---

Installation

Requires Python 3.11+.

# Isolated install (recommended)
pipx install bijux-cli

# Standard
pip install bijux-cli

Upgrade: pipx upgrade bijux-cli or pip install --upgrade bijux-cli.

Back to top

---

Quick Start

# Discover commands/flags
bijux --help

# Health check
bijux doctor

# REPL mode
bijux
bijux> help
bijux> status
bijux> exit

Back to top

---

Plugins in 60 Seconds

# Scaffold from a real template (local dir or Git URL), then install
# Option A: local template (example uses repo's cookiecutter template)
bijux plugins scaffold my_plugin --template ./plugin_template --force

# Option B: cookiecutter-compatible Git URL
# bijux plugins scaffold my_plugin --template https://github.com/bijux/bijux-plugin-template.git --force

# Install & explore
bijux plugins install ./my_plugin --force
bijux plugins list
bijux my_plugin --help

# Validate & remove
bijux plugins check my_plugin
bijux plugins uninstall my_plugin

Plugins dynamically add top-level commands.

Back to top

---

Structured Output

For automation:

# Compact JSON
bijux status -f json --no-pretty | jq

# Pretty YAML
bijux status -f yaml --pretty

Back to top

---

Developer Introspection

# DI graph
bijux dev di -f json

# Loaded plugins
bijux dev list-plugins

Back to top

---

Global Flags: Strict Precedence

Fixed ordering eliminates ambiguity.

Priority	Flag	Effect
1	-h, --help	Immediate exit (code 0) with usage; ignores all.
2	-q, --quiet	Suppress stdout/stderr; preserves exit code.
3	-d, --debug	Full diagnostics; implies --verbose, forces --pretty.
4	-f, --format <json|yaml>	Structured output; invalid → code 2.
5	--pretty / --no-pretty	Indentation toggle (default: --pretty).
6	-v, --verbose	Runtime metadata; implied by --debug.

Rationale: ADR-0002

Back to top

---

Built-in Commands

Command	Description	Example
doctor	Environment diagnostics	bijux doctor
status	CLI snapshot	bijux status -f json
repl	Interactive shell	bijux repl
plugins	Manage plugins	bijux plugins list
config	Key-value settings	bijux config set core_timeout=5
history	REPL history	bijux history --limit 10
audit	Security checks	bijux audit --dry-run
docs	Generate specs/docs	bijux docs --out spec.json
dev	Introspection (DI, plugins)	bijux dev di
sleep	Pause	bijux sleep -s 5
version	Version info	bijux version

Back to top

---

When to Use (and Not Use)

Use if you need:

• Plugins for extensibility.
• Deterministic flags for CI/scripts. ADR-0002
• REPL for interactive workflows.
• DI for modular, testable design.

Overkill if:

• You’re building a tiny one-off script (Click/Typer may be simpler).
• You don’t need plugins/DI.

Back to top

---

Shell Completion

# Install (writes to your shell’s completion dir)
bijux --install-completion

# Or print the script for manual setup
bijux --show-completion

Zsh tip: Ensure compinit runs and your fpath includes the completion directory.

Back to top

---

Configuration & Paths

Precedence: flags > env > config > defaults.

• Config: ~/.bijux/.env (BIJUXCLI_CONFIG)
• History: ~/.bijux/.history (BIJUXCLI_HISTORY_FILE)
• Plugins: ~/.bijux/.plugins (BIJUXCLI_PLUGINS_DIR)

Example:

export BIJUXCLI_PLUGINS_DIR=./custom-plugins

Back to top

---

Tests & Quality

• Depth: 2,600+ tests across unit, integration, functional, and E2E layers.
• Coverage: 98%+ code coverage (measured via pytest-cov in CI).
• Determinism: CI runs the full suite on multiple Python versions (3.11+).
• Artifacts: JSON/YAML fixtures validate structured outputs; E2E simulates real usage (REPL, plugins, DI).
• Docs: Read the full testing guide → TESTS.md.

Quick commands:

make test         # all tests
make test-unit    # unit tests only
make test-e2e     # end-to-end tests only

Artifacts: Test Artifacts · JUnit report · HTML coverage report

Back to top

---

Project Tree

A guided map of the repository (what lives where, and why). See PROJECT_TREE.md for the full breakdown.

Quick glance:

api/            # OpenAPI schemas
config/         # Lint/type/security configs
docs/           # MkDocs site (Material)
makefiles/      # Task modules (docs, test, lint, etc.)
plugin_template/# Cookiecutter-ready plugin scaffold
scripts/        # Helper scripts (hooks, docs generation)
src/bijux_cli/  # CLI + library implementation
tests/          # unit / integration / functional / e2e

Back to top

---

Roadmap

• v0.2 — Async command support, richer plugin registry.
• v1.0 — Community plugin marketplace, benchmarks vs. alternatives.

Track progress and suggest features via Issues.

Back to top

---

Docs & Resources

• Site: https://bijux.github.io/bijux-cli/
• Changelog: https://github.com/bijux/bijux-cli/blob/main/CHANGELOG.md
• Repository: https://github.com/bijux/bijux-cli
• Issues: https://github.com/bijux/bijux-cli/issues
• Security (private reports): https://github.com/bijux/bijux-cli/security/advisories/new
• Tests: See TESTS.md
• Project Tree: See PROJECT_TREE.md
• Artifacts: Browse all reports & logs — index · Tests · Lint · Quality · Security · SBOM · API · Citation

When filing issues, include --debug output where possible.

Back to top

---

Contributing

Welcome! See CONTRIBUTING.md for setup, style, and tests. We label good first issue to help you get started.

Back to top

---

Acknowledgments

• Built on Typer (CLI), FastAPI (HTTP API), and Injector (DI).
• Inspired by Click, Typer, and Cobra.
• Thanks to early contributors and testers!

Back to top

---

License

MIT — see LICENSES/MIT.txt. © 2025 Bijan Mousavi.

Back to top

Changelog

All notable changes to Bijux CLI are documented here. This project adheres to Semantic Versioning and the Keep a Changelog format.

Unreleased

Added

• (add new entries via Towncrier fragments in changelog.d/)

Changed

• (add here)

Fixed

• (add here)

Back to top

---

[0.1.2] – 2025-08-17

Added

• New Documentation Engine: Introduced a new modular documentation builder in scripts/docs_builder/ that replaces the previous helper script.
• CI Artifact Pages: The documentation site now automatically generates detailed pages for all CI artifacts, including tests, linting, code quality, security, API tests, SBOMs, and citation files.
• Release Evidence: The publish workflow now downloads all artifacts from the CI run, packages them as evidence/*.tar.gz bundles, and attaches them to the GitHub Release for traceability.
• Build Hygiene: Makefiles now enforce a "hygienic" build process, ensuring all temporary files, caches, and build outputs are stored under the artifacts/ directory to prevent root directory pollution.

Changed

• CI/CD Overhaul:
  • The ci.yml workflow now uploads each category of artifact separately for better organization and downstream consumption.
  • The docs.yml workflow now waits for the main CI run to complete, downloads all artifacts, and uses them to build a data-rich documentation site.
  • The publish.yml workflow has been streamlined and made more robust, removing the optional "wait for docs" step and improving tag detection.
• Documentation Content: All top-level Markdown documents (README.md, USAGE.md, TESTS.md, TOOLING.md, CONTRIBUTING.md, etc.) have been significantly rewritten and expanded with tables of contents, back-to-top links, and cross-references to the new artifact pages.
• Build System:
  • All Makefile modules have been refactored to use the new hygienic artifacts/ directory structure for outputs and caches.
  • tox.ini has been updated to align with the new Makefile targets and to run a comprehensive suite of checks for the py311 environment, mirroring the full CI validation process.
• API Schema: The OpenAPI schema.yaml has been improved with stricter validation (additionalProperties: false), better descriptions, response links, and more detailed examples.
• Source Code: Refactored async handling in src/bijux_cli/api.py and improved type safety across multiple modules by removing pyright: ignore comments and adding explicit cast calls where necessary.

Fixed

• Type Safety: Resolved numerous previously ignored type errors throughout the codebase and test suite.
• API Endpoint Logic: Corrected the item update logic in src/bijux_cli/httpapi.py by removing a faulty check for duplicate names that was causing incorrect 409 Conflict errors.
• Test Suite: Improved the stability and correctness of E2E tests by enhancing golden file comparisons and fixing brittle assertions.

Back to top

0.1.1 – 2025-08-14

Added

• Publish pipeline: GitHub Actions publish.yml that publishes via make publish only after required checks are green and a tag is present.
• Project map: PROJECT_TREE.md (and docs/project_tree.md) with a curated overview.
• Developer Tooling page: TOOLING.md (and docs/tooling.md) with embedded configs, Makefile snippets, and CI workflows via include-markdown.
• Docs assets: Community landing page, Plausible analytics partial, and CSS overrides.

Changed

• Docs generator (scripts/helper_mkdocs.py):
  • Copies README, USAGE, TESTS, PROJECT_TREE, and TOOLING into the site with link rewrites and {#top} anchors.
  • Generates mkdocstrings pages for all modules under src/bijux_cli/**.
  • Builds one consolidated API Reference with this structure:
    • top: Api Module, Cli Module, Httpapi Module
    • sections (collapsed by default): Commands, Contracts, Core, Infra, Services
    • nested groups for command subpackages (config/, dev/, history/, memory/, plugins/) beneath Commands.
  • Emits reference/**/index.md to power Material’s section indexes.
• MkDocs config (mkdocs.yml): tightened plugin ordering and settings for include-markdown, enabled section indexes, and strict mode; added watch paths for configs and scripts.
• README / USAGE: Refined copy; standardized top anchors and links to TESTS.md/PROJECT_TREE.md/TOOLING.md.
• SECURITY.md: Rewritten with clearer reporting, SLAs, scope, and safe harbor.
• Makefiles: macOS-safe env handling; Cairo-less Interrogate wrapper for doc coverage.
• Config: Expanded lints/dictionary.

Fixed

• Docs build (strict): resolved broken/unknown links in TOOLING.md and removed duplicate API Reference sections; left sidebar now stays populated when deep-linking into API pages.
• Tests: E2E version fixtures cleaned up.

Packaging

• PyPI links corrected: project.urls now points to accurate Homepage/Docs/Changelog/Issues/Discussions.
• Dynamic versioning from Git tags: Using hatch-vcs with dynamic = ["version"]; annotated tags like v0.1.1 define the release version. commitizen tags as v$version.
• Richer PyPI description: hatch-fancy-pypi-readme renders README.md + CHANGELOG.md on PyPI.
• Wheel/Sdist layout: Explicit Hatch build config ensures py.typed, licenses, and metadata are included.

Back to top

---

0.1.0 – 2025-08-12

Added

• Core runtime

  • Implemented Dependency Injection kernel, REPL shell, plugin loader, telemetry hooks, and shell completion (bash/zsh/fish).
  • Added core modules: api, cli, httpapi, core/{constants,context,di,engine,enums,exceptions,paths}.

• Contracts layer (contracts/)

  • Defined protocols for audit, config, context, docs, doctor, emitter, history, memory, observability, process, registry, retry, serializer, telemetry.
  • Added py.typed markers for downstream type checking.

• Services layer

  • Implemented concrete services for audit, config, docs, doctor, history, memory.
  • Built plugin subsystem: plugins/{entrypoints,groups,hooks,registry}.

• Infra layer (infra/)

  • Implemented emitter, observability, process, retry, serializer, telemetry.

• Command suite

  • Added top-level commands: audit, docs, doctor, help, repl, sleep, status, version.
  • Added config/ commands: clear, export, get, list, load, reload, set, unset, service.
  • Added dev/ commands: di, list-plugins, service.
  • Added history/ commands: clear, service.
  • Added memory/ commands: clear, delete, get, list, set, service.
  • Added plugins/ commands: check, info, install, list, scaffold, uninstall.

• Structured output & flags

  • Added JSON/YAML output via --format, pretty printing, and deterministic global flag precedence (ADR-0002).

• API contract validation & testing

  • Automated lint/validation of api/*.yaml with Prance, OpenAPI Spec Validator, Redocly, and OpenAPI Generator.
  • Added Schemathesis contract testing against the running server.
  • Pinned OpenAPI Generator CLI version via OPENAPI_GENERATOR_VERSION and automated Node.js toolchain setup in Makefile.

• Documentation tooling

  • Integrated MkDocs (Material), mkdocstrings, literate-nav, and ADR index generation.

• Quality & security pipeline

  • Added formatting/linting: ruff (+format).
  • Added typing: mypy, pyright, pytype.
  • Added docs style/coverage: pydocstyle, interrogate.
  • Added code health: vulture, deptry, radon, codespell, reuse.
  • Added security: bandit, pip-audit.
  • Added mutation testing: mutmut, cosmic-ray.

• SBOM

  • Generated CycloneDX JSON for prod/dev dependencies via make sbom (uses pip-audit).

• Citation

  • Validated CITATION.cff and added export to BibTeX/RIS/EndNote formats via make citation.

• Makefile architecture

  • Modularized the Makefile into makefiles/*.mk for maintainability and clear separation of concerns.
  • Centralized all developer workflows (test, lint, quality, security, api, docs, build, sbom, citation, changelog, publish) in one consistent interface.
  • Added bootstrap target for idempotent virtualenv setup and Git hook installation from scripts/git-hooks (skips re-installation if already linked).
  • Added all-parallel target to run independent checks (quality, security, api, docs) concurrently for faster CI/CD.
  • Added make help for self-documenting targets with grouped sections.
  • Provided helper macros (run_tool, read_pyproject_version) to standardize tooling invocation.

• pre-commit

  • Added hygiene hooks: ruff-format + ruff, mdformat, and codespell.
    • Enforced Conventional Commits via commitizen commit-msg hook.

• tox orchestration

  • Configured multi-Python test envs (py311, py312, py313).
  • Mapped Makefile workflows into tox envs (lint, quality, security, api, docs, build, sbom, changelog, citation) to ensure reproducibility.
  • Passed MAKEFLAGS to execute Makefile targets inside tox-managed virtualenvs.

• Continuous Integration

  • Added GitHub Actions workflow running tox across Python versions with Node.js 20 and Java 17 for API checks.
  • Added GitLab CI sample mirroring the GitHub workflow (tox-driven) with artifacts for coverage and API logs.
  • CI/CD pipelines directly leverage the modularized Makefile for consistent local/CI behavior.

• Packaging / PyPI page

  • Built dynamic long description via hatch-fancy-pypi-readme from README.md and CHANGELOG.md for PyPI/TestPyPI.
  • Packaged with LICENSES/, REUSE.toml, CITATION.cff, and py.typed included in source distributions.

Changed

• Released initial public version.

Fixed

• None

Back to top