kantrip 0.1.0a1__tar.gz

kantrip-0.1.0a1/.gitignore

@@ -0,0 +1,67 @@
+##### github.com: Python.gitignore #####
+
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+coverage.xml
+
+# Environments and local secrets
+.env
+!sandbox/.env
+.venv/
+.release-venv/
+env/
+venv/
+ENV/
+
+# Type and lint caches
+.mypy_cache/
+.dmypy.json
+.ruff_cache/
+.hypothesis/
+
+# Editors and operating systems
+.vscode/
+.idea/
+.DS_Store
+
+# Local Kantrip state must never enter the repository
+.kantrip/
+kantrip-local/
+*.pem
+*.key
+*.p12
+*.jks
+
+# Internal planning notes
+KANTRIP_MVP_PLAN.md

kantrip-0.1.0a1/AGENT.md

@@ -0,0 +1,111 @@
+# Agent Instructions
+
+## Engineering Contract
+
+- Treat this file as living operational knowledge. When work establishes or
+  changes a durable convention, update this guidance and every affected guide,
+  schema, fixture, example, issue template, and command sample. Rewrite obsolete
+  or duplicate guidance instead of appending contradictions.
+- Do not add empty modules or speculative adapters. Keep cyclomatic complexity
+  at or below 10; repository-wide Ruff `C901` runs in `scripts.analyze`, so use
+  focused helpers instead of suppressions.
+- Importing `kantrip` must not create directories, open files, configure logging,
+  construct consoles, or contact Kafka. Classify and redact values before
+  presentation, and keep command behavior independent from Rich.
+- Support Linux and macOS on Python 3.10 through 3.14. Keep paths, permissions,
+  signals, terminals, and shell documentation portable.
+- Keep unimplemented product work in `MVP.md`, not in current feature docs,
+  schemas, examples, commands, or implementation comments.
+
+## Profiles and Sessions
+
+- The profile schema lives in `schemas/`, examples in `examples/`, and synthetic
+  test data inside its owning test module. Keep it limited to implemented
+  behavior and synchronize examples, tests, and migration notes when it changes.
+  Schema filenames and configuration documents do not duplicate the application
+  version; the schema shipped by an application release is authoritative.
+- Treat the environment documented in `USAGE.md` as public API. Add variables
+  compatibly; renames or semantic breaks require release and migration guidance.
+  Use `KAFKA_*` for application values and reserve `KANTRIP_*` for
+  Kantrip-owned profile/session metadata.
+- `kantrip add` creates missing configuration. Add/remove operations are validated
+  and atomic, adding an existing profile never overwrites it, and listing missing
+  configuration returns an empty collection.
+- Inject the documented environment only into supervised children; never mutate
+  the caller's environment or add a separate JSON schema for environment values.
+- Reject `kantrip exec` when `KANTRIP_SESSION_ID` identifies an active parent
+  session. The schema and execution accept only `transport: plaintext` with
+  `auth.type: none`.
+
+## Client Adapters and Shells
+
+- kcat is the first supported client. Sessions expose private generated librdkafka
+  properties through `KCAT_CONFIG`; interactive shims preserve this contract and
+  reject client attempts to override it with `-F`. Never place configuration
+  values in command arguments.
+- Official Kafka tools recognize names with and without `.sh`. All receive
+  `--bootstrap-server`; consumers/producers receive their client config option,
+  and administrative tools receive `--command-config`, pointing at the private
+  generated Java properties file.
+- Kaskade `admin` and `consumer` receive a private INI file through
+  `--config-file`. Do not assume a Kaskade environment variable until Kaskade
+  implements that contract.
+- Interactive sessions support Bash, Zsh, and Fish. They load normal user startup
+  files, preserve normal history, neutralize aliases/functions/Fish abbreviations
+  for registered adapters, and restore the session shim path. Shims are private
+  and temporary; never install persistent aliases.
+- Adapters must reject connection arguments that override the selected profile.
+
+## Sensitive Values and Output
+
+- Never expose sensitive values in arguments, fixtures, logs, output,
+  diagnostics, tracebacks, or snapshots. Examples use conspicuously synthetic
+  values and infrastructure.
+- Send command results to stdout and diagnostics to stderr. Styling respects
+  `NO_COLOR`, `TERM=dumb`, `--no-color`, and non-TTY output; use text status labels
+  instead of emoji when styling is disabled.
+
+## Tests, Scripts, and Sandbox
+
+- Tests and their fixtures live in `tests` and remain offline. Shared workflow
+  helpers belong in `scripts/__init__.py`; other script modules are executable
+  workflows.
+- The manual environment lives in `sandbox`, including Compose definitions,
+  versions, synthetic data, and population tools. Tests may inspect pinned image
+  versions and Compose structure, but sandbox code and test fixtures must not
+  import each other.
+- `python -m sandbox` runs the adapter smoke workflow against an active sandbox
+  with locally installed clients and optional shells. It is a pre-commit hook,
+  not an offline or packaged E2E test.
+- `python -m scripts.verify_shell_contract` verifies Bash, Zsh, and Fish with
+  PTYs and generated fake clients. Assertions stay in Python; its temporary event
+  logs contain only safe metadata and are removed with their temporary directory.
+
+## Verification
+
+Run these checks after code, environment, schema, tooling, or documentation work:
+
+```text
+uv run --locked python -m scripts.analyze
+uv run --locked python -m scripts.tests
+uv build --clear
+uv run --locked python -m scripts.verify_release dist
+```
+
+Regenerate `images/banner.svg` with `uv run --locked python -m scripts.banner`
+when the banner, console theme, or SVG helper changes.
+
+## Releases and Contributions
+
+- Annotated `vMAJOR.MINOR.PATCH` and `vMAJOR.MINOR.PATCHaN` tags on `main` are
+  the only release version source; Hatchling and hatch-vcs derive package
+  metadata from Git. GitHub Releases are the canonical changelog, so do not add
+  maintained changelogs or version-bump commits.
+- Never hard-code the current release version in documentation, templates,
+  examples, or commands. Use `kantrip --version`, `MAJOR.MINOR.PATCH`, or Git
+  metadata so releases need no follow-up edits.
+- Commits and pull-request titles use Conventional Commits:
+  `<type>(<optional scope>): <imperative summary>`. Keep the summary short and do
+  not use it as a change list.
+- End commit messages and pull-request descriptions with a blank line followed by
+  `Assisted-by: <AI model> <version>`, using the actual model and version.

