noru 0.1.0__tar.gz

noru-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Louis Pham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

noru-0.1.0/PKG-INFO

@@ -0,0 +1,501 @@
+Metadata-Version: 2.4
+Name: noru
+Version: 0.1.0
+Summary: Autonomous orchestrator for Claude Code — runs your task queue 24/7
+Author: Louis
+Keywords: claude,orchestrator,automation,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn[standard]
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: qrcode>=7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">🤖 Noru</h1>
+  <p align="center">
+    <strong>Ship while you sleep — autonomous Claude Code orchestration</strong>
+  </p>
+  <p align="center">
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+    <a href="https://github.com/anthropics/claude-code"><img src="https://img.shields.io/badge/Claude-Code-blueviolet.svg" alt="Claude Code"></a>
+    <a href="#-contributing"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
+  </p>
+</p>
+
+> **Your AI developer that never sleeps.** Noru is a Python CLI + web dashboard that runs Claude Code tasks autonomously 24/7 — managing priorities, token budgets, and idle code reviews so your codebase improves around the clock.
+
+<p align="center">
+  <a href="https://youtu.be/JR6D9MSrjLs">
+    <img src="https://img.youtube.com/vi/JR6D9MSrjLs/maxresdefault.jpg" alt="Noru Demo" width="720">
+  </a>
+  <br>
+  <em>▶️ Watch the demo (2 min)</em>
+</p>
+
+---
+
+## 📑 Table of Contents
+
+- [📑 Table of Contents](#-table-of-contents)
+- [✨ Features](#-features)
+- [🚀 Quick Start](#-quick-start)
+  - [1. Install](#1-install)
+  - [2. Initialize a project](#2-initialize-a-project)
+  - [3. Start the orchestrator](#3-start-the-orchestrator)
+  - [Adding tasks manually](#adding-tasks-manually)
+- [📊 Dashboard](#-dashboard)
+  - [Tabs](#tabs)
+- [⚙️ Configuration](#️-configuration)
+  - [🛡️ Guardrails](#️-guardrails)
+  - [🔍 Idle Review Jobs (16 built-in)](#-idle-review-jobs-16-built-in)
+- [🔧 CLI Reference](#-cli-reference)
+  - [Lifecycle](#lifecycle)
+  - [Task Management](#task-management)
+  - [Project Management](#project-management)
+  - [Configuration](#configuration)
+  - [Idle Reviews](#idle-reviews)
+  - [Direct Execution](#direct-execution)
+- [🔔 Integrations](#-integrations)
+  - [Telegram](#telegram)
+  - [Slack](#slack)
+  - [Discord](#discord)
+- [🌐 Tunnel (Remote Access)](#-tunnel-remote-access)
+- [📡 API Reference](#-api-reference)
+- [🏗️ Architecture](#️-architecture)
+  - [Project Structure](#project-structure)
+  - [Tech Stack](#tech-stack)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🎯 **Autonomous Task Queue** | Priority-based scheduling with weight classes (light/medium/heavy) |
+| 📊 **Real-Time Dashboard** | Kanban board, stats, charts — desktop + mobile responsive |
+| 📊 **Token Budget Management** | 5-hour session windows + weekly limits with auto-pause |
+| 🔍 **Idle Code Reviews** | 16 built-in review types run via watermark refill when ready tasks drop below threshold |
+| ⏸️ **Pause / Resume** | Pause the agent from the CLI or API — server stays up, dispatch stops |
+| 🌍 **Language Config** | Claude responds in your language — 13 supported languages |
+| 📜 **Activity Log** | Persistent event timeline for every dispatch, pause, and state change |
+| 🛡️ **Guardrails** | User-defined rules injected into all prompts to prevent noru from overstepping |
+| 🔌 **Plugin Notifications** | Telegram, Slack, Discord — know when tasks complete |
+| 🌐 **Remote Access** | Built-in tunnel support (cloudflared/ngrok) with QR code |
+| 🔧 **Full REST API** | Everything the dashboard can do, your scripts can too |
+| 📋 **Event Hooks** | Custom notifications on task start, complete, fail |
+| ⚡ **Zero Build Step** | No npm, no webpack, no framework overhead — just Python |
+| 🛡️ **SQLite + WAL** | Fast, reliable, zero-config database |
+
+---
+
+## 🚀 Quick Start
+
+Get Noru running in under 2 minutes:
+
+### 1. Install
+
+```bash
+pip install noru
+```
+
+### 2. Initialize a project
+
+```bash
+cd ~/your-project
+noru init
+```
+
+> 💡 **Tip:** `noru init` scans your project and suggests initial tasks based on TODOs, open issues, and code quality signals.
+
+### 3. Start the orchestrator
+
+```bash
+noru start
+```
+
+That's it. Noru is now running tasks and serving the dashboard at **http://localhost:7777**.
+
+```bash
+# Open the dashboard in your browser
+noru dashboard
+
+# Check what's happening
+noru status
+```
+
+### Adding tasks manually
+
+```bash
+# Add a task
+noru task add --project my-app --title "Fix authentication bug" --priority 1
+
+# Promote it to the queue
+noru task ready 1
+
+# Watch it get picked up automatically
+noru status
+```
+
+---
+
+## 📊 Dashboard
+
+Noru ships with a single-file HTML dashboard — no build step, no node_modules. Just open **http://localhost:7777**.
+
+### Tabs
+
+| Tab | What it shows |
+|-----|---------------|
+| 📈 **Overview** | Metric cards, token window bar, weekly budget bar, agent controls, recent activity |
+| 📋 **Kanban** | 4-column board (Todo → Doing → Review → Done) with project filters |
+| 📁 **Projects** | Project cards with status and task counts |
+| 📝 **Tasks** | Searchable, filterable table with all tasks |
+| 📊 **Stats** | Token usage charts, completion rates, cost tracking |
+
+> 📱 **Mobile friendly.** The dashboard is fully responsive — check on your tasks from your phone while you're out.
+
+---
+
+## ⚙️ Configuration
+
+> **Full reference:** [docs/configuration.md](docs/configuration.md)
+
+Config lives at `~/.noru/config.yaml`. Created automatically on first run, or customize it:
+
+```yaml
+# Core settings
+loop_interval_seconds: 60
+port: 7777
+claude_cli: claude
+
+# Token budget — 5-hour rolling window
+max20_window_tokens: 220000
+window_duration_hours: 5
+
+# Weekly budget
+weekly:
+  seed_limit: 1500000
+  developer_reserve_pct: 0.35    # 35% reserved for your interactive sessions
+  reset_day: monday
+
+# Guardrails — injected into all prompts
+guardrails:
+  - "NEVER change database schema or migrations"
+  - "NEVER re-architect the project layout"
+
+# Watermark refill — trigger idle scans when ready tasks drop below threshold
+watermark:
+  low_watermark: 2
+  scan_cooldown_seconds: 60
+
+# Idle review jobs (run when ready tasks < watermark)
+idle_jobs:
+  max_tasks_per_run: 3
+  jobs:
+    - id: security-scan
+      enabled: true
+    - id: bug-detection
+      enabled: true
+    - id: test-coverage
+      enabled: true
+    # ... see full list below
+```
+
+> 💡 **Tip:** You can also edit configuration from the dashboard's admin panel.
+
+### 🛡️ Guardrails
+
+User-defined rules injected into every prompt noru sends to Claude Code. Use them to set hard boundaries on what noru is allowed to do:
+
+```yaml
+guardrails:
+  - "NEVER change database schema or migrations"
+  - "NEVER re-architect the project layout"
+  - "NEVER modify CI/CD pipelines"
+```
+
+### 🔍 Idle Review Jobs (16 built-in)
+
+When ready tasks drop below the watermark threshold, noru triggers a scan that creates review tasks automatically. This is stateless — no phases, no state machine. Just: `ready_tasks < low_watermark` triggers a scan, then cooldown.
+
+| Job | Default | Focus |
+|-----|---------|-------|
+| `security-scan` | ✅ ON | XSS, injection, secrets, OWASP Top 10 |
+| `bug-detection` | ✅ ON | Test failures, type errors, edge cases |
+| `logic-review` | ✅ ON | Business logic, missing validations |
+| `test-coverage` | ✅ ON | Untested functions, generate tests |
+| `code-quality` | ✅ ON | Dead code, unused imports, TODOs |
+| `refactor` | ⬜ OFF | Extract functions, reduce duplication |
+| `ui-bug-scan` | ⬜ OFF | Visual regressions, broken layouts |
+| `ux-review` | ⬜ OFF | Accessibility, navigation, UX patterns |
+| `ui-polish` | ⬜ OFF | Spacing, alignment, consistency |
+| `perf-audit` | ⬜ OFF | N+1 queries, memory leaks |
+| `docs-update` | ⬜ OFF | Missing docstrings, README gaps |
+| `dependency-check` | ⬜ OFF | Outdated packages, CVEs |
+| `api-review` | ⬜ OFF | Endpoint consistency, validation |
+| `type-safety` | ⬜ OFF | Missing type hints |
+| `error-handling` | ⬜ OFF | Missing try/catch, error propagation |
+| `pr-review` | ⬜ OFF | Review open PRs on GitHub |
+
+```bash
+# Enable/disable review jobs
+noru idle enable perf-audit
+noru idle disable docs-update
+noru idle list
+```
+
+---
+
+## 🔧 CLI Reference
+
+### Lifecycle
+
+| Command | Description |
+|---------|-------------|
+| `noru start` | Start orchestrator + dashboard server |
+| `noru stop` | Graceful stop (finishes current task) |
+| `noru stop --force` | Immediate stop |
+| `noru restart` | Stop then start |
+| `noru pause` | Pause dispatch — server stays up, no tasks run |
+| `noru status` | Current state, queue depth, active task |
+| `noru status --json` | Machine-readable status output |
+| `noru dashboard` | Open dashboard in browser |
+| `noru logs` | Tail orchestrator logs |
+
+### Task Management
+
+| Command | Description |
+|---------|-------------|
+| `noru task add --project ID --title "..." --priority N` | Add a task |
+| `noru task ready ID` | Promote task to the active queue |
+| `noru task list` | List all tasks |
+| `noru task list --status todo --project my-app` | Filter tasks |
+| `noru task done ID` | Mark task done manually |
+| `noru task skip ID` | Skip task (lower priority) |
+
+### Project Management
+
+| Command | Description |
+|---------|-------------|
+| `noru project add --id my-app --name "My App" --repo-path ~/dev/my-app` | Register a project |
+| `noru project list` | List all projects |
+| `noru project pause ID` | Pause a project (skip its tasks) |
+| `noru project resume ID` | Resume a paused project |
+| `noru init` | Scan current directory and propose tasks |
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `noru config show` | View current configuration |
+| `noru config set KEY VALUE` | Set a config value (dot notation) |
+| `noru config reset` | Reset config to defaults |
+
+### Idle Reviews
+
+| Command | Description |
+|---------|-------------|
+| `noru idle list` | Show all review jobs with on/off status |
+| `noru idle enable JOB` | Enable a review job |
+| `noru idle disable JOB` | Disable a review job |
+
+### Direct Execution
+
+| Command | Description |
+|---------|-------------|
+| `noru run` | Run one task now (bypasses scheduler) |
+| `noru run --task ID` | Run a specific task |
+| `noru run --dry-run` | Show the prompt without executing |
+
+---
+
+## 🔔 Integrations
+
+> **Full reference:** [docs/integrations.md](docs/integrations.md)
+
+Noru supports event hooks for notifications when tasks complete, fail, or when the queue empties.
+
+### Telegram
+
+```yaml
+# ~/.noru/config.yaml
+hooks:
+  telegram:
+    enabled: true
+    bot_token: "your-bot-token"
+    chat_id: "your-chat-id"
+    events: [task_completed, task_failed, queue_empty]
+```
+
+### Slack
+
+```yaml
+hooks:
+  slack:
+    enabled: true
+    webhook_url: "https://hooks.slack.com/services/..."
+    events: [task_completed, task_failed]
+```
+
+### Discord
+
+```yaml
+hooks:
+  discord:
+    enabled: true
+    webhook_url: "https://discord.com/api/webhooks/..."
+    events: [task_completed, task_failed]
+```
+
+> 💡 **Tip:** You can combine multiple integrations. All hooks fire independently.
+
+---
+
+## 🌐 Tunnel (Remote Access)
+
+> **Full reference:** [docs/tunnel.md](docs/tunnel.md)
+
+Access your dashboard from anywhere — no port forwarding required.
+
+```bash
+# Start a tunnel (auto-detects cloudflared or ngrok)
+noru tunnel start
+
+# Displays a public URL + QR code for mobile access
+# Example: https://abc123.trycloudflare.com
+```
+
+| Provider | Setup |
+|----------|-------|
+| **cloudflared** (recommended) | `brew install cloudflared` — no account needed |
+| **ngrok** | `brew install ngrok` — free account required |
+
+> ⚠️ **Warning:** The tunnel exposes your dashboard to the internet. Use it on trusted networks or add authentication.
+
+---
+
+## 📡 API Reference
+
+> **Full reference:** [docs/api.md](docs/api.md)
+
+Noru exposes a full REST API at `http://localhost:7777/api`. Everything the dashboard does, your scripts can do too.
+
+**Key endpoints:**
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/status` | Orchestrator state and queue info |
+| `GET` | `/api/tasks` | List all tasks (supports filters) |
+| `POST` | `/api/tasks` | Create a new task |
+| `PATCH` | `/api/tasks/:id` | Update task status or priority |
+| `GET` | `/api/projects` | List all projects |
+| `GET` | `/api/budget` | Token budget status |
+| `GET` | `/api/stats` | Usage statistics and charts data |
+| `POST` | `/api/agent/start` | Start the orchestrator |
+| `POST` | `/api/agent/stop` | Stop the orchestrator |
+
+```bash
+# Example: list tasks via curl
+curl http://localhost:7777/api/tasks | python3 -m json.tool
+
+# Example: add a task via API
+curl -X POST http://localhost:7777/api/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"project_id": "my-app", "title": "Fix login bug", "priority": 1}'
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+noru start
+  └── Python process (single PID)
+       ├── Main thread: uvicorn (FastAPI on :7777)
+       └── Daemon thread: OrchestratorLoop
+            ├── Fetches usage via tmux /usage command (HTTP API fallback)
+            ├── Picks highest-priority eligible task
+            ├── Dispatches to Claude Code via tmux sessions (session-id continuity)
+            ├── Detects 429 rate-limit errors and backs off reactively
+            └── Records results to SQLite (WAL mode)
+```
+
+**Every loop cycle** (default 60s) — scheduler picks one of 4 actions:
+
+1. **dispatch** — evaluate token budgets, pick highest-priority task, send to Claude Code
+2. **sleep** — budget exhausted, wait for token window to refill
+3. **idle** — queue empty + ready tasks below watermark, trigger scan to create review tasks
+4. **create_only** — budget too low for execution, only create/plan tasks
+
+### Project Structure
+
+```
+src/noru/
+├── core/           # Models, database, config, constants (zero external deps)
+├── engine/         # Token monitor, weekly tracker, queue, scheduler
+├── executor/       # WorkerBackend protocol, Claude CLI, dispatcher, idle reviewer
+├── interface/      # Orchestrator loop, Click CLI, FastAPI server, dashboard
+└── integrations/   # Hooks (Telegram, Slack, Discord), superpowers, agency-agent
+```
+
+### Tech Stack
+
+- **Python 3.11+** — threaded orchestrator, zero JS build step
+- **SQLite (WAL mode)** — fast concurrent reads, zero config
+- **FastAPI** — REST API + dashboard serving
+- **Click** — CLI framework
+- **Alpine.js + Chart.js** — dashboard UI (single HTML file)
+
+The `WorkerBackend` protocol abstracts CLI execution. The default `TmuxWorker` manages persistent Claude Code tmux sessions with session-id continuity per project. You can implement your own backend for other LLM CLIs.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Noru is built with a test-first approach.
+
+```bash
+# Clone and install
+git clone https://github.com/pxson2903/noru.git
+cd noru
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run a specific test file
+pytest tests/core/test_database.py -v
+```
+
+**Guidelines:**
+
+- Write tests first, then implement (TDD)
+- Use frozen dataclasses for models
+- All DB queries go in `core/database.py` as named methods
+- Follow the `WorkerBackend` protocol for execution backends
+- Keep `core/` free of external dependencies
+
+---
+
+## 📄 License
+
+MIT — use it, fork it, ship with it.