@ols-cli/lightspeed 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 (2026-04-10)
+
+### Initial Release
+
+- Forked from [pi-mono](https://github.com/badlogic/pi-mono) (MIT, by Mario Zechner)
+- Rebranded as `ols` (OpenShift Lightspeed CLI)
+- **OLS Client** (`packages/ols-client/`): Full REST API client for OpenShift Lightspeed Service
+  - Query, streaming query, conversations, feedback, health check
+  - Kubeconfig token extraction for K8S auth
+  - Config from `~/.ols/config.json` or `OLS_SERVICE_URL` env var
+- **OLS Tools** (`packages/ols-cli/src/core/tools/ols/`):
+  - `ols_query` — Natural language queries with RAG
+  - `ols_stream` — Streaming responses
+  - `ols_health` — Service health check
+  - `ols_conversations` — List past conversations
+  - `ols_feedback` — Submit feedback
+- **OpenShift Tools** (`packages/ols-cli/src/core/tools/openshift-tools.ts`):
+  - `oc_get` — Get resources
+  - `oc_describe` — Describe resources
+  - `oc_logs` — Fetch pod logs
+  - `oc_exec` — Execute commands in pods
+  - `cluster_status` — Cluster health overview
+- **Skills**: troubleshoot-pod, deploy-app, security-audit, cluster-health
+- **oc plugin**: `oc lightspeed` support via `oc-lightspeed` wrapper
+- **Claude Code plugin**: `.claude-plugin/plugin.json`
+- **OpenClaw skill**: `SKILL.md` (AgentSkills format)
+- **Install script**: `install.sh` for quick setup

package/README.md

@@ -0,0 +1,121 @@
+# Lightspeed CLI
+
+AI-powered OpenShift assistant from your terminal. Built on [pi-mono](https://github.com/badlogic/pi-mono).
+
+Connects to [OpenShift Lightspeed Service (OLS)](https://github.com/openshift/lightspeed-service) and gives you an interactive AI chat in your terminal — powered by your cluster's OLS instance.
+
+## Features
+
+- 🤖 Interactive AI assistant for OpenShift (TUI)
+- 🔄 Streaming responses via SSE
+- 💬 Session management with branching
+- 🔐 K8S auth from kubeconfig (oc login)
+- 🛠️ OpenShift-aware tools (oc-get, oc-describe, oc-logs)
+- 📊 Cluster status at a glance
+- 🔌 `oc` plugin compatible (`oc lightspeed`)
+
+## Install
+
+```bash
+npm install -g @ols-cli/lightspeed
+```
+
+## Quick Start
+
+```bash
+# Configure OLS endpoint
+ols config set serviceUrl https://lightspeed-service.openshift-operators.svc:8443
+
+# Interactive mode
+ols
+
+# One-shot query
+ols "how do I scale my deployment?"
+
+# Health check
+ols health
+
+# List conversations
+ols conversations
+```
+
+## Usage
+
+```bash
+# Interactive mode
+ols
+
+# One-shot query
+ols "how do I scale my deployment?"
+
+# Streaming mode
+ols --stream "check my pod health"
+
+# As oc plugin
+oc lightspeed "what's wrong with my cluster?"
+```
+
+## Configuration
+
+```bash
+# Configure OLS endpoint
+ols config set serviceUrl https://lightspeed-service.openshift-operators.svc:8443
+
+# Or via environment
+export OLS_SERVICE_URL=https://lightspeed-service.example.com:8443
+
+# Auth comes from kubeconfig — just oc login
+oc login https://api.my-cluster:6443
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ols_query` | Query OLS for OpenShift knowledge (RAG-powered) |
+| `ols_stream` | Streaming query to OLS |
+| `ols_health` | Check OLS service health |
+| `ols_conversations` | List past conversations |
+| `ols_feedback` | Submit response feedback |
+| `oc_get` | Get OpenShift resources |
+| `oc_describe` | Describe resources in detail |
+| `oc_logs` | Fetch pod logs |
+| `oc_exec` | Execute commands in pods |
+| `cluster_status` | Quick cluster health overview |
+
+## Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| `troubleshoot-pod` | Pod is CrashLooping, failing, or not ready |
+| `deploy-app` | Deploying a new application |
+| `security-audit` | Security posture review |
+| `cluster-health` | Overall cluster health check |
+
+## Architecture
+
+```
+lightspeed-cli/
+├── packages/
+│   ├── ai/            — Unified LLM API (from pi-mono)
+│   ├── agent/         — Agent runtime with tool calling (from pi-mono)
+│   ├── tui/           — Terminal UI library (from pi-mono)
+│   ├── ols-client/    — OLS REST API client (new)
+│   └── ols-cli/       — CLI entry point + TUI (from pi-mono coding-agent)
+│       └── src/core/tools/ols/  — OLS + OpenShift tools
+├── skills/            — OpenShift-specific agent skills
+├── scripts/oc-lightspeed — oc plugin wrapper
+├── .claude-plugin/    — Claude Code compatible
+├── SKILL.md           — OpenClaw / AgentSkills compatible
+└── README.md
+```
+
+## Requirements
+
+- Node.js >= 20.6.0
+- OpenShift cluster with Lightspeed Service deployed
+- `oc` CLI (for auth via kubeconfig)
+
+## License
+
+Apache-2.0 (original pi-mono code is MIT)

package/bin/ols.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * ols — OpenShift Lightspeed CLI
+ *
+ * Usage:
+ *   ols                          Interactive mode
+ *   ols "how do I scale?"        One-shot query
+ *   ols health                   Check OLS health
+ *   ols conversations            List conversations
+ *   ols config set <key> <val>   Set config
+ *   ols config show              Show config
+ */
+import { OLSClient, loadOLSConfig, saveOLSConfig } from "@ols-cli/client";
+
+// ─── Colors (zero deps) ───
+const cyan = "\x1b[36m";
+const green = "\x1b[32m";
+const red = "\x1b[31m";
+const yellow = "\x1b[33m";
+const bold = "\x1b[1m";
+const reset = "\x1b[0m";
+const dim = "\x1b[2m";
+
+// ─── Config ───
+function configCmd(args: string[]): void {
+  const cmd = args[0];
+  if (!cmd || cmd === "show") {
+    const cfg = loadOLSConfig();
+    console.log(JSON.stringify(cfg, null, 2));
+    return;
+  }
+  if (cmd === "set" && args[1] && args[2] !== undefined) {
+    const cfg = loadOLSConfig();
+    const val = args[2] === "true" ? true : args[2] === "false" ? false : args[2];
+    (cfg as any)[args[1]] = val;
+    saveOLSConfig(cfg);
+    console.log(`${green}✓${reset} Set ${args[1]} = ${args[2]}`);
+    return;
+  }
+  if (cmd === "init") {
+    console.log(`${cyan}OpenShift Lightspeed CLI Configuration${reset}\n`);
+    console.log("  ols config set serviceUrl https://lightspeed-service.example.com:8443");
+    console.log("  ols config set namespace openshift-operators\n");
+    console.log("Auth comes from kubeconfig — just run: oc login");
+    return;
+  }
+  console.log("Usage: ols config [show|set|init]");
+}
+
+// ─── Health ───
+async function healthCmd(): Promise<void> {
+  try {
+    const client = new OLSClient(loadOLSConfig());
+    const h = await client.health();
+    console.log(`${green}✓${reset} OLS Status: ${h.status}`);
+    if (h.services) {
+      for (const [name, status] of Object.entries(h.services)) {
+        const icon = status === "ok" || status === "ready" ? green : yellow;
+        console.log(`  ${icon}●${reset} ${name}: ${status}`);
+      }
+    }
+  } catch (e: any) {
+    console.error(`${red}✗${reset} ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// ─── Conversations ───
+async function conversationsCmd(): Promise<void> {
+  try {
+    const client = new OLSClient(loadOLSConfig());
+    const convos = await client.listConversations();
+    if (convos.length === 0) {
+      console.log(`${dim}No conversations found.${reset}`);
+      return;
+    }
+    console.log(`${bold}Recent Conversations${reset}\n`);
+    for (const c of convos.slice(0, 20)) {
+      const date = new Date(c.created_at).toLocaleDateString();
+      console.log(`  ${cyan}${c.id}${reset}  ${dim}${date}${reset}  ${c.first_query || "(no query)"}  [${c.message_count} msgs]`);
+    }
+  } catch (e: any) {
+    console.error(`${red}✗${reset} ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// ─── One-shot query ───
+async function queryCmd(question: string): Promise<void> {
+  try {
+    const client = new OLSClient(loadOLSConfig());
+    const resp = await client.query({ query: question });
+    console.log(`\n${resp.response}\n`);
+    if (resp.referenced_documents?.length) {
+      console.log(`${dim}References:${reset}`);
+      for (const doc of resp.referenced_documents) {
+        console.log(`  ${cyan}→${reset} ${doc.title} ${dim}(${doc.url})${reset}`);
+      }
+      console.log();
+    }
+    if (resp.conversation_id) {
+      console.log(`${dim}Conversation: ${resp.conversation_id}${reset}`);
+    }
+  } catch (e: any) {
+    console.error(`${red}✗${reset} ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// ─── Interactive REPL ───
+async function interactiveMode(): Promise<void> {
+  const readline = await import("readline");
+
+  console.log(`\n${bold}${cyan}OpenShift Lightspeed CLI${reset} v0.1.0`);
+  console.log(`${dim}Type your question, or 'quit' to exit.${reset}\n`);
+
+  let conversationId: string | undefined;
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: `${green}ols>${reset} `,
+  });
+
+  rl.prompt();
+
+  rl.on("line", async (line) => {
+    const input = line.trim();
+    if (!input) { rl.prompt(); return; }
+    if (input === "quit" || input === "exit" || input === "q") {
+      console.log(`${dim}Bye!${reset}`);
+      process.exit(0);
+    }
+    if (input === "health") { await healthCmd(); rl.prompt(); return; }
+    if (input === "conversations") { await conversationsCmd(); rl.prompt(); return; }
+
+    try {
+      const client = new OLSClient(loadOLSConfig());
+      const resp = await client.query({ query: input, conversation_id: conversationId });
+      conversationId = resp.conversation_id;
+      console.log(`\n${resp.response}\n`);
+      if (resp.referenced_documents?.length) {
+        console.log(`${dim}References:${reset}`);
+        for (const doc of resp.referenced_documents) {
+          console.log(`  ${cyan}→${reset} ${doc.title}`);
+        }
+        console.log();
+      }
+    } catch (e: any) {
+      console.error(`${red}✗${reset} ${e.message}`);
+    }
+    rl.prompt();
+  });
+}
+
+// ─── Main ───
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    return interactiveMode();
+  }
+
+  const cmd = args[0];
+
+  if (cmd === "config") return configCmd(args.slice(1));
+  if (cmd === "health") return await healthCmd();
+  if (cmd === "conversations" || cmd === "convos") return await conversationsCmd();
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    console.log(`${bold}Usage:${reset}
+  ols                          Interactive mode
+  ols "your question"          One-shot query
+  ols health                   Check OLS service health
+  ols conversations            List past conversations
+  ols config show              Show configuration
+  ols config set <key> <val>   Set config value
+  ols config init              Setup help
+  ols help                     This help
+`);
+    return;
+  }
+
+  // Treat as query
+  return await queryCmd(args.join(" "));
+}
+
+main().catch((e) => {
+  console.error(`${red}Fatal:${reset} ${e.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ols-cli/lightspeed",
+  "version": "0.1.0",
+  "description": "OpenShift Lightspeed CLI — AI-powered assistant for OpenShift from your terminal",
+  "type": "module",
+  "bin": {
+    "ols": "./bin/ols.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "echo \"no tests yet\""
+  },
+  "keywords": [
+    "openshift", "lightspeed", "ols", "kubernetes", "cli",
+    "ai-agent", "assistant", "terminal", "devops"
+  ],
+  "author": "Chin (kcns008)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kcns008/lightspeed-cli.git"
+  },
+  "homepage": "https://github.com/kcns008/lightspeed-cli#readme",
+  "bugs": {
+    "url": "https://github.com/kcns008/lightspeed-cli/issues"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ols-cli/client": "^0.1.0"
+  }
+}

package/skills/cluster-health.md

@@ -0,0 +1,45 @@
+---
+name: cluster-health
+description: >
+  Check the overall health of an OpenShift cluster. Use when the user asks about
+  cluster status, node health, capacity, or wants a quick health overview.
+metadata:
+  author: kcns008
+  version: "0.1.0"
+---
+
+# Cluster Health Check
+
+## Steps
+
+1. **Node status**
+   ```
+   cluster_status: (no args for full cluster)
+   ```
+
+2. **Check for warnings**
+   ```bash
+   oc get events -A --field-selector type=Warning --sort-by='.lastTimestamp'
+   ```
+
+3. **Check cluster operators** (OpenShift only)
+   ```bash
+   oc get clusteroperators
+   oc get co -o jsonpath='{range .items[?(@.status.conditions[?(@.type=="Available")].status!="True")]}{.metadata.name}{"\n"}{end}'
+   ```
+
+4. **Check alerts** (if monitoring stack available)
+   ```bash
+   oc get alerts -n openshift-monitoring
+   ```
+
+5. **Resource capacity**
+   ```bash
+   oc top nodes
+   oc get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
+   ```
+
+6. **Summarize health**
+   - 🟢 Healthy — all nodes ready, no critical alerts
+   - 🟡 Warning — degraded operators or resource pressure
+   - 🔴 Critical — nodes down, pods failing, alerts firing

package/skills/deploy-app.md

@@ -0,0 +1,58 @@
+---
+name: deploy-app
+description: >
+  Guide deploying an application to OpenShift. Use when the user wants to deploy
+  a new app, create a deployment, set up services and routes. Covers S2I, Docker,
+  Helm, and raw YAML approaches.
+metadata:
+  author: kcns008
+  version: "0.1.0"
+---
+
+# Deploy Application
+
+## Steps
+
+1. **Ask about the app**
+   - What's the source? (Git repo, container image, local code)
+   - What's the runtime? (Java, Node.js, Python, Go, etc.)
+   - Which namespace/project?
+
+2. **Choose deployment method**
+
+   | Method | Best For |
+   |--------|----------|
+   | `oc new-app` | Quick deploy from source or image |
+   | `oc new-build` + deploy | Custom build pipeline |
+   | Helm chart | Complex apps with config |
+   | Raw YAML/Kustomize | Full control |
+
+3. **Deploy**
+   ```bash
+   # From Git (S2I)
+   oc new-app https://github.com/user/repo.git --name=myapp -n myns
+
+   # From image
+   oc new-app myimage:tag --name=myapp -n myns
+
+   # Expose
+   oc expose svc/myapp
+   ```
+
+4. **Verify**
+   ```
+   oc_get: resource=pods -n <namespace>
+   oc_get: resource=svc -n <namespace>
+   oc_get: resource=route -n <namespace>
+   ```
+
+5. **Set up health checks** (if not auto-detected)
+   ```bash
+   oc set probe dc/myapp --readiness --get-url=http://:8080/health
+   oc set probe dc/myapp --liveness --get-url=http://:8080/health
+   ```
+
+6. **Configure resources**
+   ```bash
+   oc set resources dc/myapp --requests=cpu=100m,memory=256Mi --limits=cpu=500m,memory=512Mi
+   ```

package/skills/security-audit.md

@@ -0,0 +1,48 @@
+---
+name: security-audit
+description: >
+  Run a security audit on an OpenShift namespace or cluster. Use when the user
+  asks about security posture, RBAC, SCCs, network policies, or compliance.
+metadata:
+  author: kcns008
+  version: "0.1.0"
+---
+
+# Security Audit
+
+## Steps
+
+1. **Check RBAC**
+   ```bash
+   oc get clusterrolebindings -o wide
+   oc get rolebindings -n <namespace>
+   oc auth can-i --list --as=system:serviceaccount:<ns>:<sa>
+   ```
+
+2. **Check Security Context Constraints**
+   ```bash
+   oc get scc
+   oc describe scc restricted
+   ```
+
+3. **Check pod security**
+   ```bash
+   oc get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.securityContext}{"\n"}{end}'
+   ```
+
+4. **Check network policies**
+   ```bash
+   oc get networkpolicies -n <namespace>
+   ```
+
+5. **Check image vulnerabilities** (if Security Operator installed)
+   ```bash
+   oc get vulnerabilities -n <namespace>
+   oc get imagevulnerabilities -n <namespace>
+   ```
+
+6. **Summarize findings**
+   - Overly permissive RBAC
+   - Pods running as root
+   - Missing network policies
+   - Known vulnerabilities

package/skills/troubleshoot-pod.md

@@ -0,0 +1,50 @@
+---
+name: troubleshoot-pod
+description: >
+  Troubleshoot a problematic pod in OpenShift. Use when a pod is CrashLooping,
+  not ready, failing health checks, or showing errors. Walks through events,
+  logs, describe, and common failure patterns.
+metadata:
+  author: kcns008
+  version: "0.1.0"
+---
+
+# Troubleshoot Pod
+
+## Steps
+
+1. **Get pod status**
+   ```
+   oc_get: resource=pods -n <namespace>
+   ```
+   Identify the problematic pod. Note its status (CrashLoopBackOff, ImagePullBackOff, Pending, etc.)
+
+2. **Describe the pod**
+   ```
+   oc_describe: resource=pod/<pod-name> -n <namespace>
+   ```
+   Look for: Events (bottom), State, Last State, Reason, Message
+
+3. **Check events**
+   ```
+   bash: oc get events -n <namespace> --sort-by='.lastTimestamp' --field-selector involvedObject.name=<pod-name>
+   ```
+
+4. **Fetch logs**
+   ```
+   oc_logs: pod=<pod-name> -n <namespace> --tail=100
+   ```
+   If crashed previously, add `--previous` flag
+
+5. **Diagnose based on patterns**
+
+   | Status | Common Cause | Fix |
+   |--------|-------------|-----|
+   | CrashLoopBackOff | App crash on startup | Check logs for exception/exit code |
+   | ImagePullBackOff | Wrong image/tag or no pull secret | Verify image name, check secrets |
+   | Pending | No resources (CPU/memory) or PVC issues | Check node capacity, PVC status |
+   | OOMKilled | Memory limit too low | Increase memory limit |
+   | Error | Config/secrets missing | Check env vars, mounted configmaps |
+   | Completed | Job/one-shot finished | Normal for Jobs |
+
+6. **Summarize findings and suggest fix**