bijux-cli 0.1.0__tar.gz

bijux_cli-0.1.0/.gitignore

@@ -0,0 +1,142 @@
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+Icon?
+$RECYCLE.BIN/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+*.whl
+*.spec
+
+# Environments
+.venv/
+.venv*/
+.env
+.envrc
+.env.*
+.conda/
+.condarc
+*.conda
+.direnv/
+.pdm.toml
+
+# Test/coverage
+.coverage
+.coverage.*
+.coverage/
+htmlcov/
+.tox/
+.nox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pytype/
+.hypothesis/
+.mutmut-cache/
+.cache/
+.noseids
+nosetests.xml
+test-results/
+*.cover
+*.prof
+profile_default/
+.benchmarks/
+.mutmut-cache
+
+# IDEs/editors
+.idea/
+.vscode/
+.vscode-test/
+*.code-workspace
+*.sublime-project
+*.sublime-workspace
+
+# Docs
+docs/_build/
+site/
+_build/
+doctrees/
+*.doctree
+
+# JS/Node
+node_modules/
+
+# Data/Bioinformatics
+*.bam
+*.bai
+*.cram
+*.crai
+*.sam
+*.vcf
+*.vcf.gz
+*.fai
+*.tar
+*.tar.gz
+*.h5
+*.hdf5
+*.sqlite
+*.sqlite3
+*.db
+*.mtx
+*.loom
+*.bw
+*.rda
+*.rds
+*.csv.gz
+*.tsv.gz
+results/
+output/
+out/
+.snakemake/
+*.singularity
+*.sif
+
+# Misc
+*.log
+*.out
+*.err
+*.pid
+*.tmp
+*.temp
+*.bak
+*.orig
+*.rej
+*~
+
+# Secrets
+secrets.*
+*.key
+*.pem
+.secret
+.secret.*
+session.sqlite
+
+# Local/project dev data
+.tmp_home/
+tmp/
+tmp*/
+.local/
+openapitools.json
+
+# bijux-cli
+comments.txt
+artifacts/
+artifacts

