@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,106 @@
 {
   "name": "@kabmo-labs/kabmo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Web console and diagnostic workbench for AI coding agents — Elysia + Preact on Bun.",
+  "license": "UNLICENSED",
+  "author": "Wijanarko Putra Rajeb <wijanarko.rajeb@gmail.com>",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kabmo": "./src/cli/kabmo.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kabmo-labs/kabmo.git"
+  },
+  "homepage": "https://github.com/kabmo-labs/kabmo#readme",
+  "bugs": {
+    "url": "https://github.com/kabmo-labs/kabmo/issues"
+  },
+  "keywords": [
+    "kabmo",
+    "coding-agent",
+    "agent",
+    "console",
+    "elysia",
+    "preact",
+    "bun"
+  ],
+  "files": [
+    "src",
+    "extensions",
+    "index.html",
+    "bunfig.toml",
+    "public",
+    "tsconfig.json",
+    "marketplace",
+    "dist/client"
+  ],
+  "scripts": {
+    "dev": "bun run --hot src/server/index.ts --kabmo-server",
+    "dev:lan": "HOST=0.0.0.0 bun run --hot src/server/index.ts --kabmo-server",
+    "build": "bun run scripts/build-client.ts",
+    "omp:schema": "bun run scripts/omp-schema.mjs",
+    "omp:schema:check": "bun run scripts/omp-schema.mjs --check",
+    "start": "NODE_ENV=production bun run src/server/index.ts --kabmo-server",
+    "typecheck": "tsc",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit",
+    "test": "bun test",
+    "test:e2e": "playwright test --config tests/e2e/playwright.config.ts",
+    "readme:media": "bun run scripts/readme-media.ts",
+    "typecheck:e2e": "tsc --noEmit -p tests/e2e",
+    "publish:plugins": "bash .github/scripts/publish-plugin-packages.sh packages/kabmo-sdk packages/kabmo-ui"
+  },
+  "dependencies": {
+    "@fontsource/fira-code": "^5.3.0",
+    "@kabmo-labs/kabmo-sdk": "0.0.1",
+    "@kabmo-labs/kabmo-ui": "0.0.1",
+    "@shikijs/langs": "^4.4.3",
+    "@shikijs/themes": "^4.4.3",
+    "@tailwindcss/postcss": "^4.1.14",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-webgl": "^0.19.0",
+    "@xterm/xterm": "^6.0.0",
+    "dompurify": "^3.4.15",
+    "elysia": "^1.4.30",
+    "katex": "^0.18.7",
+    "lucide-preact": "^1.47.0",
+    "mammoth": "^1.13.0",
+    "marked": "^18.0.11",
+    "marked-linkify-it": "^4.0.2",
+    "mermaid": "^12.0.0",
+    "postcss": "^8.5.16",
+    "preact": "^10.29.8",
+    "read-excel-file": "^9.3.12",
+    "remend": "^1.3.1",
+    "ripgrep": "^0.3.1",
+    "shiki": "^4.4.3",
+    "tailwindcss": "^4.1.14",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.0",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.10",
+    "@semantic-release/npm": "^13.2.0",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^22.14.0",
+    "bun-types": "^1.4.2",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "happy-dom": "^20.14.5",
+    "semantic-release": "^25.0.9",
+    "typescript": "~5.8.2"
+  },
+  "workspaces": [
+    "packages/*"
+  ]
+}

package/public/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="512" height="512" role="img" aria-label="Kabmo">
+  <title>Kabmo</title>
+  <!-- Full-canvas tile, the geometry the previous icon used: the launcher, the
+       tab and the dock each apply their own mask, and an inset tile would leave
+       a margin inside the mask instead of behind it. -->
+  <rect width="64" height="64" rx="14" fill="#0B5D3B"/>
+  <g fill="none" stroke-width="7" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M20 15v34" stroke="#F7F4EA"/>
+    <path d="M20 32 42 15" stroke="#F26522"/>
+    <path d="M20 32 42 49" stroke="#F7F4EA"/>
+  </g>
+</svg>

