release: v1.0.6 - PyPI distribution support

Added:
- PyPI distribution: `pip install quorum-cli && quorum` works out of the box
- GitHub Actions workflow for automated PyPI publishing (Trusted Publishing)
- Frontend bundled into wheel automatically

Fixed:
- Startup spinner now shows immediately on all platforms
- /help and /status modals can be closed with ESC key

Changed:
- Simplified launcher scripts with signal file coordination
- Frontend signals readiness for seamless spinner-to-UI transition

Author: Detrol

.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm ci
+          npm run build
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CHANGELOG.md

@@ -7,7 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-<!-- Changes after 1.0.5 release go here -->
+<!-- Changes after 1.0.6 release go here -->
+
+---
+
+## [1.0.6] - 2025-12-13
+
+### Added
+
+- **PyPI Distribution** - Install Quorum with a single command
+  - `pip install quorum-cli && quorum` now works out of the box
+  - Frontend is bundled into the wheel automatically
+  - GitHub Actions workflow for automated PyPI publishing with Trusted Publishing
+
+### Fixed
+
+- **Startup Spinner** - Animated loading spinner now shows immediately on all platforms
+  - Works consistently for both pip install and development mode
+  - Signal file coordination between launcher and frontend
+- **Modal ESC Handling** - `/help` and `/status` modals can now be closed with ESC key
+
+### Changed
+
+- Simplified launcher scripts (removed signal file complexity from user-facing code)
+- Frontend now signals readiness to launcher for seamless spinner-to-UI transition
 
 ---
 
@@ -185,7 +208,9 @@ User cache (`~/.quorum/`):
 
 ---
 
-[Unreleased]: https://github.com/Detrol/quorum-cli/compare/v1.0.4...HEAD
+[Unreleased]: https://github.com/Detrol/quorum-cli/compare/v1.0.6...HEAD
+[1.0.6]: https://github.com/Detrol/quorum-cli/compare/v1.0.5...v1.0.6
+[1.0.5]: https://github.com/Detrol/quorum-cli/compare/v1.0.4...v1.0.5
 [1.0.4]: https://github.com/Detrol/quorum-cli/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/Detrol/quorum-cli/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/Detrol/quorum-cli/compare/v1.0.1...v1.0.2

README.md

@@ -19,15 +19,30 @@
 
 Multi-agent AI discussion system for structured debates. Ask multiple AI models (Claude, GPT, Gemini, Grok, and local models via Ollama) a question and let them debate, brainstorm, or deliberate using seven different methods.
 
