Files
ChaosCrypt/docs/BUILDING.md
T
dvs 2529edac1d v2.1.6: Restructure as a distributable library
Restructure ChaosCrypt from a single-file script into a complete,
installable Python package with three interfaces: a typed Python API, an
argument-driven CLI, and a bilingual interactive TUI.

The algorithm itself is unchanged. Ciphertexts and key files remain fully
interoperable with the original implementation in both directions, which is
enforced by dedicated tests rather than merely documented.

Added
- Library API: ChaosCrypt facade plus ChaosCryptCore for the raw algorithm
- Unified error hierarchy: 16 named types, all ChaosCryptError subclasses,
  rendering as ChaosCrypt_ERR_<Detail>_<Code>
- CLI: keygen, encrypt, decrypt, file, info, chpwd, tui, with --json output,
  stdin/stdout piping, and three password sources per secret
- Bilingual TUI: English default, runtime switch to Chinese, getpass password
  entry with a non-TTY fallback that keeps it scriptable
- Binary and file support: encrypt_bytes/decrypt_bytes and
  encrypt_file/decrypt_file
- Key management: change_key_password rewraps without altering key material;
  export_key_text/load_from_text move a key without touching disk
- Documentation: SECURITY.md with the full design and threat analysis, plus
  docs/ covering the API, CLI, architecture and build process
- Test suite: 92 tests across round-trips, binary safety, key management,
  error types, CLI, TUI, i18n and legacy interoperability
- Packaging: pyproject.toml, setup.py compatibility shim, MANIFEST.in,
  py.typed, examples, MIT licence

Fixed
- Conflicting --pwd option between the -p and -P groups prevented the CLI
  from starting at all
- Wrong key file password reported as file corruption (E002); structural
  validation now distinguishes it from a damaged file (E003)
- export_key_text produced key material without loading it into the instance
- Non-hexadecimal input was accepted as ciphertext and silently decrypted
  into garbage, making corruption indistinguishable from success; malformed
  input now raises E010 before any processing
- TUI failed under piped input because getpass requires a TTY
- TUI kept reading the default key file name after generating a new one

Changed
- Source tree reorganised: the package lives at chaoscrypt/, with tests,
  examples and legacy alongside it; documentation and build artefacts at the
  repository root
- Code comments unified in English; public docstrings document parameters,
  return values and raised exceptions
- English is now the default UI language
- ChaosCryptChat removed from the repository
- Attribution updated to Dvs (DvsXT); project URLs point to Gitea
2026-09-27 17:03:05 +08:00

357 lines
8.7 KiB
Markdown