bijux_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to **Bijux CLI** are documented here.
+This project adheres to [Semantic Versioning](https://semver.org) and the
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+
+## [Unreleased]
+
+### Added
+
+* (add new entries via Towncrier fragments in `changelog.d/`)
+
+### Changed
+
+* (add here)
+
+### Fixed
+
+* (add here)
+
+---
+
+<!-- towncrier start -->
+
+## [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](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence/)).
+
+* **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
+
+[Unreleased]: https://github.com/bijux/bijux-cli/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bijux/bijux-cli/releases/tag/v0.1.0

bijux_cli-0.1.0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as:"
+title: "bijux-cli"
+version: "0.1.0"
+date-released: 2025-08-11
+authors:
+  - family-names: "Mousavi"
+    given-names: "Bijan"
+    orcid: "https://orcid.org/0009-0002-4092-2854"
+repository-code: "https://github.com/bijux/bijux-cli"
+url: "https://github.com/bijux/bijux-cli"
+license: "MIT"
+keywords: ["cli", "developer-tools", "plugins"]
+preferred-citation:
+  type: software
+  title: "bijux-cli"
+  version: "0.1.0"
+  authors:
+    - family-names: "Mousavi"
+      given-names: "Bijan"
+  year: 2025
+  month: 8
+  url: "https://github.com/bijux/bijux-cli"

bijux_cli-0.1.0/LICENSES/CC0-1.0.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

bijux_cli-0.1.0/LICENSES/MIT.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 Bijan Mousavi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

bijux_cli-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: bijux-cli
+Version: 0.1.0
+Summary: Lean, plug-in-driven CLI kernel
+Project-URL: Homepage, https://github.com/bijux/bijux-cli
+Project-URL: Repository, https://github.com/bijux/bijux-cli.git
+Project-URL: Bug Tracker, https://github.com/bijux/bijux-cli/issues
+Project-URL: Documentation, https://bijux.github.io/bijux-cli/
+Project-URL: Changelog, https://github.com/bijux/bijux-cli/releases
+Author-email: Bijan Mousavi <mousavi.bijan@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Bijan Mousavi
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+        associated documentation files (the "Software"), to deal in the Software without restriction, including
+        without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+        following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial
+        portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+        LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+        EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+        IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+        USE OR OTHER DEALINGS IN THE SOFTWARE.
+Keywords: cli,developer-tools,plugins
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.7
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: cookiecutter>=2.3.0
+Requires-Dist: cryptography>=44.0.1
+Requires-Dist: fastapi<1.0,>=0.110
+Requires-Dist: injector>=0.20.1
+Requires-Dist: orjson>=3.9.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: pluggy>=1.0.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: pydantic-settings~=2.0
+Requires-Dist: pydantic<3.0,>=2.9.2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rapidfuzz>=3.0.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: typer>=0.12.5
+Provides-Extra: dev
+Requires-Dist: anyio<5.0,>=4.4.0; extra == 'dev'
+Requires-Dist: bandit<2.0,>=1.7.10; extra == 'dev'
+Requires-Dist: black<26.0,>=25.1.0; extra == 'dev'
+Requires-Dist: build<2.0,>=1.0.3; extra == 'dev'
+Requires-Dist: codespell<3.0,>=2.3.0; extra == 'dev'
+Requires-Dist: commitizen<4.0,>=3.21.0; extra == 'dev'
+Requires-Dist: cosmic-ray>=4.0.0; extra == 'dev'
+Requires-Dist: deptry<1.0,>=0.10.0; extra == 'dev'
+Requires-Dist: hypothesis-jsonschema<1.0,>=0.23.0; extra == 'dev'
+Requires-Dist: hypothesis<7.0,>=6.103.0; extra == 'dev'
+Requires-Dist: interrogate<2.0,>=1.7.0; extra == 'dev'
+Requires-Dist: isort<6.0,>=5.11.0; extra == 'dev'
+Requires-Dist: mkdocs-gen-files; extra == 'dev'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin<2.0,>=1.2.0; extra == 'dev'
+Requires-Dist: mkdocs-include-markdown-plugin; extra == 'dev'
+Requires-Dist: mkdocs-literate-nav; extra == 'dev'
+Requires-Dist: mkdocs-material<10.0,>=9.5.39; extra == 'dev'
+Requires-Dist: mkdocs-redirects<2.0,>=1.2; extra == 'dev'
+Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'dev'
+Requires-Dist: mkdocstrings[python]<1.0,>=0.26.1; extra == 'dev'
+Requires-Dist: mutmut<3.0,>=2.1.0; extra == 'dev'
+Requires-Dist: mypy<2.0,>=1.11.2; extra == 'dev'
+Requires-Dist: openapi-spec-validator<1.0,>=0.7.1; extra == 'dev'
+Requires-Dist: pexpect<5.0,>=4.8.0; extra == 'dev'
+Requires-Dist: pip-audit<3.0,>=2.7.3; extra == 'dev'
+Requires-Dist: prance<1.0,>=0.22.0; extra == 'dev'
+Requires-Dist: pre-commit<4.0,>=3.8.0; extra == 'dev'
+Requires-Dist: pydocstyle<7.0,>=6.2.1; extra == 'dev'
+Requires-Dist: pyright<2.0,>=1.1.320; extra == 'dev'
+Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-benchmark<5.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov<7.0,>=6.2.1; extra == 'dev'
+Requires-Dist: pytest-rerunfailures<14.0,>=13.0; extra == 'dev'
+Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.4.1; extra == 'dev'
+Requires-Dist: pytype>=2024.10.11; extra == 'dev'
+Requires-Dist: radon<6.0,>=5.1.0; extra == 'dev'
+Requires-Dist: reuse<6.0.0,>=4.0.0; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.6.8; extra == 'dev'
+Requires-Dist: schemathesis<4.0,>=3.16.0; extra == 'dev'
+Requires-Dist: towncrier<25.0,>=23.0; extra == 'dev'
+Requires-Dist: twine<7.0,>=6.1.0; extra == 'dev'
+Requires-Dist: types-colorama<1.0,>=0.0.14; extra == 'dev'
+Requires-Dist: types-orjson<4.0,>=3.6.0; extra == 'dev'
+Requires-Dist: types-psutil<7.0,>=6.0.0; extra == 'dev'
+Requires-Dist: types-pyyaml<7.0,>=6.0.12; extra == 'dev'
+Requires-Dist: typing-extensions<5.0,>=4.5.0; extra == 'dev'
+Requires-Dist: uvicorn<1.0,>=0.30.1; extra == 'dev'
+Requires-Dist: vulture<3.0,>=2.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Bijux CLI
+
+**A modern, predictable, and extensible CLI framework** — with strict runtime contracts, a first-class plugin system, structured output, and built-in diagnostics.
+
+---
+
+## Features at a Glance
+
+* **Plugin-driven architecture** – add/override behavior without touching core.
+* **Deterministic global flags** – strict precedence for consistent behavior
+  *(see ADR: Global Flags Precedence)*.
+* **Dependency-Injection kernel** – decoupled services, easy to test.
+* **Interactive REPL** – persistent shell for exploration and debugging.
+* **Structured output** – JSON/YAML with pretty/compact controls.
+* **Diagnostics** – environment checks, DI graph inspection, plugin validation.
+
+---
+
+## Installation
+
+**Requires Python 3.11+**
+
+```bash
+# Recommended: isolated CLI install
+pipx install bijux-cli
+
+# Or via pip
+pip install bijux-cli
+```
+
+---
+
+## Quick Start
+
+```bash
+# See commands and global flags
+bijux --help
+
+# Run environment diagnostics
+bijux doctor
+
+# Start the interactive shell
+bijux
+bijux> help
+bijux> exit
+```
+
+---
+
+## Usage Examples
+
+### Structured Output (JSON/YAML)
+
+```bash
+# Compact JSON for scripting
+bijux status -f json --no-pretty
+
+# Pretty JSON for humans
+bijux status -f json --pretty
+
+# YAML
+bijux status -f yaml
+```
+
+### DI & Developer Introspection
+
+```bash
+# Inspect DI registrations
+bijux dev di -f json | jq
+
+# List loaded plugins
+bijux dev list-plugins
+```
+
+### Plugins
+
+```bash
+# Scaffold, install, and validate a plugin
+mkdir -p ./tmp_plugin && cd ./tmp_plugin
+bijux plugins scaffold my_plugin --template=../plugin_template --force
+cd ..
+bijux plugins install ./tmp_plugin/my_plugin --force
+bijux plugins check my_plugin
+bijux plugins list
+```
+
+---
+
+## Global Flags (Precedence)
+
+Higher priority wins and may short-circuit lower ones.
+
+| Priority | Flag(s)                     | Effect                                                                |
+|--------: |-----------------------------|-----------------------------------------------------------------------|
+| 1        | `-h`, `--help`              | Exit 0 immediately; ignore all other flags.                           |
+| 2        | `-q`, `--quiet`             | Suppress both stdout and stderr; exit code still reflects the result. |
+| 3        | `-d`, `--debug`             | Full diagnostics; implies `--verbose`, forces `--pretty`.             |
+| 4        | `-f, --format <json\|yaml>` | Choose structured output; invalid value → exit code `2`.              |
+| 5        | `--pretty`/`--no-pretty`    | Control indentation (default: `--pretty`).                            |
+| 6        | `-v`, `--verbose`           | Add runtime metadata; implied by `--debug`.                           |
+
+*Reference:* ADR-0002 Global Flags Precedence
+[https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence/](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence/)
+
+---
+
+## Built-in Commands
+
+| Command   | Purpose                        | Example                           |
+|-----------|--------------------------------|-----------------------------------|
+| `doctor`  | Environment health check       | `bijux doctor`                    |
+| `status`  | Show CLI status                | `bijux status -f json`            |
+| `repl`    | Interactive shell              | `bijux repl`                      |
+| `plugins` | Manage plugins                 | `bijux plugins list`              |
+| `config`  | Manage key-value settings      | `bijux config set core_timeout=5` |
+| `history` | REPL history operations        | `bijux history --limit 10`        |
+| `audit`   | Security/compliance audit      | `bijux audit --dry-run`           |
+| `docs`    | Docs/spec generation utilities | `bijux docs --out spec.json`      |
+| `dev`     | Developer tools (DI, plugins)  | `bijux dev di`                    |
+| `sleep`   | Pause execution                | `bijux sleep -s 5`                |
+| `version` | Display version info           | `bijux version`                   |
+
+Plugins are surfaced as top-level commands once installed.
+
+---
+
+## Shell Completion
+
+Enable tab completion (no sudo required):
+
+```bash
+# Install completion (zsh saves to ~/.zfunc)
+bijux --install-completion
+
+# Or print the script if you manage completions manually
+bijux --show-completion
+```
+
+Restart your shell afterward. For zsh, ensure `compinit` runs and your `fpath` includes the completions' directory.
+
+---
+
+## Configuration & Paths
+
+**Defaults** (overridable via env vars):
+
+* Config: `~/.bijux/.env` → `BIJUXCLI_CONFIG`
+* History: `~/.bijux/.history` → `BIJUXCLI_HISTORY_FILE`
+* Plugins: `~/.bijux/.plugins` → `BIJUXCLI_PLUGINS_DIR`
+
+**Resolution order:** CLI flags → Environment → Config file → Defaults
+
+Example override:
+
+```bash
+export BIJUXCLI_PLUGINS_DIR=./.plugins
+export BIJUXCLI_CONFIG=./.env
+export BIJUXCLI_HISTORY_FILE=./.history
+```
+
+---
+
+## Documentation
+
+* **User Guide:** [https://bijux.github.io/bijux-cli/usage/](https://bijux.github.io/bijux-cli/usage/)
+* **Contributing:** [https://bijux.github.io/bijux-cli/contributing/](https://bijux.github.io/bijux-cli/contributing/)
+* **Security Policy:** [https://bijux.github.io/bijux-cli/security/](https://bijux.github.io/bijux-cli/security/)
+* **Code of Conduct:** [https://bijux.github.io/bijux-cli/code\_of\_conduct/](https://bijux.github.io/bijux-cli/code_of_conduct/)
+
+---
+
+## Support & Security
+
+* **Issues:** please include `--debug` output where feasible.
+* **Vulnerabilities:** report privately via GitHub Security Advisory.
+  [https://github.com/bijux/bijux-cli/security/advisories/new](https://github.com/bijux/bijux-cli/security/advisories/new)
+
+---
+
+## License
+
+Released under the **MIT License**.
+[https://bijux.github.io/bijux-cli/license/](https://bijux.github.io/bijux-cli/license/)

bijux_cli-0.1.0/README.md

@@ -0,0 +1,183 @@
+# Bijux CLI
+
+**A modern, predictable, and extensible CLI framework** — with strict runtime contracts, a first-class plugin system, structured output, and built-in diagnostics.
+
+---
+
+## Features at a Glance
+
+* **Plugin-driven architecture** – add/override behavior without touching core.
+* **Deterministic global flags** – strict precedence for consistent behavior
+  *(see ADR: Global Flags Precedence)*.
+* **Dependency-Injection kernel** – decoupled services, easy to test.
+* **Interactive REPL** – persistent shell for exploration and debugging.
+* **Structured output** – JSON/YAML with pretty/compact controls.
+* **Diagnostics** – environment checks, DI graph inspection, plugin validation.
+
+---
+
+## Installation
+
+**Requires Python 3.11+**
+
+```bash
+# Recommended: isolated CLI install
+pipx install bijux-cli
+
+# Or via pip
+pip install bijux-cli
+```
+
+---
+
+## Quick Start
+
+```bash
+# See commands and global flags
+bijux --help
+
+# Run environment diagnostics
+bijux doctor
+
+# Start the interactive shell
+bijux
+bijux> help
+bijux> exit
+```
+
+---
+
+## Usage Examples
+
+### Structured Output (JSON/YAML)
+
+```bash
+# Compact JSON for scripting
+bijux status -f json --no-pretty
+
+# Pretty JSON for humans
+bijux status -f json --pretty
+
+# YAML
+bijux status -f yaml
+```
+
+### DI & Developer Introspection
+
+```bash
+# Inspect DI registrations
+bijux dev di -f json | jq
+
+# List loaded plugins
+bijux dev list-plugins
+```
+
+### Plugins
+
+```bash
+# Scaffold, install, and validate a plugin
+mkdir -p ./tmp_plugin && cd ./tmp_plugin
+bijux plugins scaffold my_plugin --template=../plugin_template --force
+cd ..
+bijux plugins install ./tmp_plugin/my_plugin --force
+bijux plugins check my_plugin
+bijux plugins list
+```
+
+---
+
+## Global Flags (Precedence)
+
+Higher priority wins and may short-circuit lower ones.
+
+| Priority | Flag(s)                     | Effect                                                                |
+|--------: |-----------------------------|-----------------------------------------------------------------------|
+| 1        | `-h`, `--help`              | Exit 0 immediately; ignore all other flags.                           |
+| 2        | `-q`, `--quiet`             | Suppress both stdout and stderr; exit code still reflects the result. |
+| 3        | `-d`, `--debug`             | Full diagnostics; implies `--verbose`, forces `--pretty`.             |
+| 4        | `-f, --format <json\|yaml>` | Choose structured output; invalid value → exit code `2`.              |
+| 5        | `--pretty`/`--no-pretty`    | Control indentation (default: `--pretty`).                            |
+| 6        | `-v`, `--verbose`           | Add runtime metadata; implied by `--debug`.                           |
+
+*Reference:* ADR-0002 Global Flags Precedence
+[https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence/](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence/)
+
+---
+
+## Built-in Commands
+
+| Command   | Purpose                        | Example                           |
+|-----------|--------------------------------|-----------------------------------|
+| `doctor`  | Environment health check       | `bijux doctor`                    |
+| `status`  | Show CLI status                | `bijux status -f json`            |
+| `repl`    | Interactive shell              | `bijux repl`                      |
+| `plugins` | Manage plugins                 | `bijux plugins list`              |
+| `config`  | Manage key-value settings      | `bijux config set core_timeout=5` |
+| `history` | REPL history operations        | `bijux history --limit 10`        |
+| `audit`   | Security/compliance audit      | `bijux audit --dry-run`           |
+| `docs`    | Docs/spec generation utilities | `bijux docs --out spec.json`      |
+| `dev`     | Developer tools (DI, plugins)  | `bijux dev di`                    |
+| `sleep`   | Pause execution                | `bijux sleep -s 5`                |
+| `version` | Display version info           | `bijux version`                   |
+
+Plugins are surfaced as top-level commands once installed.
+
+---
+
+## Shell Completion
+
+Enable tab completion (no sudo required):
+
+```bash
+# Install completion (zsh saves to ~/.zfunc)
+bijux --install-completion
+
+# Or print the script if you manage completions manually
+bijux --show-completion
+```
+
+Restart your shell afterward. For zsh, ensure `compinit` runs and your `fpath` includes the completions' directory.
+
+---
+
+## Configuration & Paths
+
+**Defaults** (overridable via env vars):
+
+* Config: `~/.bijux/.env` → `BIJUXCLI_CONFIG`
+* History: `~/.bijux/.history` → `BIJUXCLI_HISTORY_FILE`
+* Plugins: `~/.bijux/.plugins` → `BIJUXCLI_PLUGINS_DIR`
+
+**Resolution order:** CLI flags → Environment → Config file → Defaults
+
+Example override:
+
+```bash
+export BIJUXCLI_PLUGINS_DIR=./.plugins
+export BIJUXCLI_CONFIG=./.env
+export BIJUXCLI_HISTORY_FILE=./.history
+```
+
+---
+
+## Documentation
+
+* **User Guide:** [https://bijux.github.io/bijux-cli/usage/](https://bijux.github.io/bijux-cli/usage/)
+* **Contributing:** [https://bijux.github.io/bijux-cli/contributing/](https://bijux.github.io/bijux-cli/contributing/)
+* **Security Policy:** [https://bijux.github.io/bijux-cli/security/](https://bijux.github.io/bijux-cli/security/)
+* **Code of Conduct:** [https://bijux.github.io/bijux-cli/code\_of\_conduct/](https://bijux.github.io/bijux-cli/code_of_conduct/)
+
+---
+
+## Support & Security
+
+* **Issues:** please include `--debug` output where feasible.
+* **Vulnerabilities:** report privately via GitHub Security Advisory.
+  [https://github.com/bijux/bijux-cli/security/advisories/new](https://github.com/bijux/bijux-cli/security/advisories/new)
+
+---
+
+## License
+
+Released under the **MIT License**.
+[https://bijux.github.io/bijux-cli/license/](https://bijux.github.io/bijux-cli/license/)

bijux_cli-0.1.0/REUSE.toml

@@ -0,0 +1,35 @@
+version = 1
+
+# Config/docs/assets: public domain
+[[annotations]]
+path = [
+  "**/*.png", "**/*.svg", "**/*.ico", "**/*.gif", "**/*.jpg", "**/*.jpeg",
+  "**/*.html", "**/*.toml", "**/*.ini", "**/*.cfg", "**/*.conf",
+  "**/*.env", "**/*.env.*", "**/*.yaml", "**/*.yml", "**/*.json",
+  "**/*.cff", "**/*.dic", ".coverage*", ".gitattributes", ".gitignore",
+  "changelog.d/**", "**/.editorconfig", "artifacts/**", "scripts/git-hooks/**"
+]
+precedence = "override"
+SPDX-License-Identifier = "CC0-1.0"
+SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"
+
+# Templates: public domain
+[[annotations]]
+path = ["plugin_template/**"]
+precedence = "override"
+SPDX-License-Identifier = "CC0-1.0"
+SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"
+
+# Code: MIT
+[[annotations]]
+path = ["**/*.py", "**/*.pyi", "**/*.sh", "**/*.mk", "Makefile", "Dockerfile", "Dockerfile.*"]
+precedence = "closest"
+SPDX-License-Identifier = "MIT"
+SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"
+
+# Markdown docs: MIT
+[[annotations]]
+path = ["**/*.md"]
+precedence = "closest"
+SPDX-License-Identifier = "MIT"
+SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"

bijux_cli-0.1.0/config/README.md

@@ -0,0 +1,23 @@
+# Project Configuration
+
+This directory contains all configuration files for **`bijux-cli`** development and quality assurance.
+It is the **single source of truth** for code formatting, linting, type checking, testing, and security rules — ensuring every contributor works in a **predictable, consistent** environment.
+
+Centralizing these configurations ensures:
+
+* **One place** to update standards
+* **Identical behavior** across local and CI builds
+
+---
+
+## Quick Reference
+
+| File                              | Tool / Purpose                                                     |
+|-----------------------------------|--------------------------------------------------------------------|
+| **`bijux.dic`**                   | PyCharm / Codespell — custom dictionary for project-specific terms |
+| **`cosmic-ray.toml`**             | Cosmic Ray — mutation testing configuration                        |
+| **`coveragerc.ini`**              | Coverage.py — coverage measurement rules                           |
+| **`mypy.ini`**                    | Mypy — strict static type checking                                 |
+| **`pyrightconfig.json`**          | Pyright — fast static type analysis                                |
+| **`ruff.toml`**                   | Ruff — linting, formatting, and isort rules                        |
+

bijux_cli-0.1.0/plugin_template/README.md

@@ -0,0 +1,63 @@
+# {{cookiecutter.project\_name}}
+
+A starter template for building **Bijux CLI** plugins—clean, typed, and ready to ship.
+
+---
+
+## Quick start
+
+```bash
+# 1) Scaffold from this template (run from your workspace)
+mkdir -p ./tmp && cd ./tmp
+bijux plugins scaffold my_plugin --template=../plugin_template --force
+
+# 2) Install the new plugin (name inferred from folder basename)
+cd ..
+bijux plugins install ./tmp/my_plugin --force
+
+# 3) Verify it’s healthy
+bijux plugins check my_plugin
+bijux plugins info my_plugin
+bijux dev list-plugins
+```
+
+Uninstall anytime:
+
+```bash
+bijux plugins uninstall my_plugin
+```
+
+---
+
+## What you get
+
+* **Zero-boilerplate setup** for a Bijux plugin.
+* **Typed hooks** and a minimal command to extend the CLI.
+* **Structured output** (JSON/YAML) consistent with core flags.
+* Clear spots to add docs, tests, and CI later.
+
+> Once installed, plugins appear as **top-level commands** (or can register hooks to extend existing behavior).
+
+---
+
+## Develop & iterate
+
+During development, just reinstall over the existing copy:
+
+```bash
+# Make changes to your plugin, then:
+bijux plugins install ./tmp/my_plugin --force
+bijux plugins check my_plugin
+```
+
+Tip: keep your plugin under version control and add tests early.
+
+---
+
+## Need more?
+
+* List all installed plugins: `bijux plugins list`
+* Show details: `bijux plugins info <name|path>`
+* Validate structure/signature: `bijux plugins check <name|path>`
+
+Build well. Break nothing.

bijux_cli-0.1.0/pyproject.toml

@@ -0,0 +1,216 @@
+[build-system]
+requires = [
+  "hatchling>=1.27.0,<1.28",
+  "hatch-fancy-pypi-readme>=24.2,<26.0",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "bijux-cli"
+version = "0.1.0"
+description = "Lean, plug-in-driven CLI kernel"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+license = {file = "LICENSES/MIT.txt" }
+authors = [{ name = "Bijan Mousavi", email = "mousavi.bijan@gmail.com" }]
+keywords = ["cli", "developer-tools", "plugins"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Utilities",
+  "Framework :: FastAPI",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "typer>=0.12.5",
+  "click>=8.1.7",
+  "pydantic>=2.9.2,<3.0",
+  "pydantic-settings~=2.0",
+  "packaging>=23.0",
+  "injector>=0.20.1",
+  "fastapi>=0.110,<1.0",
+  "orjson>=3.9.0",
+  "pyyaml>=6.0.2",
+  "cookiecutter>=2.3.0",
+  "cryptography>=44.0.1",
+  "psutil>=6.0.0",
+  "rapidfuzz>=3.0.0",
+  "prompt_toolkit>=3.0.0",
+  "structlog>=24.4.0",
+  "colorama>=0.4.6",
+  "pluggy>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "types-PyYAML>=6.0.12,<7.0",
+  "types-orjson>=3.6.0,<4.0",
+  "types-colorama>=0.0.14,<1.0",
+  "types-psutil>=6.0.0,<7.0",
+  "typing-extensions>=4.5.0,<5.0",
+
+  "pytest>=8.4.1,<9.0",
+  "pytest-cov>=6.2.1,<7.0",
+  "pytest-asyncio>=1.0.0,<2.0",
+  "pytest-timeout>=2.4.0,<3.0",
+  "pytest-rerunfailures>=13.0,<14.0",
+  "pytest-benchmark>=4.0.0,<5.0",
+  "hypothesis>=6.103.0,<7.0",
+  "hypothesis-jsonschema>=0.23.0,<1.0",
+  "pexpect>=4.8.0,<5.0",
+
+  "black>=25.1.0,<26.0",
+  "isort>=5.11.0,<6.0",
+  "ruff>=0.6.8,<1.0",
+  "mypy>=1.11.2,<2.0",
+  "pytype>=2024.10.11",
+  "codespell>=2.3.0,<3.0",
+  "pyright>=1.1.320,<2.0",
+  "pydocstyle>=6.2.1,<7.0",
+  "radon>=5.1.0,<6.0",
+
+  "vulture>=2.7,<3.0",
+  "deptry>=0.10.0,<1.0",
+  "reuse>=4.0.0,<6.0.0",
+
+  "build>=1.0.3,<2.0",
+  "bandit>=1.7.10,<2.0",
+  "pip-audit>=2.7.3,<3.0",
+  "commitizen>=3.21.0,<4.0",
+
+  "interrogate>=1.7.0,<2.0",
+  "mkdocs>=1.6.1,<2.0",
+  "mkdocs-material>=9.5.39,<10.0",
+  "mkdocstrings[python]>=0.26.1,<1.0",
+  "mkdocs-git-revision-date-localized-plugin>=1.2.0,<2.0",
+  "mkdocs-include-markdown-plugin",
+  "mkdocs-gen-files",
+  "mkdocs-literate-nav",
+  "mkdocs-redirects>=1.2,<2.0",
+
+  "prance>=0.22.0,<1.0",
+  "openapi-spec-validator>=0.7.1,<1.0",
+  "schemathesis>=3.16.0,<4.0",
+  "anyio>=4.4.0,<5.0",
+  "uvicorn>=0.30.1,<1.0",
+
+  "pre-commit>=3.8.0,<4.0",
+  "twine>=6.1.0,<7.0",
+  "towncrier>=23.0,<25.0",
+
+  "mutmut>=2.1.0,<3.0",
+  "cosmic-ray>=4.0.0",
+]
+
+[project.scripts]
+bijux = "bijux_cli.__main__:main"
+
+[project.urls]
+"Homepage" = "https://github.com/bijux/bijux-cli"
+"Repository" = "https://github.com/bijux/bijux-cli.git"
+"Bug Tracker" = "https://github.com/bijux/bijux-cli/issues"
+"Documentation" = "https://bijux.github.io/bijux-cli/"
+"Changelog" = "https://github.com/bijux/bijux-cli/releases"
+
+# bijux start
+[tool.bijux]
+api_version = "0.1.0"
+# bijux end
+
+# hatch start
+[tool.hatch.build]
+include = [
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "LICENSES/**",
+  "REUSE.toml",
+  "CITATION.cff",
+  "src/bijux_cli/py.typed",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bijux_cli"]
+zip-safe = false
+include = ["/bijux_cli"]
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+fragments = [
+  { path = "README.md" },
+  { path = "CHANGELOG.md" },
+]
+# hatch end
+
+# deptry start
+[tool.deptry]
+ignore = ["DEP002", "DEP003"]
+# deptry end
+
+# interrogate start
+[tool.interrogate]
+fail-under = 98
+exclude = ["src/bijux_cli/core/di.py"]
+color = true
+# interrogate end
+
+# commitizen start
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = ["pyproject.toml:project.version"]
+tag_format = "v$version"
+update_changelog_on_bump = false
+version_files = ["pyproject.toml:project.version"]
+# commitizen end
+
+# towncrier start
+[tool.towncrier]
+filename = "CHANGELOG.md"
+directory = "changelog.d"
+title_format = "## [{version}] – {project_date}"
+issue_format = "[#{issue}](https://github.com/bijux/bijux-cli/issues/{issue})"
+start_string = "<!-- towncrier start -->"
+all_bullets = true
+single_file = true
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "New Features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Bug Fixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "docs"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "refactor"
+name = "Refactoring"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "chore"
+name = "Miscellaneous Chores"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "trivial"
+name = "Trivial"
+showcontent = false
+# towncrier end

bijux_cli-0.1.0/scripts/README.md

@@ -0,0 +1,84 @@
+# `scripts/`
+
+A small collection of **purpose-built developer utilities** for code hygiene, documentation automation, and release workflow integration.
+
+## Contents
+
+### 1. **Comment Harvester** (`helper_comments.py`)
+
+Scans a codebase for **all lines containing `#`** (including `# noqa`, `# type: ignore`, and TODO/FIXME notes).
+Useful for:
+
+* Building a **baseline** for linter/typing ignore rules.
+* Periodic triage of technical debt and ignored checks.
+
+**Example:**
+
+```bash
+python scripts/helper_comments.py src -o comments.txt -e .py .pyi
+```
+
+**Sample output:**
+
+```
+src/example.py
+12: def foo():  # noqa: E999
+47: # TODO: refactor
+```
+
+Notes:
+
+* Any `#` is treated as a comment (including shebangs and inline hashes in strings).
+* Skips unreadable files.
+* Respects `--ext` filter.
+
+---
+
+### 2. **MkDocs API & Navigation Generator** (`helper_mkdocs.py`)
+
+Generates **API reference pages** for all Python modules in `src/bijux_cli` and an auto-synced `nav.md` for [literate-nav](https://github.com/oprypin/mkdocs-literate-nav).
+
+Integrated into `mkdocs.yml`:
+
+```yaml
+plugins:
+  - gen-files:
+      scripts:
+        - scripts/helper_mkdocs.py
+  - literate-nav
+  - mkdocstrings
+```
+
+Run locally:
+
+```bash
+mkdocs serve    # preview
+mkdocs build    # build static site
+```
+
+---
+
+### 3. **Commit Hook – Changelog Fragment Generator** (`git-hooks/prepare-commit-msg`)
+
+A **Git `prepare-commit-msg` hook** that automatically creates a [Towncrier](https://towncrier.readthedocs.io/) changelog fragment when committing with a Conventional Commit message.
+
+Example:
+
+```bash
+feat(api): add streaming support
+```
+
+Automatically produces:
+
+```
+changelog.d/1691940245.feature.md
+```
+
+---
+
+## Workflow Philosophy
+
+* **Automation first**: anything repetitive belongs in a script or hook.
+* **Debt visibility**: helper comments are tracked, triaged, and expire.
+* **Docs in sync**: API navigation is regenerated automatically at build time.
+* **Release-ready commits**: hooks enforce fragment creation for changelog accuracy.