-## Requirements
+## Quick Install (pip)
+
+```bash
+pip install quorum-cli
+quorum
+```
+
+That's it! Configure your API keys on first run or create a `.env` file.
+
+**Requirements:** Python 3.11+, Node.js 18+
+
+---
+
+## Development Installation
+
+For contributors or those who want the latest changes:
+
+### Requirements
 
 - Python 3.11 or higher
 - Node.js 18 or higher
 - npm
 - [uv](https://github.com/astral-sh/uv) (auto-installed if missing)
 
-## Installation
-
 ### Linux / macOS
 
 ```bash

frontend/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "quorum-frontend",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Terminal UI for Quorum multi-agent consensus system",
   "license": "BSL-1.1",
   "type": "module",

frontend/package.json

@@ -158,15 +158,16 @@ export function App() {
           setMaxTurns(userSettings.max_turns);
         }
 
-        // Settings loaded - show UI
-        setBackendReady(true);
-
-        // Signal shell spinner to stop and clear screen for UI
+        // Signal launcher spinner to stop and wait briefly for it to clear
         const signalFile = process.env.QUORUM_SIGNAL_FILE;
         if (signalFile) {
-          writeFileSync(signalFile, "ready");
+          try { writeFileSync(signalFile, "ready"); } catch {}
+          await new Promise(r => setTimeout(r, 100)); // Let spinner clear itself
         }
-        process.stdout.write('\x1Bc');
+
+        // Clear screen fully (screen + scrollback + cursor home)
+        process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
+        setBackendReady(true);
 
         // Mark cached validated models immediately
         const cachedValidated = new Set(modelsResult.validated || []);
@@ -697,7 +698,7 @@ export function App() {
     }
   });
 
-  // Render nothing while backend starts (shell spinner handles this)
+  // Render nothing while backend starts (launcher handles spinner)
   if (!backendReady) {
     return null;
   }

frontend/src/App.tsx

@@ -3,10 +3,18 @@
  */
 
 import React from "react";
-import { Box, Text } from "ink";
+import { Box, Text, useInput } from "ink";
 import { t } from "../i18n/index.js";
+import { useStore } from "../store/index.js";
 
 export function Help() {
+  const { setShowHelp } = useStore();
+
+  useInput((input, key) => {
+    if (key.escape) {
+      setShowHelp(false);
+    }
+  });
   return (
     <Box
       flexDirection="column"

frontend/src/components/Help.tsx

@@ -3,7 +3,7 @@
  */
 
 import React from "react";
-import { Box, Text } from "ink";
+import { Box, Text, useInput } from "ink";
 import { useStore } from "../store/index.js";
 import { getModelDisplayName } from "./Message.js";
 import { t } from "../i18n/index.js";
@@ -15,8 +15,15 @@ export function Status() {
     discussionMethod,
     synthesizerMode,
     maxTurns,
+    setShowStatus,
   } = useStore();
 
+  useInput((input, key) => {
+    if (key.escape) {
+      setShowStatus(false);
+    }
+  });
+
   const modelNames = selectedModels.map((id) =>
     getModelDisplayName(id, availableModels)
   );

frontend/src/components/Status.tsx

@@ -5,17 +5,8 @@
 import { spawn, ChildProcess } from "node:child_process";
 import { createInterface, Interface } from "node:readline";
 import { EventEmitter } from "node:events";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
 import { v4 as uuidv4 } from "uuid";
 
-// Get project root directory from this file's location
-// This file is at: frontend/dist/ipc/client.js (after compilation)
-// Project root is 3 levels up: ../../../
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PROJECT_ROOT = join(__dirname, "..", "..", "..");
-
 import type {
   JsonRpcRequest,
   JsonRpcResponse,
@@ -55,17 +46,9 @@ export class BackendClient extends EventEmitter {
   constructor() {
     super();
 
-    // Use venv Python directly - bypasses uv entirely
-    // PROJECT_ROOT is calculated from this file's location, not cwd
-    // This ensures it works regardless of where the user runs quorum from
-
-    // Platform-specific venv Python path
-    const isWindows = process.platform === "win32";
-    const venvPython = isWindows
-      ? join(PROJECT_ROOT, ".venv", "Scripts", "python.exe")
-      : join(PROJECT_ROOT, ".venv", "bin", "python");
-
-    this.pythonCommand = venvPython;
+    // Python tells us where it is via QUORUM_PYTHON env var (set by main.py)
+    // This works for both dev mode and pip install
+    this.pythonCommand = process.env.QUORUM_PYTHON || "python";
     this.pythonArgs = ["-m", "quorum", "--ipc"];
   }
 
@@ -83,8 +66,6 @@ export class BackendClient extends EventEmitter {
 
     this.process = spawn(this.pythonCommand, this.pythonArgs, {
       stdio: ["pipe", "pipe", "pipe"],
-      cwd: PROJECT_ROOT,
-      env: { ...process.env, PYTHONPATH: join(PROJECT_ROOT, "src") },
     });
 
     this.process.on("error", (err) => {

frontend/src/ipc/client.ts

@@ -58,6 +58,9 @@ path = "src/quorum/constants.py"
 [tool.hatch.build.targets.wheel]
 packages = ["src/quorum"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"frontend/dist" = "quorum/_frontend"
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests", "src"]