# Building and Releasing
How to build, test, and publish ChaosCrypt.
---
## Requirements
| Tool | Version | Purpose |
|---|---|---|
| Python | 3.8+ | Runtime and build |
| `build` | 1.0+ | Building distributions |
| `twine` | 4.0+ | Validating and uploading |
| `pytest` | 7.0+ | Running the test suite |
Install the development dependencies:
```bash
pip install -e ".[dev]"
```
---
## Development setup
```bash
git clone https://git.dvscloud.net/dvs/ChaosCrypt
cd ChaosCrypt
pip install -e ".[dev]"
```
An editable install means changes to the source take effect immediately,
without reinstalling.
---
## Running the tests
```bash
pytest # everything
pytest chaoscrypt/tests/test_chaoscrypt.py # one module
pytest -k roundtrip # by name
pytest -x # stop at first failure
pytest -v # verbose
```
With coverage:
```bash
pytest --cov=chaoscrypt --cov-report=term-missing
```
### Test modules
| Module | Covers |
|---|---|
| `test_chaoscrypt.py` | Round-trips, binary safety, key management, errors, CLI, i18n |
| `test_tui.py` | Interactive interface, driven by piped key sequences |
| `test_legacy_interop.py` | Bidirectional compatibility with the original implementation |
The TUI tests work because the interface falls back from `getpass` to plain
`input` when stdin is not a terminal. That fallback exists for automation, so
it serves both purposes.
### Compatibility tests
`test_legacy_interop.py` imports `chaoscrypt/legacy/chaoscrypt_legacy.py`
directly and exchanges data in both directions:
```bash
pytest chaoscrypt/tests/test_legacy_interop.py -v
```
These tests are the enforcement mechanism for the claim that the algorithm
was ported without any behavioural change. If they fail, the compatibility
promise is broken.
---
## Building distributions
```bash
python -m build
```
This produces two artefacts in `dist/`:
| Artefact | Contents |
|---|---|
| `chaoscrypt-2.1.6.tar.gz` | Source distribution — everything needed to rebuild |
| `chaoscrypt-2.1.6-py3-none-any.whl` | Wheel — the installed package |
### What the wheel contains
Only the importable package:
```
chaoscrypt/__init__.py
chaoscrypt/_core.py
chaoscrypt/cli.py
chaoscrypt/tui.py
chaoscrypt/errors.py
chaoscrypt/i18n.py
chaoscrypt/__main__.py
chaoscrypt/py.typed
```
`tests/`, `examples/` and `legacy/` sit alongside the package in the source
tree but are excluded from the wheel by the explicit `packages` declaration in
`pyproject.toml`. They ship in the source distribution, because the tests are
useful to anyone building from source.
### Verifying the artefacts
```bash
twine check dist/*
```
Both files should report `PASSED`.
Inspect the wheel contents:
```bash
python -m zipfile -l dist/chaoscrypt-2.1.6-py3-none-any.whl
```
---
## Testing the build in isolation
Before publishing, verify the wheel installs and works in a clean environment
with no development dependencies present:
```bash
# Create a throwaway environment.
python -m venv /tmp/verify
/tmp/verify/bin/pip install dist/chaoscrypt-2.1.6-py3-none-any.whl
# No third-party dependencies should appear.
/tmp/verify/bin/pip list
# Exercise the command line.
cd /tmp
/tmp/verify/bin/chaoscrypt --version
/tmp/verify/bin/chaoscrypt keygen -k test.key -P keypass
/tmp/verify/bin/chaoscrypt encrypt "hello" -p userpass -k test.key -P keypass
# Exercise the API.
/tmp/verify/bin/python -c "
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt('test.key', 'keypass', auto_load=True)
token = cc.encrypt('verify', 'userpass')
assert cc.decrypt(token, 'userpass') == 'verify'
print('clean install verified')
"
```
On Windows, use `\tmp\verify\Scripts\` in place of `/tmp/verify/bin/`.
---
## Releasing
### 1. Update the version
The version appears in two places and both must agree:
- `pyproject.toml` — `version = "2.1.6"`
- `chaoscrypt/__init__.py` — `__version__ = "2.1.6"`
Update the changelog with a new dated section, then verify consistency:
```bash
python -c "
import chaoscrypt, tomllib
with open('pyproject.toml', 'rb') as f:
meta = tomllib.load(f)
assert chaoscrypt.__version__ == meta['project']['version'], 'version mismatch'
print('versions consistent:', chaoscrypt.__version__)
"
```
### 2. Clean previous artefacts
```bash
rm -rf dist/ build/ *.egg-info chaoscrypt/*.egg-info
```
### 3. Run the full test suite
```bash
pytest
```
Do not release with a failing test.
### 4. Build
```bash
python -m build
twine check dist/*
```
### 5. Test the built wheel
Run the isolated install procedure from the previous section.
### 6. Upload
To TestPyPI first, to confirm the metadata renders correctly:
```bash
twine upload --repository testpypi dist/*
```
Then to PyPI:
```bash
twine upload dist/*
```
Credentials come from `~/.pypirc`, environment variables, or an API token
entered at the prompt. Never commit them.
### 7. Tag the release
```bash
git tag -a v2.1.6 -m "ChaosCrypt 2.1.6"
git push origin v2.1.6
```
---
## Versioning policy
ChaosCrypt follows [Semantic Versioning](https://semver.org/):
| Change | Version bump |
|---|---|
| Breaking API change | Major |
| New functionality, backward compatible | Minor |
| Bug fix or documentation | Patch |
Additional guarantees for a given major version:
- the public API will not change incompatibly;
- error codes will not be renumbered;
- the key file format will not change;
- ciphertexts from any earlier release will continue to decrypt.
The algorithm is frozen. The package layout, documentation and tooling may
evolve freely within a major version.
---
## Continuous integration
A minimal GitHub Actions workflow:
```yaml
name: test
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
python-version: ["3.8", "3.11", "3.13"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- run: pip install -e ".[dev]"
- run: pytest
- run: python -m build
- run: twine check dist/*
```
Testing across operating systems matters here because the TUI and CLI handle
terminal behaviour, path separators and encoding differently on each.
---
## Project layout
```
ChaosCrypt/
├── README.md project overview
├── SECURITY.md design and threat analysis
├── CHANGELOG.md release history
├── LICENSE MIT
├── MANIFEST.in sdist contents
├── pyproject.toml build configuration
├── .gitignore
├── docs/ this directory
│ ├── README.md documentation index
│ ├── API.md Python API reference
│ ├── CLI.md command line reference
│ ├── ARCHITECTURE.md internal design
│ └── BUILDING.md this file
├── dist/ build artefacts (generated)
└── chaoscrypt/ source tree
├── __init__.py public API and facade
├── _core.py the algorithm
├── cli.py command line interface
├── tui.py interactive interface
├── errors.py error hierarchy
├── i18n.py UI strings
├── __main__.py python -m entry point
├── py.typed PEP 561 marker
├── tests/ test suite
├── examples/ runnable examples
└── legacy/ original implementation
```
---
## Troubleshooting
**`error: package directory 'chaoscrypt/chaoscrypt' does not exist`**
The `package-dir` mapping in `pyproject.toml` is wrong for this layout. The
package lives at `chaoscrypt/`, alongside `tests/` and `examples/`, so the
mapping must be:
```toml
[tool.setuptools]
packages = ["chaoscrypt"]
package-dir = { "chaoscrypt" = "chaoscrypt" }
```
**The wheel contains `tests/` or `examples/`**
The `packages` list is too broad. It should name only `chaoscrypt`, not use
automatic discovery, because discovery would find the sibling directories.
**`ModuleNotFoundError: No module named 'chaoscrypt'` after an editable install**
Check that the install registered the right directory:
```bash
python -c "import chaoscrypt, os; print(os.path.dirname(chaoscrypt.__file__))"
```
The path should point at the repository's `chaoscrypt/` directory.
**Tests pass locally but fail in CI**
Most often an encoding issue. The library explicitly uses UTF-8 for text I/O,
but locale settings can still affect terminal behaviour. The TUI tests set
`PYTHONIOENCODING=utf-8` and `NO_COLOR=1` for exactly this reason.