holoctl 0.5.0__tar.gz

holoctl-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Carillo
+
+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.

holoctl-0.5.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: holoctl
+Version: 0.5.0
+Summary: Universal project operating system for AI coding assistants
+Author: Felipe Carillo
+License: MIT License
+        
+        Copyright (c) 2026 Felipe Carillo
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/FelipeCarillo/holoctl
+Project-URL: Repository, https://github.com/FelipeCarillo/holoctl
+Keywords: ai,project-management,kanban,claude-code,cursor,windsurf,copilot,aider,agents,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Dynamic: license-file
+
+# holoctl
+
+> Universal project operating system for AI coding assistants.
+
+<p>
+  <a href="./README.md"><img src="https://img.shields.io/badge/lang-English-blue?style=flat-square" alt="English"/></a>
+  <a href="./README.pt-br.md"><img src="https://img.shields.io/badge/lang-Português-green?style=flat-square" alt="Português"/></a>
+</p>
+
+[![PyPI version](https://img.shields.io/pypi/v/holoctl.svg)](https://pypi.org/project/holoctl/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/holoctl.svg)](https://pypi.org/project/holoctl/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg)](https://www.python.org)
+
+---
+
+## What is holoctl?
+
+**holoctl** is a CLI tool that turns any directory into a fully structured AI-ready project. It gives you a Kanban board, agent definitions, slash commands, and a live web dashboard — all version-controlled in `.holoctl/` alongside your code.
+
+One project root. Any number of sub-repos and directories underneath. One `/holoctl` slash command to set it all up inside Claude Code.
+
+```
+my-project/              ← project root (holoctl init here)
+├── backend/             [git · Node]
+├── frontend/            [git · React]
+├── mobile/              [git · React Native]
+├── infra/               [Terraform]
+├── .holoctl/            ← all project state lives here
+│   ├── config.json
+│   ├── board/
+│   │   └── tickets/
+│   ├── agents/
+│   ├── commands/
+│   └── context/
+└── README.md
+```
+
+---
+
+## Install
+
+Recommended (handles PATH automatically):
+
+```bash
+uv tool install holoctl
+```
+
+Or with pip:
+
+```bash
+pip install holoctl
+```
+
+> **`holoctl` lives entirely inside your workspace.** It writes nothing to `$HOME` and keeps no global registry of projects. Initialize once with `holoctl init`, run `holoctl compile --target claude` to wire up the `/holoctl` slash command in that workspace's `.claude/commands/`. Repeat per workspace.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Go to your project root
+cd ~/my-project
+
+# 2. Initialize
+holoctl init
+
+# 3. Open the dashboard
+holoctl serve
+# → http://127.0.0.1:4242
+
+# 4. Compile for your AI tool(s)
+holoctl compile --target claude    # CLAUDE.md + .claude/commands/
+holoctl compile --target cursor    # .cursor/commands/ + .cursor/rules/
+holoctl compile --target windsurf  # .windsurfrules
+holoctl compile --target copilot   # .github/copilot-instructions.md
+holoctl compile --target devin     # AGENTS.md + .devin/skills/
+```
+
+Or just type `/holoctl` in Claude Code — it detects, initializes, and compiles automatically.
+
+---
+
+## Features
+
+### 📋 Kanban Board
+
+Ticket management built for AI agents. Every ticket is a Markdown file with frontmatter — readable by humans and machines.
+
+```bash
+holoctl board add '{"title":"Add auth flow","agent":"developer","projects":["backend"]}'
+holoctl board add '{"title":"Wire SSE","agent":"developer","projects":["backend","frontend"]}'
+holoctl board ls
+holoctl board ls --project backend --status doing
+holoctl board move PRJ-001 doing
+holoctl board set PRJ-001 priority p0
+holoctl board stat
+```
+
+Tickets vincúlam a **um ou vários** projetos descobertos no workspace via o campo `projects: string[]` (substituiu o antigo `scope`).
+
+### 📁 Multi-Project Workspace
+
+A workspace (the directory where you ran `holoctl init`) is auto-scanned: any direct subdirectory containing a project marker (`.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, …) appears as a project in the dashboard's **Projects** tab and on the board's project filter — no manual registration required.
+
+```bash
+holoctl repo list                          # see what was discovered
+holoctl repo add ./infra --name infra     # optional: override / add a subdir the scan missed
+holoctl repo info backend
+```
+
+### 🌐 Web Dashboard
+
+```bash
+holoctl serve              # http://127.0.0.1:4242 (localhost only)
+holoctl serve --host 0.0.0.0  # expose on local network
+```
+
+| Tab | Description |
+|---|---|
+| **Board** | Kanban view with real-time SSE updates |
+| **Repos** | Git status per sub-repo: branch, last commit, remote link |
+| **Files** | Full file tree with tech-stack badges |
+| **Agents** | AI agent definitions |
+| **Commands** | Slash commands library |
+| **Context** | Project knowledge base |
+
+**File tree badges:** Git, Node, React, Vue, React Native, Python, Go, Rust, Flutter, Docker, Terraform, iOS, Java, PHP.
+
+### 🤖 AI Tool Integration
+
+`holoctl compile` translates `.holoctl/` into the native format of each AI tool:
+
+| Tool | Slash Command | Context File |
+|---|---|---|
+| Claude Code | `.claude/commands/*.md` | `CLAUDE.md` |
+| Cursor | `.cursor/commands/*.md` | `.cursor/rules/holoctl.md` |
+| Windsurf | (n/a) | `.windsurfrules` |
+| GitHub Copilot | (n/a) | `.github/copilot-instructions.md` |
+| Devin CLI | `.devin/skills/*/SKILL.md` | `AGENTS.md` |
+
+### 🔧 No Global Setup
+
+`holoctl` writes nothing to `$HOME` — there is no global registry of projects and no global slash-command installer. The `/holoctl` slash command is generated **per workspace** by `holoctl compile --target claude`, which writes `.claude/commands/holoctl.md` inside that workspace. Run `compile` once per workspace where you want the slash command available.
+
+---
+
+## Commands
+
+```
+holoctl init               Initialize .holoctl/ in the current workspace
+holoctl overview           One-screen workspace snapshot (board, projects, agents, suggested next)
+holoctl board <cmd>        Manage tickets (add, ls, move, set, stat, get)
+holoctl repo <cmd>         Inspect / override discovered subprojects
+holoctl compile            Compile to tool-specific files
+holoctl serve              Start the web dashboard
+holoctl agent <cmd>        Manage agent definitions
+holoctl doctor             Check workspace health
+```
+
+---
+
+## .holoctl/ Structure
+
+```
+.holoctl/
+├── config.json          ← project settings (name, prefix, board config, repos)
+├── activity.jsonl       ← append-only event log
+├── board/
+│   ├── index.json       ← ticket index (auto-rebuilt from .md files)
+│   └── tickets/
+│       └── PRJ-001-my-ticket.md
+├── agents/
+│   └── developer.md
+├── commands/
+│   └── review.md
+└── context/
+    ├── decisions/
+    └── documents/
+```
+
+---
+
+## Ticket Format
+
+```markdown
+---
+id: PRJ-001
+title: Add authentication
+agent: developer
+projects: backend, shared
+status: doing
+priority: p1
+sprint: sprint-1
+created: 2026-05-04
+updated: 2026-05-04
+completed: null
+depends: null
+tags: auth, security
+---
+
+# Start
+(Current state before starting)
+
+# Goal — Definition of Done
+- [ ] JWT auth implemented
+- [ ] Tests passing
+
+# Context
+Why this ticket exists.
+```
+
+---
+
+## Configuration
+
+```json
+{
+  "project": {
+    "name": "My Project",
+    "prefix": "MP",
+    "repos": [
+      { "name": "backend",  "path": "./backend",  "description": "Node API" },
+      { "name": "frontend", "path": "./frontend", "description": "React app" }
+    ]
+  },
+  "board": {
+    "statuses": ["backlog", "doing", "review", "done", "cancelled"],
+    "priorities": ["p0", "p1", "p2", "p3"],
+    "idPadding": 3
+  },
+  "targets": ["claude", "cursor"]
+}
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.11
+
+---
+
+## License
+
+MIT © [Felipe Carillo](https://github.com/FelipeCarillo)

holoctl-0.5.0/README.md

@@ -0,0 +1,246 @@
+# holoctl
+
+> Universal project operating system for AI coding assistants.
+
+<p>
+  <a href="./README.md"><img src="https://img.shields.io/badge/lang-English-blue?style=flat-square" alt="English"/></a>
+  <a href="./README.pt-br.md"><img src="https://img.shields.io/badge/lang-Português-green?style=flat-square" alt="Português"/></a>
+</p>
+
+[![PyPI version](https://img.shields.io/pypi/v/holoctl.svg)](https://pypi.org/project/holoctl/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/holoctl.svg)](https://pypi.org/project/holoctl/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg)](https://www.python.org)
+
+---
+
+## What is holoctl?
+
+**holoctl** is a CLI tool that turns any directory into a fully structured AI-ready project. It gives you a Kanban board, agent definitions, slash commands, and a live web dashboard — all version-controlled in `.holoctl/` alongside your code.
+
+One project root. Any number of sub-repos and directories underneath. One `/holoctl` slash command to set it all up inside Claude Code.
+
+```
+my-project/              ← project root (holoctl init here)
+├── backend/             [git · Node]
+├── frontend/            [git · React]
+├── mobile/              [git · React Native]
+├── infra/               [Terraform]
+├── .holoctl/            ← all project state lives here
+│   ├── config.json
+│   ├── board/
+│   │   └── tickets/
+│   ├── agents/
+│   ├── commands/
+│   └── context/
+└── README.md
+```
+
+---
+
+## Install
+
+Recommended (handles PATH automatically):
+
+```bash
+uv tool install holoctl
+```
+
+Or with pip:
+
+```bash
+pip install holoctl
+```
+
+> **`holoctl` lives entirely inside your workspace.** It writes nothing to `$HOME` and keeps no global registry of projects. Initialize once with `holoctl init`, run `holoctl compile --target claude` to wire up the `/holoctl` slash command in that workspace's `.claude/commands/`. Repeat per workspace.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Go to your project root
+cd ~/my-project
+
+# 2. Initialize
+holoctl init
+
+# 3. Open the dashboard
+holoctl serve
+# → http://127.0.0.1:4242
+
+# 4. Compile for your AI tool(s)
+holoctl compile --target claude    # CLAUDE.md + .claude/commands/
+holoctl compile --target cursor    # .cursor/commands/ + .cursor/rules/
+holoctl compile --target windsurf  # .windsurfrules
+holoctl compile --target copilot   # .github/copilot-instructions.md
+holoctl compile --target devin     # AGENTS.md + .devin/skills/
+```
+
+Or just type `/holoctl` in Claude Code — it detects, initializes, and compiles automatically.
+
+---
+
+## Features
+
+### 📋 Kanban Board
+
+Ticket management built for AI agents. Every ticket is a Markdown file with frontmatter — readable by humans and machines.
+
+```bash
+holoctl board add '{"title":"Add auth flow","agent":"developer","projects":["backend"]}'
+holoctl board add '{"title":"Wire SSE","agent":"developer","projects":["backend","frontend"]}'
+holoctl board ls
+holoctl board ls --project backend --status doing
+holoctl board move PRJ-001 doing
+holoctl board set PRJ-001 priority p0
+holoctl board stat
+```
+
+Tickets vincúlam a **um ou vários** projetos descobertos no workspace via o campo `projects: string[]` (substituiu o antigo `scope`).
+
+### 📁 Multi-Project Workspace
+
+A workspace (the directory where you ran `holoctl init`) is auto-scanned: any direct subdirectory containing a project marker (`.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, …) appears as a project in the dashboard's **Projects** tab and on the board's project filter — no manual registration required.
+
+```bash
+holoctl repo list                          # see what was discovered
+holoctl repo add ./infra --name infra     # optional: override / add a subdir the scan missed
+holoctl repo info backend
+```
+
+### 🌐 Web Dashboard
+
+```bash
+holoctl serve              # http://127.0.0.1:4242 (localhost only)
+holoctl serve --host 0.0.0.0  # expose on local network
+```
+
+| Tab | Description |
+|---|---|
+| **Board** | Kanban view with real-time SSE updates |
+| **Repos** | Git status per sub-repo: branch, last commit, remote link |
+| **Files** | Full file tree with tech-stack badges |
+| **Agents** | AI agent definitions |
+| **Commands** | Slash commands library |
+| **Context** | Project knowledge base |
+
+**File tree badges:** Git, Node, React, Vue, React Native, Python, Go, Rust, Flutter, Docker, Terraform, iOS, Java, PHP.
+
+### 🤖 AI Tool Integration
+
+`holoctl compile` translates `.holoctl/` into the native format of each AI tool:
+
+| Tool | Slash Command | Context File |
+|---|---|---|
+| Claude Code | `.claude/commands/*.md` | `CLAUDE.md` |
+| Cursor | `.cursor/commands/*.md` | `.cursor/rules/holoctl.md` |
+| Windsurf | (n/a) | `.windsurfrules` |
+| GitHub Copilot | (n/a) | `.github/copilot-instructions.md` |
+| Devin CLI | `.devin/skills/*/SKILL.md` | `AGENTS.md` |
+
+### 🔧 No Global Setup
+
+`holoctl` writes nothing to `$HOME` — there is no global registry of projects and no global slash-command installer. The `/holoctl` slash command is generated **per workspace** by `holoctl compile --target claude`, which writes `.claude/commands/holoctl.md` inside that workspace. Run `compile` once per workspace where you want the slash command available.
+
+---
+
+## Commands
+
+```
+holoctl init               Initialize .holoctl/ in the current workspace
+holoctl overview           One-screen workspace snapshot (board, projects, agents, suggested next)
+holoctl board <cmd>        Manage tickets (add, ls, move, set, stat, get)
+holoctl repo <cmd>         Inspect / override discovered subprojects
+holoctl compile            Compile to tool-specific files
+holoctl serve              Start the web dashboard
+holoctl agent <cmd>        Manage agent definitions
+holoctl doctor             Check workspace health
+```
+
+---
+
+## .holoctl/ Structure
+
+```
+.holoctl/
+├── config.json          ← project settings (name, prefix, board config, repos)
+├── activity.jsonl       ← append-only event log
+├── board/
+│   ├── index.json       ← ticket index (auto-rebuilt from .md files)
+│   └── tickets/
+│       └── PRJ-001-my-ticket.md
+├── agents/
+│   └── developer.md
+├── commands/
+│   └── review.md
+└── context/
+    ├── decisions/
+    └── documents/
+```
+
+---
+
+## Ticket Format
+
+```markdown
+---
+id: PRJ-001
+title: Add authentication
+agent: developer
+projects: backend, shared
+status: doing
+priority: p1
+sprint: sprint-1
+created: 2026-05-04
+updated: 2026-05-04
+completed: null
+depends: null
+tags: auth, security
+---
+
+# Start
+(Current state before starting)
+
+# Goal — Definition of Done
+- [ ] JWT auth implemented
+- [ ] Tests passing
+
+# Context
+Why this ticket exists.
+```
+
+---
+
+## Configuration
+
+```json
+{
+  "project": {
+    "name": "My Project",
+    "prefix": "MP",
+    "repos": [
+      { "name": "backend",  "path": "./backend",  "description": "Node API" },
+      { "name": "frontend", "path": "./frontend", "description": "React app" }
+    ]
+  },
+  "board": {
+    "statuses": ["backlog", "doing", "review", "done", "cancelled"],
+    "priorities": ["p0", "p1", "p2", "p3"],
+    "idPadding": 3
+  },
+  "targets": ["claude", "cursor"]
+}
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.11
+
+---
+
+## License
+
+MIT © [Felipe Carillo](https://github.com/FelipeCarillo)

holoctl-0.5.0/holoctl/__init__.py

@@ -0,0 +1,5 @@
+try:
+    from importlib.metadata import version
+    __version__ = version("holoctl")
+except Exception:
+    __version__ = "0.3.0"

holoctl-0.5.0/holoctl/__main__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import sys
+
+if sys.platform == "win32":
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+import typer
+
+from .cli.init_ import app as _init_app, init_cmd
+from .cli.board import app as _board_app
+from .cli.compile_ import app as _compile_app, compile_cmd
+from .cli.sync_ import app as _sync_app, sync_cmd
+from .cli.doctor import app as _doctor_app, doctor_cmd
+from .cli.agent import app as _agent_app
+from .cli.repo import app as _repo_app
+from .cli.serve import app as _serve_app, serve_cmd
+from .cli.overview import app as _overview_app, overview_cmd
+from . import __version__
+
+app = typer.Typer(
+    name="holoctl",
+    help="Universal project operating system for AI coding assistants",
+    no_args_is_help=True,
+)
+
+# Sub-group commands
+app.add_typer(_board_app, name="board", help="Manage the project board")
+app.add_typer(_agent_app, name="agent", help="Manage agent definitions")
+app.add_typer(_repo_app, name="repo", help="Manage repos within a project")
+
+# Direct commands
+app.command("init")(init_cmd)
+app.command("compile")(compile_cmd)
+app.command("sync")(sync_cmd)
+app.command("doctor")(doctor_cmd)
+app.command("serve")(serve_cmd)
+app.command("overview")(overview_cmd)
+
+
+def _version_callback(value: bool):
+    if value:
+        print(__version__)
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: bool = typer.Option(None, "--version", "-v", callback=_version_callback, is_eager=True),
+    ctx: typer.Context = typer.Context,
+):
+    pass
+
+
+if __name__ == "__main__":
+    app()

holoctl-0.5.0/holoctl/cli/_console.py

@@ -0,0 +1,4 @@
+from rich.console import Console
+
+# Force modern Windows terminal rendering — avoids cp1252 encoding errors on legacy console.
+console = Console(legacy_windows=False)