package/public/kabmo-wordmark.svg

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Kabmo wordmark — the app icon's K lockup with the word beside it.
+     The word is Inter ExtraBold (the face index.html loads), outlines at a
+     100-unit cap height; the plate is the icon's own 64-unit tile scaled to
+     1.5625 x cap so the K keeps its proportions. Tracking -0.025em, the a
+     tucked 0.28em into the plate, the b->m gap widened 0.02em — the same
+     values the app's BrandWordmark uses, measured there. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -128.12 486.38 156.25" width="486.38" height="156.25" role="img" aria-label="Kabmo">
+  <title>Kabmo</title>
+  <defs>
+    <linearGradient id="kabmo-ab" gradientUnits="userSpaceOnUse" x1="117.76" y1="0" x2="279.42" y2="0">
+      <stop offset="0" stop-color="#f59e0b"/>
+      <stop offset="1" stop-color="#ea580c"/>
+    </linearGradient>
+    <style>
+      /* One ink for every background. A README embeds this as an image, and a
+         prefers-color-scheme query inside such an image follows the CONTAINER
+         only in Chromium — WebKit resolves it from the OS, so a GitHub-dark
+         page on a light OS rendered near-black on near-black. */
+      .kabmo-mo { fill: #7e7a72; }
+    </style>
+  </defs>
+  <rect width="156.25" height="156.25" y="-128.12" rx="34.18" fill="#0b5d3b"/>
+  <g fill="none" stroke-width="17.09" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M48.83 -91.5V-8.5" stroke="#f7f4ea"/>
+    <path d="M48.83 -50 102.54 -91.5" stroke="#f26522"/>
+    <path d="M48.83 -50 102.54 -8.5" stroke="#f7f4ea"/>
+  </g>
+  <path fill="url(#kabmo-ab)" d="M146.49 1.34Q139.31 1.34 133.7 -1.11Q128.1 -3.56 124.95 -8.49Q121.79 -13.42 121.79 -20.81Q121.79 -27.05 123.97 -31.34Q126.15 -35.64 130.05 -38.32Q133.94 -41.01 138.97 -42.42Q144.01 -43.83 149.71 -44.3Q156.09 -44.83 159.98 -45.47Q163.87 -46.11 165.68 -47.38Q167.5 -48.66 167.5 -50.94L167.5 -51.21Q167.5 -53.83 166.29 -55.64Q165.08 -57.45 162.8 -58.39Q160.52 -59.33 157.29 -59.33Q154.07 -59.33 151.56 -58.39Q149.04 -57.45 147.43 -55.7Q145.82 -53.96 145.15 -51.61L123.94 -54.36Q125.42 -60.81 129.74 -65.67Q134.07 -70.54 141.09 -73.26Q148.1 -75.97 157.5 -75.97Q164.48 -75.97 170.55 -74.33Q176.62 -72.68 181.19 -69.5Q185.75 -66.31 188.3 -61.64Q190.85 -56.98 190.85 -50.94L190.85 0L168.84 0L168.84 -10.54L168.23 -10.54Q166.22 -6.64 163.1 -4.03Q159.98 -1.41 155.85 -0.03Q151.72 1.34 146.49 1.34ZM153.6 -14.16Q157.56 -14.16 160.75 -15.77Q163.94 -17.38 165.82 -20.2Q167.7 -23.02 167.7 -26.71L167.7 -33.89Q166.69 -33.36 165.18 -32.89Q163.67 -32.42 161.86 -32.05Q160.05 -31.68 158.23 -31.38Q156.42 -31.07 154.74 -30.81Q151.32 -30.34 148.91 -29.19Q146.49 -28.05 145.21 -26.24Q143.94 -24.43 143.94 -21.88Q143.94 -19.4 145.21 -17.68Q146.49 -15.97 148.64 -15.07Q150.78 -14.16 153.6 -14.16ZM247.95 1.07Q242.25 1.07 238.05 -0.84Q233.86 -2.75 231.11 -5.77Q228.35 -8.79 226.88 -12.15L226.07 -12.15L226.07 0L202.92 0L202.92 -100L226.34 -100L226.34 -62.15L226.88 -62.15Q228.29 -65.57 231.01 -68.72Q233.72 -71.88 237.92 -73.93Q242.11 -75.97 248.09 -75.97Q256.01 -75.97 262.82 -71.85Q269.63 -67.72 273.82 -59.16Q278.02 -50.6 278.02 -37.45Q278.02 -24.7 273.99 -16.14Q269.97 -7.58 263.12 -3.26Q256.27 1.07 247.95 1.07ZM239.97 -17.18Q244.46 -17.18 247.58 -19.7Q250.7 -22.21 252.31 -26.81Q253.93 -31.41 253.93 -37.45Q253.93 -43.56 252.31 -48.09Q250.7 -52.62 247.62 -55.13Q244.53 -57.65 239.97 -57.65Q235.47 -57.65 232.31 -55.2Q229.16 -52.75 227.48 -48.22Q225.8 -43.69 225.8 -37.45Q225.8 -31.34 227.48 -26.78Q229.16 -22.21 232.35 -19.7Q235.54 -17.18 239.97 -17.18Z"/>
+  <path class="kabmo-mo" fill="#7e7a72" d="M289.88 0L289.88 -75.03L311.43 -75.03L312.77 -55.57L311.16 -55.57Q312.9 -62.89 316.36 -67.38Q319.82 -71.88 324.41 -73.96Q329.01 -76.04 334.11 -76.04Q342.16 -76.04 347.1 -70.87Q352.03 -65.7 354.71 -53.96L352.1 -53.96Q353.91 -61.81 357.8 -66.71Q361.69 -71.61 366.93 -73.83Q372.16 -76.04 377.8 -76.04Q384.85 -76.04 390.25 -72.99Q395.65 -69.93 398.74 -64.26Q401.83 -58.59 401.83 -50.6L401.83 0L378.47 0L378.47 -45.3Q378.47 -51.01 375.49 -53.96Q372.5 -56.91 367.87 -56.91Q364.58 -56.91 362.13 -55.44Q359.68 -53.96 358.41 -51.31Q357.13 -48.66 357.13 -45.03L357.13 0L334.65 0L334.65 -45.64Q334.65 -50.81 331.76 -53.86Q328.88 -56.91 324.18 -56.91Q320.96 -56.91 318.51 -55.44Q316.06 -53.96 314.68 -51.24Q313.31 -48.52 313.31 -44.56L313.31 0ZM448.73 1.41Q436.98 1.41 428.53 -3.46Q420.07 -8.32 415.54 -17.01Q411.01 -25.7 411.01 -37.25Q411.01 -48.86 415.54 -57.55Q420.07 -66.24 428.53 -71.11Q436.98 -75.97 448.73 -75.97Q460.47 -75.97 468.93 -71.11Q477.39 -66.24 481.88 -57.55Q486.38 -48.86 486.38 -37.25Q486.38 -25.7 481.88 -17.01Q477.39 -8.32 468.93 -3.46Q460.47 1.41 448.73 1.41ZM448.73 -16.51Q453.22 -16.51 456.31 -19.13Q459.4 -21.74 460.98 -26.44Q462.55 -31.14 462.55 -37.38Q462.55 -43.62 460.98 -48.29Q459.4 -52.95 456.31 -55.5Q453.22 -58.05 448.73 -58.05Q444.23 -58.05 441.14 -55.5Q438.06 -52.95 436.48 -48.29Q434.9 -43.62 434.9 -37.38Q434.9 -31.14 436.48 -26.44Q438.06 -21.74 441.14 -19.13Q444.23 -16.51 448.73 -16.51Z"/>
+</svg>

package/public/manifest.webmanifest

@@ -0,0 +1,91 @@
+{
+  "id": "/",
+  "name": "Kabmo",
+  "short_name": "Kabmo",
+  "description": "Browser console and diagnostic workbench for AI coding agents.",
+  "display": "standalone",
+  "display_override": ["window-controls-overlay", "standalone"],
+  "background_color": "#0B5D3B",
+  "theme_color": "#0B5D3B",
+  "start_url": "/",
+  "scope": "/",
+  "launch_handler": {
+    "client_mode": "focus-existing"
+  },
+  "file_handlers": [
+    {
+      "action": "/open-file",
+      "accept": {
+        "text/plain": [".txt", ".text", ".log", ".env"],
+        "text/markdown": [".md", ".markdown", ".mdx"],
+        "text/csv": [".csv", ".tsv"],
+        "application/json": [".json", ".jsonc"],
+        "application/x-yaml": [".yaml", ".yml"],
+        "application/toml": [".toml"],
+        "application/xml": [".xml"],
+        "text/html": [".html", ".htm"],
+        "text/css": [".css", ".scss", ".less"],
+        "text/javascript": [".js", ".mjs", ".cjs", ".jsx"],
+        "text/x-typescript": [".ts", ".tsx", ".mts", ".cts"],
+        "text/x-python": [".py"],
+        "text/x-go": [".go"],
+        "text/x-rust": [".rs"],
+        "text/x-java": [".java", ".kt", ".kts"],
+        "text/x-ruby": [".rb"],
+        "text/x-php": [".php"],
+        "text/x-c": [".c", ".h"],
+        "text/x-cpp": [".cpp", ".cc", ".hpp"],
+        "text/x-csharp": [".cs"],
+        "text/x-swift": [".swift"],
+        "text/x-sh": [".sh", ".bash", ".zsh"],
+        "text/x-sql": [".sql"],
+        "text/x-diff": [".diff", ".patch"],
+        "image/svg+xml": [".svg"],
+        "image/png": [".png", ".apng"],
+        "image/jpeg": [".jpg", ".jpeg", ".jfif"],
+        "image/gif": [".gif"],
+        "image/webp": [".webp"],
+        "image/avif": [".avif"],
+        "image/bmp": [".bmp"],
+        "image/tiff": [".tif", ".tiff"],
+        "application/pdf": [".pdf"],
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document": [".docx"],
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": [".xlsx", ".xlsm"]
+      },
+      "icons": [
+        {
+          "src": "/icon-192x192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ],
+      "launch_type": "single-client"
+    }
+  ],
+  "icons": [
+    {
+      "src": "/icon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-maskable-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}

package/public/sw.js

@@ -0,0 +1,76 @@
+/**
+ * Kabmo service worker.
+ *
+ * Two jobs, and only the first one is about installability.
+ *
+ * 1. Chromium requires a fetch handler for PWA installability.
+ *
+ * 2. The dev client bundle is cached here rather than by the HTTP cache,
+ *    because the HTTP cache CANNOT hold it. Chrome declines to store a response
+ *    whose decoded body reaches ~5 MB — measured with `Cache-Control: no-cache`
+ *    and a working `ETag`: 1 MB and 4 MB answered `304` on the next load, while
+ *    5, 6, 7, 8, 16 and 20 MB were re-fetched in full every time, never sending
+ *    `If-None-Match`. Bun's development bundle is ~19.7 MB (unminified, by
+ *    design), so it was re-downloaded on every single page load — the whole of
+ *    the dev-mode bandwidth complaint. Cache Storage has no such per-entry
+ *    limit, so this is the one layer that can hold it.
+ *
+ * Only `/_dev-assets/client/*` is cached: that is the bundle, whose filename
+ * carries a build-generation hash that changes on every rebuild, so a URL is a
+ * reliable key for its bytes. `/_dev-assets/asset/*` is deliberately NOT
+ * cached — a CSS asset keeps its name while its content changes (appending a
+ * rule to `tailwind.css` changes the bytes served at the same URL), so
+ * cache-first there would serve stale styles; those go to the network and are
+ * revalidated by the server's own `ETag`, which answers `304`.
+ *
+ * One bundle generation is kept at a time: storing a new one drops the rest, so
+ * the cache cannot grow by one bundle per rebuild. Nothing here runs in
+ * production — the URLs it matches do not exist there.
+ */
+
+const BUNDLE_CACHE = 'kabmo-dev-bundle';
+
+/** The cache this worker used before the rename. */
+const LEGACY_BUNDLE_CACHE = 'ompchamber-dev-bundle';
+const BUNDLE_PREFIX = '/_dev-assets/client/';
+
+self.addEventListener('install', () => {
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    (async () => {
+      // The pre-rename cache holds a whole development bundle and nothing will
+      // ever read it again — the key it was stored under is gone. Dropping it
+      // here is the only thing that can reclaim those bytes on a client that
+      // was already running when the worker changed.
+      await caches.delete(LEGACY_BUNDLE_CACHE);
+      await self.clients.claim();
+    })(),
+  );
+});
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+  if (event.request.method !== 'GET') return;
+  if (url.origin !== self.location.origin) return;
+  if (!url.pathname.startsWith(BUNDLE_PREFIX)) return;
+
+  event.respondWith(
+    (async () => {
+      const cache = await caches.open(BUNDLE_CACHE);
+      const hit = await cache.match(url.pathname);
+      if (hit) return hit;
+
+      const response = await fetch(event.request);
+      if (response.ok) {
+        await cache.put(url.pathname, response.clone());
+        // The previous generation is dead the moment a new one is stored.
+        const stale = await cache.keys();
+        await Promise.all(stale.filter((key) => new URL(key.url).pathname !== url.pathname).map((key) => cache.delete(key)));
+      }
+      return response;
+    })(),
+  );
+});

package/src/cli/kabmo.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { main } from '@/cli/main.js';
+
+main('kabmo');

package/src/cli/lib/args.js

@@ -0,0 +1,283 @@
+/**
+ * Command-line argument parsing for Kabmo CLI.
+ *
+ * Pure and side-effect free: it never throws, never exits and never writes
+ * to a stream. Callers decide how to react to `unknown` flags.
+ */
+
+const BOOLEAN_LONG = new Set([
+  'lan',
+  'dev',
+  'prod',
+  'foreground',
+  'no-daemon',
+  'tls',
+  'all',
+  'follow',
+  'check',
+  'force',
+  'no-restart',
+  'tray',
+  'startup',
+  'json',
+  'quiet',
+  'help',
+  'version',
+]);
+
+// Flags that set a DIFFERENTLY NAMED option, so a hyphenated flag can land on a
+// camelCase key. `--start-server` and `--no-icon` are here rather than in
+// BOOLEAN_LONG for exactly that reason: BOOLEAN_LONG stores the flag under its
+// own spelling (`options['start-server']`), and a command reading
+// `options.startServer` would then never see the flag — measured: `tray run
+// --start-server` reported `server.started: false` because the option it set was
+// never the one the command read.
+const NEGATED_LONG = {
+  'no-daemon': { key: 'foreground', value: true },
+  'no-restart': { key: 'restart', value: false },
+  'no-ui-password': { key: 'noUiPassword', value: true },
+  'no-startup': { key: 'startup', value: false },
+};
+
+const SHORT_TO_LONG = {
+  p: 'port',
+  n: 'lines',
+  f: 'follow',
+  c: 'check',
+  q: 'quiet',
+  h: 'help',
+  v: 'version',
+};
+
+const SHORT_VALUE = new Set(['p', 'n']);
+
+function toNumberOrNull(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return null;
+  }
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function takeValue(tokens, index, inline) {
+  if (typeof inline === 'string' && inline.length > 0) {
+    return { value: inline, nextIndex: index };
+  }
+  const candidate = tokens[index + 1];
+  if (typeof candidate === 'string' && !candidate.startsWith('-')) {
+    return { value: candidate, nextIndex: index + 1 };
+  }
+  return { value: undefined, nextIndex: index };
+}
+
+/**
+ * Parse `process.argv.slice(2)` into a command, positionals and options.
+ */
+export function parseArgs(argv) {
+  const tokens = Array.isArray(argv) ? argv.slice() : [];
+  const options = {
+    port: null,
+    host: null,
+    lan: false,
+    dev: false,
+    prod: false,
+    foreground: false,
+    tls: false,
+    uiPassword: null,
+    uiPasswordFile: null,
+    noUiPassword: false,
+    all: false,
+    follow: false,
+    check: false,
+    force: false,
+    restart: true,
+    lines: null,
+    tray: false,
+    startup: null,
+    json: false,
+    quiet: false,
+    help: false,
+    version: false,
+  };
+  const unknown = [];
+  const nonFlags = [];
+
+  const applyLong = (name, inline, index) => {
+    if (name === 'port') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.port = toNumberOrNull(value);
+      return nextIndex;
+    }
+    if (name === 'ui-password') {
+      // Optional value: `--ui-password` with nothing after it (or followed by
+      // another flag) asks for a generated one, which `serve` mints. Recorded as
+      // an empty string so `null` keeps meaning "not mentioned".
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.uiPassword = typeof value === 'string' && value.length > 0 ? value : '';
+      return nextIndex;
+    }
+    if (name === 'ui-password-file') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.uiPasswordFile = typeof value === 'string' && value.length > 0 ? value : null;
+      return nextIndex;
+    }
+    if (name === 'lines') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.lines = toNumberOrNull(value);
+      return nextIndex;
+    }
+    if (name === 'host' || name === 'hostname') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.host = typeof value === 'string' ? value : null;
+      return nextIndex;
+    }
+    const negated = NEGATED_LONG[name];
+    if (negated) {
+      options[negated.key] = negated.value;
+      return index;
+    }
+    if (BOOLEAN_LONG.has(name)) {
+      options[name] = true;
+      return index;
+    }
+    unknown.push(`--${name}`);
+    return index;
+  };
+
+  for (let i = 0; i < tokens.length; i += 1) {
+    const arg = tokens[i];
+
+    if (typeof arg !== 'string') {
+      continue;
+    }
+
+    if (arg === '--') {
+      for (let j = i + 1; j < tokens.length; j += 1) {
+        nonFlags.push(tokens[j]);
+      }
+      break;
+    }
+
+    if (!arg.startsWith('-') || arg === '-') {
+      nonFlags.push(arg);
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      const name = eq >= 0 ? arg.slice(2, eq) : arg.slice(2);
+      const inline = eq >= 0 ? arg.slice(eq + 1) : undefined;
+      i = applyLong(name, inline, i);
+      continue;
+    }
+
+    const body = arg.slice(1);
+    const shortName = body[0];
+    const attached = body.length > 1 ? body.slice(1) : undefined;
+    const longName = SHORT_TO_LONG[shortName];
+
+    if (!longName) {
+      unknown.push(arg);
+      continue;
+    }
+
+    if (SHORT_VALUE.has(shortName)) {
+      const { value, nextIndex } = takeValue(tokens, i, attached);
+      if (longName === 'port') {
+        options.port = toNumberOrNull(value);
+      } else {
+        options.lines = toNumberOrNull(value);
+      }
+      i = nextIndex;
+      continue;
+    }
+
+    if (attached !== undefined) {
+      unknown.push(arg);
+      continue;
+    }
+
+    options[longName] = true;
+  }
+
+  const command = nonFlags.length > 0 ? nonFlags[0] : null;
+  const positionals = nonFlags.slice(1);
+
+  return { command, positionals, options, unknown };
+}
+
+/**
+ * Full multi-line help text. Returned (not printed) so the caller owns output.
+ */
+export function helpText(bin = 'kabmo') {
+  return `Kabmo - Developer web console and diagnostic workbench for AI Oh-My-Pi
+
+USAGE:
+  ${bin} [COMMAND] [OPTIONS]
+
+COMMANDS:
+  serve          Start Kabmo web server (default when no command is given)
+  update         Update Kabmo to the latest version on npm
+  stop           Stop the instances the CLI started (--port/--all to stop any)
+  restart        Stop and start again (every CLI-started instance, or --port <port>)
+  status         Show running instances (every one, or --port <port>)
+  logs           Print or follow server logs (every instance, or --port <port>)
+  plugin         Build, type, scaffold or list panel plugins
+                 (build|types|new|list; see "${bin} plugin --help")
+
+OPTIONS:
+  -p, --port <port>       Web server port (default: 3000); scopes status/stop/restart/logs
+  --host <address>        Bind address (default: 127.0.0.1)
+  --hostname <address>    Alias for --host
+  --lan                   Bind to 0.0.0.0 for LAN access (warns when no password is set)
+  --tls                   Serve over HTTPS with a self-signed certificate (generated once)
+  --tray                  Show a menu-bar/notification-area icon for this server
+  --startup               Start the server at login (and show the tray icon now)
+  --no-startup            Remove the login entry
+  --ui-password [value]   Require a password for the browser UI (generates one when omitted)
+  --ui-password-file <p>  Read the password from a file (used by a login entry)
+  --no-ui-password        Disable the UI password for this start
+  --prod                  Accepted for compatibility; production is the default
+  --dev                   Run the dev server from source (HMR, unminified)
+  --foreground            Run the server in the foreground (no daemon)
+  --no-daemon             Alias for --foreground
+  --all                   Every instance, including ones started outside the CLI
+  -c, --check             Report whether a newer release exists without installing it
+  --force                 Reinstall even when already up to date
+  --no-restart            Do not restart a running instance after updating
+  -f, --follow            Follow log output as it is written
+  -n, --lines <count>     Number of log lines to print
+  --json                  Emit machine-readable JSON output
+  -q, --quiet             Suppress non-essential output
+  -h, --help              Show this help
+  -v, --version           Show the version
+
+ENVIRONMENT:
+  KABMO_DATA_DIR          Override the data directory (default: ~/.kabmo)
+  KABMO_PORT              Default web server port
+  KABMO_HOST              Default bind address
+  KABMO_UI_PASSWORD       UI password, hashed into auth.json at startup and
+                          then removed from the environment (see --ui-password)
+  KABMO_OMP_BIN           Path to the omp binary (required; falls back to PATH)
+  NPM_CONFIG_REGISTRY     Registry the update check reads (default: registry.npmjs.org)
+
+  The pre-rename OMPCHAMBER_* spellings of the five KABMO_* variables above are
+  still read, so an existing shell profile or unit file keeps working.
+
+EXAMPLES:
+  ${bin}                       # Start the production server on the default port
+  ${bin} serve --port 8080     # Start on port 8080
+  ${bin} serve --lan           # Start and expose the server on the LAN
+  ${bin} serve --dev           # Run the dev server from source instead
+  ${bin} update --check        # Is a newer release available?
+  ${bin} update                # Update, then restart a running instance
+  ${bin} stop                  # Stop the instances the CLI started
+  ${bin} stop --port 3000      # Stop the instance on port 3000, whoever started it
+  ${bin} restart               # Restart the server
+  ${bin} status                # Show whether the server is running
+  ${bin} logs -f -n 200        # Follow the last 200 log lines
+  ${bin} serve --tray          # Start the server with a tray icon
+  ${bin} serve --startup       # Also start at every login
+  ${bin} serve --no-startup    # Remove the login entry
+`;
+}