Metadata-Version: 2.4
Name: cockpit-cli
Version: 0.1.3
Summary: Keyboard-first TUI platform for developer workspaces.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cffi>=1.17
Requires-Dist: packaging>=24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: textual>=0.58.0
Provides-Extra: all-datasources
Requires-Dist: chromadb>=0.5; extra == 'all-datasources'
Requires-Dist: duckdb-engine>=0.13; extra == 'all-datasources'
Requires-Dist: duckdb>=1.1; extra == 'all-datasources'
Requires-Dist: google-cloud-bigquery>=3.30; extra == 'all-datasources'
Requires-Dist: ibis-framework>=10.0; extra == 'all-datasources'
Requires-Dist: mariadb>=1.1; extra == 'all-datasources'
Requires-Dist: psycopg[binary]>=3.2; extra == 'all-datasources'
Requires-Dist: pybigquery>=0.10; extra == 'all-datasources'
Requires-Dist: pymongo>=4.10; extra == 'all-datasources'
Requires-Dist: pymysql>=1.1; extra == 'all-datasources'
Requires-Dist: pyodbc>=5.1; extra == 'all-datasources'
Requires-Dist: redis>=5.0; extra == 'all-datasources'
Requires-Dist: snowflake-sqlalchemy>=1.6; extra == 'all-datasources'
Provides-Extra: analytics
Requires-Dist: ibis-framework>=10.0; extra == 'analytics'
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3.30; extra == 'bigquery'
Requires-Dist: pybigquery>=0.10; extra == 'bigquery'
Provides-Extra: chroma
Requires-Dist: chromadb>=0.5; extra == 'chroma'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: textual>=0.58.0; extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: duckdb-engine>=0.13; extra == 'duckdb'
Requires-Dist: duckdb>=1.1; extra == 'duckdb'
Provides-Extra: mariadb
Requires-Dist: mariadb>=1.1; extra == 'mariadb'
Provides-Extra: mongo
Requires-Dist: pymongo>=4.10; extra == 'mongo'
Provides-Extra: mssql
Requires-Dist: pyodbc>=5.1; extra == 'mssql'
Provides-Extra: mysql
Requires-Dist: pymysql>=1.1; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: cyclonedx-bom>=4.2; extra == 'release'
Requires-Dist: sigstore>=3.6; extra == 'release'
Provides-Extra: secrets
Requires-Dist: cryptography>=44.0; extra == 'secrets'
Requires-Dist: keyring>=25.6; extra == 'secrets'
Provides-Extra: snowflake
Requires-Dist: snowflake-sqlalchemy>=1.6; extra == 'snowflake'
Provides-Extra: vault
Requires-Dist: cryptography>=44.0; extra == 'vault'
Requires-Dist: keyring>=25.6; extra == 'vault'
Description-Content-Type: text/markdown

# cockpit-cli

Keyboard-first developer workspace cockpit for Linux.

`cockpit-cli` combines a Textual TUI, a local web admin plane, persisted sessions,
guarded mutating actions, and a plugin-capable datasource platform. The app is
Linux-first and optimized for local development, SSH-backed environments, and
operator workflows that need one command/event model across terminal, Git,
Docker, Cron, DB, HTTP, and layout management.

## Core Capabilities

- persisted workspaces and sessions backed by SQLite
- local and SSH-backed workspaces with resume across restarts
- Textual TUI with `Work`, `Git`, `Docker`, `Cron`, `DB`, `Curl`, and `Logs`
- editable split layouts with persisted variants
- command palette, slash commands, and keybindings through one dispatcher
- guarded mutating flows for Docker, Cron, DB, and HTTP actions
- local web admin for datasource profiles, plugin installs, layouts, and diagnostics
- Vault-first secret registry with compatibility providers for env, file, and keyring
- plugin install/update/pin/remove with repo or package requirements
- plugin compatibility, permission allowlists, and on-disk integrity verification before runtime activation
- broad datasource support through SQLAlchemy dialects plus non-SQL adapters
- terminal scrollback, search, keyboard or mouse-assisted selection, export, and clipboard copy

## Supported Datasource Families

Built-in datasource profiles support these backends:

- `sqlite`
- `postgres` / `postgresql`
- `mysql`
- `mariadb`
- `mssql`
- `duckdb`
- `bigquery`
- `snowflake`
- `mongodb`
- `redis`
- `chromadb`

Relational and analytics backends run through SQLAlchemy with external dialects
where appropriate. Non-SQL backends use dedicated adapters. Additional
datasources can be supplied by plugins.

## Tech Stack

