The Problem

Kubernetes clusters are powerful but their CLI‑centric workflow makes day‑to‑day navigation, resource inspection and quick actions cumbersome for developers and operators who prefer a graphical UI.

What This Does

freelens ships a desktop Electron application that bundles a React/Tailwind front‑end with a Node‑back‑end. The main UI lives under freelens/src/renderer/ (e.g., index.ts) and the Electron main process starts from freelens/src/main/index.ts. Core domain logic – catalog entities, kube‑object stores, and API wrappers – lives in the monorepo packages/core/ and is reused by feature packages such as packages/cluster-sidebar and packages/business-features/keyboard-shortcuts. The build pipeline is driven by pnpm (see pnpm-lock.yaml) and Webpack configs in freelens/webpack/ and each feature package.

How It Is Wired

  • Entry point – Electron launches freelens/src/main/index.ts. This registers injectables (register-injectables.ts) and calls the start helper in freelens/integration/helpers/utils.ts (line 118).
  • Bootstrap flow – start reaches seven internal functions, the most used being getId (called from 20 places) and getName (10 places). For example, podSelector → getName occurs six times, and index → getId five times.
  • Core data path – The catalog entity model in packages/core/src/common/catalog/catalog-entity.ts defines parseId, getId, getName, and getBadge. This file is called from eight other files and underpins most UI listings.
  • Kubernetes API layer – packages/core/src/common/k8s-api/kube-object.store.ts implements the store that queries the cluster, exposing query, getAllByNs, and getTotalCount. It makes outbound network calls (four internal edges) via the api object (e.g., attemptStart → remove where remove triggers this.api.delete).
  • Extension discovery – packages/core/src/extensions/extension-discovery/extension-discovery.ts (init function at line 141) loads bundled extensions from the local node_modules folder, registering them with the DI container.
  • Feature injection – Feature packages register their services via register-injectables.ts (e.g., packages/cluster-sidebar/src/register-injectables.ts). The DI system resolves tokens like keyboard-shortcut-injection-token used by the shortcut listener in packages/business-features/keyboard-shortcuts/src/keyboard-shortcut-listener.tsx.
  • Outbound effects – Only five functions touch the outside world: one file read/write and four network calls. The shortest external path is start → attemptStart → remove (network api.delete). No direct file system writes are observed beyond the initial setup scripts.
  • Hot spots – catalog-entity.ts (12 functions, 25 types) and kube-object.store.ts (34 functions) have the highest internal connectivity and therefore the widest blast radius for changes.
  • Unmapped wiring – The call graph does not resolve framework callbacks (React event handlers) or the Webpack bundling step, so those pathways are not reflected in the static edge count.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/freelens.git
cd freelens

# Install deps with pnpm (lockfile present)
pnpm install

# Build the Electron app (webpack config)
pnpm run build   # defined in package.json scripts

# Run the development version
pnpm start       # launches Electron using src/main/index.ts

Configuration files such as freelens/integration/tsconfig.json and freelens/webpack/main.ts are already wired; no additional environment variables are required for a local cluster connection, but the app expects a kubeconfig file at the default location (~/.kube/config) which is read by the API layer (kube-object.store.ts).

Real‑World Use

A developer working on a microservice can open Freelens, select a cluster from the sidebar (cluster-sidebar), and instantly view pod logs, exec into containers, or apply Helm charts via the UI. Keyboard shortcuts registered in packages/business-features/keyboard-shortcuts/src/keyboard-shortcut-listener.tsx let power users trigger common actions (e.g., Ctrl+Shift+L to open logs) without leaving the desktop.

Code Health & Issues

  • Critical – write-all permission in .github/workflows/release.yaml.
  • Critical – Exposed GH_TOKEN in .github/workflows/npm-audit.yaml.
  • High – Unpinned third‑party actions (e.g., helm/kind-action@v1).
  • High – continue-on-error on a correctness step in .github/workflows/integration-tests.yaml.
  • Medium – persist-credentials: false missing on checkout step in the same workflow.

Additional observations: tests are present (539 files) and CI runs via GitHub Actions; a license file exists; a lockfile (pnpm-lock.yaml) is committed. No Dockerfile is provided, and the repo contains committed secrets flagged by the analysis.

The Bottom Line

Freelens delivers a well‑structured Electron UI for Kubernetes, with clear separation between core catalog logic and feature extensions. The codebase is heavily typed, heavily tested, but the CI workflow contains several serious security misconfigurations that must be addressed before production deployment. It is suitable for teams that need a desktop Kubernetes UI and are prepared to remediate the workflow issues.