kantrip-0.1.0a1/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Architecture Decisions
+
+This document records behavior implemented by Kantrip today. Planned design is
+kept in `MVP.md` until it is implemented.
+
+## Plaintext profiles
+
+Profiles contain non-secret Kafka broker metadata. The bundled schema accepts
+only plaintext transport without authentication, plus descriptions, labels, and
+Java or librdkafka client properties. Profile updates are schema-validated and
+atomically replace the configuration file with mode `0600`.
+
+The configuration path follows `KANTRIP_CONFIG`, then `XDG_CONFIG_HOME`, then
+`~/.config/kantrip/config.yaml`. Profile names and paths are treated as untrusted
+input, and profile display passes through the redaction layer.
+
+## Kantrip sessions
+
+`kantrip exec` runs one command or interactive Bash, Zsh, or Fish subshell for a
+selected profile. Nested sessions are rejected. Each session uses a randomly
+named temporary directory containing private generated client configuration and,
+for interactive shells, adapter shims. Python's temporary-directory lifecycle
+removes those artifacts when the supervised command returns.
+
+The child receives `KANTRIP_PROFILE`, `KANTRIP_SESSION_ID`, and
+`KANTRIP_SESSION_DIR`; the caller's parent environment is never modified. The
+child also receives the documented plaintext `KAFKA_*` and `KCAT_CONFIG` values.
+
+## Client adapters
+
+Supported adapters inject the selected bootstrap servers and generated client
+configuration using each tool's native interface. kcat reads `KCAT_CONFIG`,
+official Kafka commands receive connection and properties-file arguments, and
+Kaskade `admin` and `consumer` receive a generated INI file. Options that would
+override the selected profile are rejected.
+
+Interactive shells load the user's normal startup configuration and history.
+Kantrip then removes aliases, functions, and Fish abbreviations that shadow
+supported client names, restores the session shim directory at the front of
+`PATH`, and refreshes command lookup.
+
+## Diagnostics and output
+
+`kantrip doctor` performs read-only local checks. It validates configuration,
+file permissions, profile IDs, runtime support, active-session state, shim-path
+precedence, and installed client commands without contacting Kafka.
+
+Kantrip executes children directly with argument arrays. Normal command output
+and diagnostics remain separate, sensitive-looking values are redacted before
+presentation, and styling follows terminal capability, `NO_COLOR`, `TERM=dumb`,
+and `--no-color`.