- Python 3.11+
- Textual
- SQLite
- YAML + TCSS
- SQLAlchemy
- optional Ibis and backend-specific drivers

## Repository Layout

```text
config/
  commands.yaml
  connections.example.yaml
  datasources.example.yaml
  keybindings.yaml
  layouts/
  plugins.example.yaml
  themes/
docs/
  superpowers/
packaging/
  arch/
src/cockpit/
tests/
```

## Installation

### Core install

```bash
git clone git@github.com:DamienDrash/cockpit_cli.git
cd cockpit_cli
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

### Full datasource install

```bash
pip install -e '.[all-datasources]'
```

Or install only the extras you need, for example:

```bash
pip install -e '.[postgres,mysql,duckdb,mongo,redis]'
```

Enable Vault, encrypted local cache support, and keyring compatibility:

```bash
pip install -e '.[vault,secrets]'
```

Install release and verification tooling:

```bash
pip install -e '.[release]'
```

## Quick Start

Open the current directory:

```bash
cockpit-cli open .
```

Resume the last session:

```bash
cockpit-cli resume
```

List connection aliases:

```bash
cockpit-cli connections
```

List configured datasource profiles:

```bash
cockpit-cli datasources
```

Run the local web admin:

```bash
cockpit-cli admin --open-browser
```

## TUI Commands

Common commands:

```text
/workspace open .
/workspace open @prod:/srv/app
/workspace reopen_last
/session restore
/tab focus db
/layout apply_default
/layout toggle_orientation
/layout grow
/layout shrink
/terminal focus
/terminal restart
/terminal search "error"
/terminal search_next
/terminal search_prev
/terminal export .cockpit/terminal-buffer.txt
/terminal copy
/docker restart
/docker stop
/docker remove
/cron enable
/cron disable
/db run_query "SELECT 1"
/curl send GET https://example.com
```

## Web Admin

The local web admin exposes:

- datasource profile creation and deletion
- datasource execution for quick operator queries and mutations
- Vault profile management, login, lease diagnostics, transit actions, and managed secret references
- plugin install/update/pin/enable/remove
- layout cloning and split edits
- diagnostics for commands, panels, datasources, secrets, plugins, tunnels, and tool availability

It runs locally only and reuses the same application services as the TUI.

## Connection Profiles

Connection aliases live in `config/connections.yaml`. Start from
[connections.example.yaml](/home/damien/Dokumente/cockpit/config/connections.example.yaml).

Example:

```yaml
connections:
  prod:
    target: deploy@example.com
    default_path: /srv/app
    description: Production target
```

Then open through either form:

```bash
cockpit-cli open --connection prod /srv/app
cockpit-cli open @prod:/srv/app/current
```

## Datasource Profiles

Datasource profiles can be managed in the web admin or through
`config/datasources.yaml`. Start from
[datasources.example.yaml](/home/damien/Dokumente/cockpit/config/datasources.example.yaml).

Each profile captures:

- backend
- connection URL
- optional secret reference mappings for `${PLACEHOLDER}` interpolation
- optional driver
- risk level
- local or SSH target
- SSH tunneling for tunnel-safe remote SQL and NoSQL backends
- database name
- capabilities

Example secret-backed datasource snippet:

```yaml
profiles:
  - id: analytics-postgres
    name: Analytics Postgres
    backend: postgres
    connection_url: postgresql+psycopg://${DB_USER}:${DB_PASS}@db.internal:5432/analytics
    target_kind: ssh
    target_ref: deploy@example.com
    secret_refs:
      DB_USER: env:ANALYTICS_DB_USER
      DB_PASS:
        provider: keyring
        service: cockpit
        username: analytics-password

Vault-backed references are also supported directly, for example:

```yaml
profiles:
  - id: app-postgres
    name: App Postgres
    backend: postgres
    connection_url: postgresql://${DB_USER}:${DB_PASS}@db.internal:5432/app
    secret_refs:
      DB_USER: vault+dynamic://ops-vault/database/app#username
      DB_PASS: vault+dynamic://ops-vault/database/app#password
```
```

## Plugin System

Two plugin paths exist:

1. Static config loading from `config/plugins.yaml`
2. Managed installs through the web admin using pip-compatible requirements

Managed plugin installs support:

- package names
- pinned versions
- local paths
- git requirements
- trusted source prefix enforcement
- permission allowlists before runtime activation
- compatibility checks against the running cockpit version
- install-time and runtime integrity hashes

Plugins can contribute:

- panels
- commands
- datasource families
- admin pages

See [plugins.example.yaml](/home/damien/Dokumente/cockpit/config/plugins.example.yaml)
and [notes_plugin.py](/home/damien/Dokumente/cockpit/src/cockpit/plugins/notes_plugin.py).

## Packaging

Release artifacts included in the repo:

- `sdist`
- `wheel`
- Arch/CachyOS `PKGBUILD` in [packaging/arch/PKGBUILD](/home/damien/Dokumente/cockpit/packaging/arch/PKGBUILD)
- tag-driven GitHub release workflow in [.github/workflows/release.yml](/home/damien/Dokumente/cockpit/.github/workflows/release.yml)
- release checksum manifest generation (`SHA256SUMS.txt`)
- CycloneDX SBOM generation for Python and frontend dependencies
- Sigstore keyless bundles for published release assets
- GitHub provenance attestation generation
- PyPI Trusted Publishing from the same canonical package artifacts

## Development

Run tests:

```bash
PYTHONPATH=src python -m unittest discover -s tests -p 'test_*.py' -v
```

Run UI/E2E tests with the dependency environment:

```bash
PYTHONPATH=src:/tmp/cockpit-deps python -m unittest \
  tests.e2e.test_embedded_terminal_widget \
  tests.e2e.test_app_resume_flow -v
```

CI lives in [.github/workflows/ci.yml](/home/damien/Dokumente/cockpit/.github/workflows/ci.yml).
It compiles the code, runs the unittest suite, builds `sdist` plus `wheel`, and runs a live service matrix against PostgreSQL, MySQL, Redis, and MongoDB.
It also exercises a release dry-run path that builds the frontend bundle, assembles Python artifacts, and emits SBOM plus checksum metadata without publishing.
Tagged pushes additionally publish release artifacts through [.github/workflows/release.yml](/home/damien/Dokumente/cockpit/.github/workflows/release.yml).

## Release Verification

Published GitHub releases include:

- `sdist`
- `wheel`
- `SHA256SUMS.txt`
- `release-manifest.json`
- Python and frontend CycloneDX SBOM files
- Sigstore bundle files for release assets
- GitHub build provenance bundle output

Verify checksums:

```bash
sha256sum -c SHA256SUMS.txt
```

Verify a signed artifact:

```bash
python -m pip install sigstore
python -m sigstore verify github cockpit_cli-<version>-py3-none-any.whl \
  --bundle cockpit_cli-<version>-py3-none-any.whl.sigstore.json \
  --repository DamienDrash/cockpit_cli \
  --ref refs/tags/v<version> \
  --trigger push
```

Verify provenance:

```bash
gh attestation verify cockpit_cli-<version>-py3-none-any.whl \
  --repo DamienDrash/cockpit_cli
```

Maintainer release steps are documented in
[docs/releasing.md](/home/damien/Dokumente/cockpit/docs/releasing.md).

## Operator Notes

Terminal selection flow:

- `Ctrl+Space` starts or clears a terminal line selection
- `Shift+Up` and `Shift+Down` expand the active selection
- `Ctrl+Shift+C` copies the selection
- `Ctrl+Alt+C` copies the full terminal buffer
- mouse wheel scrolls through scrollback
- clicking and dragging inside the embedded terminal expands the current line selection

Managed secrets:

- create them in the web admin under `Secrets`
- reference them inside datasource `secret_refs` as `stored:secret-name`
- Vault profiles support `token`, `AppRole`, and `OIDC/JWT` login modes
- Vault-managed entries support `kv` and dynamic secret references
- Vault transit operations are available from the web admin for encrypt/decrypt/sign/verify
- Vault sessions can use encrypted local cache where enabled
- compatibility `env`, `file`, and `keyring` providers remain supported for migration and bootstrap flows

Plugin trust policy:

- `config/plugins.yaml` can define `trusted_sources` and `allowed_permissions`
- plugins requesting permissions outside the configured allowlist stay installed but do not activate at runtime

Tunnel operations:

- remote datasource tunnels show reconnect counts and last-failure diagnostics in the web admin
- dead tunnels can be reconnected directly from the diagnostics page

Contribution and release notes:

- [CONTRIBUTING.md](/home/damien/Dokumente/cockpit/CONTRIBUTING.md)
- [CHANGELOG.md](/home/damien/Dokumente/cockpit/CHANGELOG.md)
- [SECURITY.md](/home/damien/Dokumente/cockpit/SECURITY.md)
- [docs/releasing.md](/home/damien/Dokumente/cockpit/docs/releasing.md)

## Linux Scope

This project is currently Linux-first. The repository includes first-class
packaging for Arch-like systems, including CachyOS.

## License

MIT. See [LICENSE](/home/damien/Dokumente/cockpit/LICENSE).
