openk8s 0.0.1 → 1.0.1

package/README.md

@@ -1,45 +1,196 @@
 # openk8s
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+A terminal UI for Kubernetes.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+**This project is vibe-coded and untested.** No guarantees it works. Built as an exercise to see how far AI-assisted development can go for a k9s-like terminal UI. Use at your own risk.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## What is this?
 
-## Purpose
+openk8s is a keyboard-driven TUI for browsing and managing Kubernetes clusters, inspired by [k9s](https://k9scli.io/). It aims to be a simpler, opinionated alternative — three panes, no mouse dependency (though clickable), and direct access to the most common kubectl operations without leaving the terminal.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `openk8s`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Prerequisites
 
-## What is OIDC Trusted Publishing?
+| Tool | Required | Notes |
+|------|----------|-------|
+| [kubectl](https://kubernetes.io/docs/tasks/tools/) | yes | Must be configured with a valid kubeconfig |
+| [helm](https://helm.sh/) | no | Enables HelmRelease management |
+| [bun](https://bun.sh/) | yes | Required at runtime to execute the app |
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Installation
 
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+### npm (requires bun at runtime)
+
+```bash
+npm install -g openk8s
+openk8s
+```
+
+### bunx (no install needed)
+
+```bash
+bunx openk8s
+```
+
+### From source
+
+```bash
+git clone https://github.com/leon19/openk8s
+cd openk8s
+npm install
+bun run dev
+```
+
+## Quick start
+
+```bash
+openk8s
+```
+
+The app scans your kubeconfig, picks your current context, and loads the cluster's resources. Use `c` to switch contexts, `n` to switch namespaces.
+
+## Layout
+
+```
+┌─────────────┬──────────────────────┬──────────────────┐
+│   Kinds     │     Resources        │    Inspector     │
+│             │                      │                  │
+│   pods     ›│   nginx-7fb96c...   ││   Summary tab    │
+│   services ›│   redis-5d4f8b...   ││   Status: Ready  │
+│   configmaps│   api-6c9b8...      ││   Age: 2h        │
+│   ...       │   ...               ││   ...            │
+│             │                      │                  │
+│ [C] cluster │  / filter            │  [s] [y] [v] [i] │
+│ [N] ns      │                     │                   │
+└─────────────┴──────────────────────┴──────────────────┘
+```
+
+Three resizable panes: resource kinds (left), resources (center), inspector (right, hidden when width < 110). Tab/Shift+Tab cycles focus. Inspector has four tabs: Summary, YAML, Events, Describe.
+
+## Keybindings
+
+### Global
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Cycle pane focus right / left |
+| `c` | Switch cluster context |
+| `n` | Switch namespace |
+| `r` | Refresh current view |
+| `Escape` | Close overlay / exit filter mode |
+| `Ctrl+C` | Quit |
+
+### Navigation
+
+| Key | Action |
+|-----|--------|
+| `Up` / `k` | Move up in current pane |
+| `Down` / `j` | Move down in current pane |
+| `Left` / `h` | Move to previous pane |
+| `Right` | Move to next pane / inspector tab |
+
+### Resource pane
+
+| Key | Action |
+|-----|--------|
+| `/` | Enter filter mode (type to filter resources) |
+| `Space` | Toggle multi-select on current resource |
+| `l` | View streaming logs |
+| `x` | Open interactive shell (`kubectl exec`) |
+| `e` | Edit resource (`kubectl edit` / `helm upgrade --reuse-values`) |
+| `d` | Delete resource (supports batch delete) |
+| `f` | Port-forward overlay |
+| `Shift+S` | Scale replicas |
+| `Shift+R` | Rollout restart |
+| `b` | Helm rollback (HelmReleases only) |
+| `Shift+U` | Helm upgrade (HelmReleases only, interactive) |
+
+### Inspector pane
+
+| Key | Action |
+|-----|--------|
+| `s` | Summary tab |
+| `y` | YAML tab (press again to copy YAML) |
+| `v` | Events tab |
+| `i` | Describe tab |
+
+### Logs overlay
+
+| Key | Action |
+|-----|--------|
+| `Up` / `Down` / `k` / `j` | Scroll by 3 lines |
+| `c` | Pick container (multi-container pods) |
+| `p` | Toggle previous logs |
+| `t` | Set tail count |
+| `s` | Set since duration (e.g. `1h`, `30m`) |
+| `/` | Search within logs |
+| `n` / `Shift+N` | Next / previous search match |
+| `Escape` | Exit search → exit input → close overlay |
+| `Enter` | Confirm input / search |
+
+### Port-forward overlay
+
+| Key | Action |
+|-----|--------|
+| `Up` / `Down` / `k` / `j` | Navigate ports |
+| `Enter` | Start forwarding on selected port |
+| `x` | Stop active forward on selected port |
+| `Escape` | Close overlay |
+
+### Scale dialog
+
+| Key | Action |
+|-----|--------|
+| type | Enter replica count |
+| `Enter` | Apply scale |
+| `Escape` | Cancel |
+
+### Delete confirm overlay
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Confirm deletion |
+| `Escape` | Cancel |
+
+## Features
+
+- **Context & namespace switching** — browse any cluster in your kubeconfig, any namespace
+- **Resource browsing** — auto-discovers API resource kinds and lists resources with status, age, and summary; curates a sensible default ordering
+- **Log streaming** — `kubectl logs --follow` with search, container picker, tail count, since duration, and previous logs toggle; Deployments/StatefulSets use `--all-pods`
+- **Shell** — drop into a container via `kubectl exec -it sh` (renderer suspends, resumes on exit)
+- **Edit** — `kubectl edit` for resources, temp-file + `helm upgrade --reuse-values` for HelmReleases (opens `$EDITOR`)
+- **Port-forward** — declare ports, start/stop forwards inline with live status
+- **Scale** — set replica count for Deployments, StatefulSets, ReplicaSets
+- **Rollout restart** — one-key restart for Deployments, StatefulSets, DaemonSets
+- **Delete** — single or batch (via multi-select with `Space`), uses `kubectl delete` or `helm uninstall`
+- **Secret reveal** — click `[reveal]` inline to decode secret values and `[copy]` to clipboard
+- **YAML copy** — view full YAML in inspector, press `y` again to copy
+- **Metrics** — pod and node CPU/memory usage when metrics-server is installed
+- **Helm releases** — list, rollback, and upgrade Helm releases (injected as a resource kind when helm is available)
+- **Multi-select** — select multiple resources for batch operations (delete)
+- **Keyboard-first** — all actions accessible via keyboard; mouse also supported
+- **Persistent state** — last active context and namespace saved to `~/.config/openk8s/state.json`
+
+## Clipboard
+
+Copy actions (YAML, secret values) use:
+- **Linux (Wayland):** `wl-copy`
+- **Linux (X11):** `xclip -selection clipboard`
+- **macOS:** `pbcopy`
+
+A toast notification is shown on unsupported platforms.
+
+## Polling
+
+The app auto-refreshes on three intervals:
+
+| What | Interval |
+|------|----------|
+| Cluster state | 30s |
+| Resource list & detail | 5s |
+| Metrics | 15s |
+
+Press `r` to force a manual refresh at any time.
+
+## License
+
+MIT

package/bin/openk8s.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.tsx";

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "openk8s",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for openk8s",
+  "version": "1.0.1",
+  "description": "A terminal UI for Kubernetes",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "openk8s": "./bin/openk8s.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leon19/openk8s.git"
+  },
+  "author": {
+    "name": "Lorens León",
+    "email": "lorensleon@gmail.com"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "kubernetes",
+    "tui",
+    "k9s",
+    "terminal",
+    "kubectl"
+  ],
+  "scripts": {
+    "dev": "bun run --watch src/index.tsx",
+    "prepare": "husky || exit 0"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ]
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.3",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.2.12",
+    "@opentui/react": "^0.2.12",
+    "react": "^19.2.6"
+  }
 }