kantrip-0.1.0a1/COMPATIBILITY.md

@@ -0,0 +1,25 @@
+# Command compatibility
+
+Kantrip recognizes commands by executable basename. Apache Kafka 2.6 is the
+oldest CLI surface Kantrip guarantees; newer clients can connect to older brokers
+subject to Apache Kafka's normal client/broker compatibility. Both unsuffixed
+commands and the `.sh` variants shipped in Apache Kafka distributions are
+supported.
+
+Interactive sessions support Bash, Zsh, and Fish on Linux and macOS. Kantrip
+loads normal user startup configuration and history, then restores its temporary
+adapter executables after startup-time aliases, functions, abbreviations, and
+`PATH` changes. When `SHELL` is unset, an installed Bash is used. Other shells
+are not supported.
+
+| Supported command | CLI version | Kafka behavior | Notes |
+| --- | --- | --- | --- |
+| `kafka-console-consumer[.sh]` | Apache Kafka 2.6–4.3 | Consume records | Injects `--bootstrap-server` and `--consumer.config`; Kafka 4.3 deprecates the config flag ahead of its planned Kafka 5.0 removal. |
+| `kafka-console-producer[.sh]` | Apache Kafka 2.6–4.3 | Produce records | Injects `--bootstrap-server` and `--producer.config`; Kafka 4.3 deprecates the config flag ahead of its planned Kafka 5.0 removal. |
+| `kafka-topics[.sh]` | Apache Kafka 2.6+ | Create, list, describe, alter, and delete topics | Injects `--bootstrap-server` and `--command-config`. |
+| `kafka-consumer-groups[.sh]` | Apache Kafka 2.6+ | Inspect and manage consumer groups | Injects `--bootstrap-server` and `--command-config`. |
+| `kafka-configs[.sh]` | Apache Kafka 2.6+ | Inspect and alter supported dynamic configurations | Injects `--bootstrap-server` and `--command-config`; broker authorization still applies. |
+| `kafka-acls[.sh]` | Apache Kafka 2.6+ | List, add, and remove ACLs | Injects `--bootstrap-server` and `--command-config`; requires a configured authorizer and an authorized principal. |
+| `kafka-broker-api-versions[.sh]` | Apache Kafka 2.6+ | Inspect broker protocol versions | Injects `--bootstrap-server` and `--command-config`. |
+| `kcat` / `kafkacat` | kcat 1.7+ | Metadata, produce, and consume | Uses a private `KCAT_CONFIG`; explicit `-F` is rejected. |
+| `kaskade` | Kaskade 4.0+ | Administer and consume | Uses a private INI file for `admin` and `consumer`. |

kantrip-0.1.0a1/DEVELOPMENT.md

@@ -0,0 +1,228 @@
+# Development Instructions
+
+## Setup
+
+Install uv:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# or on macOS
+brew install uv
+```
+
+Create the project environment and install locked development dependencies:
+
+```bash
+uv sync --locked
+```
+
+The project is installed in editable mode. Run the CLI with:
+
+```bash
+uv run kantrip --help
+uv run kantrip --version
+```
+
+Install pre-commit hooks with:
+
+```bash
+uv run pre-commit install
+```
+
+## Scripts
+
+Apply code styles:
+
+```bash
+uv run python -m scripts.styles
+```
+
+Run type, formatting, lint, spelling, and workflow analysis:
+
+```bash
+uv run python -m scripts.analyze
+```
+
+Run the offline unit tests:
+
+```bash
+uv run python -m scripts.tests
+```
+
+Generate the deterministic Rich README banner:
+
+```bash
+uv run python -m scripts.banner
+```
+
+Reusable script code belongs in `scripts/__init__.py`; individual modules are
+executable workflows. Tests and fixture utilities remain under their owning test
+suite, and manual-environment utilities remain under `sandbox`. The sandbox smoke
+command is intentionally separate from the offline test suite.
+
+## Schema and application environment
+
+The profile JSON Schema lives in `schemas/`. Synthetic user-facing examples live
+in `examples/`. Test-owned fixture copies live under `tests` and must never
+contain private infrastructure details.
+
+Application environment variables are documented in `USAGE.md`. When a variable
+changes, update the usage and architecture documentation and the relevant tests
+together.
+
+## Build artifacts
+
+Build the wheel and source distribution:
+
+```bash
+uv build --clear
+```
+
+Verify versions, entry points, the packaged profile schema, public examples, and
+required documentation:
+
+```bash
+uv run --locked python -m scripts.verify_release dist
+```
+
+An exact `vMAJOR.MINOR.PATCH` or `vMAJOR.MINOR.PATCHaN` tag produces a release
+version. Untagged builds use
+hatch-vcs development metadata; the configured fallback exists only so an empty
+or exported pre-release checkout can bootstrap before the first commit.
+
+## Manual sandbox
+
+The sandbox is a manual environment, not a test-fixture provider. Automated tests
+must not import it.
+
+Start its three-node plaintext Kafka cluster:
+
+```bash
+docker compose --project-directory sandbox up -d
+```
+
+Stop it and remove its volumes:
+
+```bash
+docker compose --project-directory sandbox down -v
+```
+
+Kafka is available at `localhost:19092`, `localhost:29092`, and
+`localhost:39092`. The pinned Kafka image version lives in `sandbox/.env`.
+
+With the sandbox running and the supported clients installed locally, run the
+adapter smoke checks:
+
+```bash
+uv run --locked python -m sandbox
+uv run --locked python -m sandbox \
+  --shell bash --shell zsh --shell fish
+uv run --locked python -m sandbox my-topic \
+  --profile sandbox --bootstrap-server localhost:19092 --keep-topic
+```
+
+By default, the script creates and lists a randomized topic, produces and
+consumes a record, and exercises the groups, configs, ACLs, and broker API
+adapters. It also lists the topic with kcat, validates the Kaskade adapter, and
+deletes the topic. At least one executable variant for every official Kafka
+command must be installed. The check uses styled emoji output in a terminal and
+text status labels when styling is disabled, including in CI or when `--no-color`
+is passed.
+
+Repeat `--shell` to add real interactive-subshell checks after the explicit
+command pass. A requested shell is required to be installed; the three-shell
+command above verifies Bash, Zsh, and Fish with PTYs, including profile
+visibility, path restoration, and every installed adapter executable.
+
+The smoke script is also a pre-commit hook. Keep the sandbox running when making
+commits; this remains a local integration check rather than part of the offline
+unit-test suite.
+
+GitHub Actions separately runs a lightweight shell contract on Bash, Zsh, and
+Fish, including history persistence. It uses generated fake client executables instead of installing Kafka,
+kcat, Kaskade, Java, or Docker. The Python test owns the assertions and reads a
+temporary JSON-lines event log containing command names, safe arguments, config
+file modes, and session metadata. Logs are deleted with the test directory and
+sanitized output is shown only when a contract fails.
+
+Run that contract independently from the normal unit suite with:
+
+```bash
+KANTRIP_REQUIRED_SHELLS=bash,zsh,fish \
+  uv run --locked python -m scripts.verify_shell_contract
+```
+
+### End-to-end adapter workflow
+
+Create an isolated profile for the running sandbox, then create a topic, produce
+two records, and consume exactly those records:
+
+```bash
+uv run kantrip add sandbox --bootstrap-server localhost:19092
+
+uv run kantrip exec sandbox -- kafka-topics --create \
+  --topic kantrip-development --partitions 1 --replication-factor 1
+
+printf 'first record\nsecond record\n' | \
+  uv run kantrip exec sandbox -- kafka-console-producer \
+    --topic kantrip-development
+
+uv run kantrip exec sandbox -- kafka-console-consumer \
+  --topic kantrip-development --from-beginning --max-messages 2
+```
+
+Replace any official Kafka command with its `.sh` form when using an Apache Kafka
+distribution that retains the suffix.
+
+Additional quick checks for the other adapters are:
+
+```bash
+uv run kantrip exec sandbox -- kafka-consumer-groups --list
+uv run kantrip exec sandbox -- kafka-configs \
+  --describe --entity-type topics --entity-name kantrip-development
+uv run kantrip exec sandbox -- kafka-acls --version
+uv run kantrip exec sandbox -- kafka-broker-api-versions
+uv run kantrip exec sandbox -- kcat -L
+uv run kantrip exec sandbox -- kaskade admin
+
+uv run kantrip exec sandbox -- kafka-topics --delete \
+  --topic kantrip-development
+```
+
+The sandbox does not configure a Kafka authorizer, so use `--version` to validate
+the ACL adapter there. Listing or changing ACLs requires a cluster with an
+authorizer and a suitably authorized principal.
+
+## Architecture and security
+
+- Stable design decisions: [`ARCHITECTURE.md`](ARCHITECTURE.md)
+- Planned MVP work: [`MVP.md`](MVP.md)
+- Assets, threats, controls, and limitations: [`THREAT_MODEL.md`](THREAT_MODEL.md)
+- Private vulnerability reporting: [`SECURITY.md`](SECURITY.md)
+
+## Release
+
+Git tags are the only release-version source. GitHub Releases are the canonical
+release history; never edit a static package version or maintained changelog.
+Use the reusable [release checklist](RELEASE_CHECKLIST.md) to record preparation
+and post-release evidence for each candidate.
+
+Before releasing, ensure `main` is current, clean, and passing:
+
+```bash
+git switch main
+git pull --ff-only origin main
+git status --short
+uv lock --check
+uv run --locked python -m scripts.analyze
+uv run --locked python -m scripts.tests
+uv build --clear
+uv run --locked python -m scripts.verify_release dist
+```
+
+Create and push an annotated stable (`vMAJOR.MINOR.PATCH`) or alpha
+(`vMAJOR.MINOR.PATCHaN`) tag. The protected release
+workflow validates the tag against `main`, builds once, verifies and installs the
+wheel, generates Conventional Commit notes, attests the distributions, waits for
+approval, publishes through PyPI trusted publishing, and creates the GitHub
+Release from the same artifacts. Kantrip has no Docker release job.

kantrip-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saúl Piña
+
+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.

kantrip-0.1.0a1/MVP.md

@@ -0,0 +1,52 @@
+# MVP Roadmap
+
+Kantrip's current baseline is the plaintext profile workflow documented in
+`README.md` and `USAGE.md`. Items in this file are planned and are not supported
+until they move into the implementation, schema, tests, and current-feature
+documentation together.
+
+## 1. Session hardening
+
+- Supervise a child process group and forward termination signals explicitly.
+- Validate session-directory ownership, permissions, markers, and path
+  boundaries before use or cleanup.
+- Remove verified stale session directories left by abnormal termination.
+- Define and enforce behavior for background or detached descendants.
+
+## 2. Credentials and authenticated Kafka
+
+- Store long-lived secrets in macOS Keychain or a Linux Secret Service provider;
+  do not add plaintext or locally encrypted secret-file fallbacks.
+- Extend the profile schema and generated client files for TLS, SASL/PLAIN,
+  SCRAM-SHA-256, SCRAM-SHA-512, and mutual TLS.
+- Materialize certificates and private keys only in private session directories
+  and keep secrets out of command arguments and diagnostics.
+
+## 3. Connectivity and registry integration
+
+- Add `kantrip ping` for explicit broker connectivity and authentication checks.
+- Add Schema Registry profiles and tested mappings for Confluent-compatible and
+  Apicurio endpoints.
+- Add OAuth support, including the generic client-credentials flow and Strimzi
+  callback integration.
+
+## 4. Profile workflow
+
+- Add explicit persistent profile selection without modifying a parent shell.
+- Add migration tooling when a released schema needs a breaking change.
+- Extend `kantrip doctor` with credential-provider, certificate-expiry, and
+  stale-session diagnostics as those capabilities are implemented.
+
+## MVP non-goals
+
+- AWS MSK IAM authentication.
+- Windows support.
+- Docker-based distribution or a hosted Kantrip service.
+
+## Alpha configuration cleanup
+
+Early example configurations included a top-level `version: 1` field and schema
+sections for capabilities that were not implemented. The current alpha schema
+rejects those fields. Remove `version`, `defaults`, TLS, authentication,
+credential-reference, and Schema Registry sections; recreate the affected
+profiles as plaintext profiles with `kantrip add` when convenient.