hubspaces 0.1.0__tar.gz

hubspaces-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+build/
+__pycache__/
+*.pyc
+.scan_root
+.hub.log
+.venv/
+*.DS_Store
+
+/tasks/

hubspaces-0.1.0/LICENSE

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

hubspaces-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: hubspaces
+Version: 0.1.0
+Summary: Local markdown/HTML browser with split-pane preview, full-text search, and a task board — stdlib-only.
+Project-URL: Homepage, https://github.com/auth-02/hub
+Project-URL: Repository, https://github.com/auth-02/hub
+Author: Atharva
+License: MIT
+License-File: LICENSE
+Keywords: browser,documentation,full-text-search,markdown,notes,static-site
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+![Hub — Every .md & .html, one page](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/banner.png)
+
+<div align="center">
+
+# Hub
+
+**Point it at a folder. Get every `.md` and `.html` inside as one searchable, previewable page.**
+
+[![PyPI](https://img.shields.io/pypi/v/hubspaces)](https://pypi.org/project/hubspaces/)
+[![Python](https://img.shields.io/pypi/pyversions/hubspaces)](https://pypi.org/project/hubspaces/)
+[![tests](https://github.com/auth-02/hub/actions/workflows/tests.yml/badge.svg)](https://github.com/auth-02/hub/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**[📖 Docs & live demo →](https://auth-02.github.io/hub/)**
+
+</div>
+
+Hub scans a directory tree, indexes every document into SQLite with full-text search and task lineage, and serves a fast local browser at `http://localhost:8787`. No npm. No framework. No runtime dependencies — pure stdlib Python (3.11+).
+
+---
+
+## Install
+
+```bash
+pipx install hubspaces       # isolated, recommended
+# or
+pip install hubspaces
+```
+
+From a clone (no publish needed):
+
+```bash
+git clone https://github.com/auth-02/hub && cd hub
+pipx install .
+```
+
+This puts two commands on your `PATH`: **`hub`** (build the index) and **`hub-server`** (serve it + watch for changes).
+
+## Run
+
+```bash
+cd ~/my-project        # any folder you want to browse
+hub-server             # serves http://localhost:8787 and rebuilds on change
+```
+
+Then open <http://localhost:8787>. That's it — Hub indexes the current directory by default.
+
+Want to see it before pointing it at your own files? `hub --demo` builds the index from a bundled example repo, then `hub-server --demo` serves it.
+
+```bash
+hub-server --demo
+```
+
+---
+
+### Index — grouped by repo, filtered by kind, sorted by recency
+Status badges on every task manifest. Click to cycle `ongoing → completed → paused`, saved instantly.
+
+![Hub index](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/index.png)
+
+### Split-pane preview with task trace
+Click any row to open a live preview. The `// trace` panel links to related runs, artifacts, and the parent task.
+
+![Split-pane preview](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/preview.png)
+
+### Hub Feed — floating activity drawer
+Press `Ctrl+F` or click the `// feed` tab on the right edge. Shows the last 50 file events across the scan root — what changed, which task, when.
+
+![Hub feed drawer](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/feed-drawer.png)
+
+### Hub Timeline — daily work summary
+Press `Ctrl+T` or click the `// timeline` tab. Answers *What have I been working on? / yesterday? / this week?* — grouped by task, with git commits, runs logged, artifacts generated, and task status inline.
+
+![Hub timeline drawer](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/timeline.png)
+
+### Markdown & HTML document pages
+Every file opened in its own tab gets a clean reading view with a `// trace` bar below the heading. HTML artifacts are served with the hub's own CSS injected.
+
+![Markdown document page](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/doc.png)
+
+---
+
+## Features
+
+- **Full-text search** — filter by repo, path, title, and body simultaneously. Implicit AND, `repo:name` prefix supported.
+- **Kind chips** — one-click filters for TASK, RUN, ARTIFACT, CLAUDE, README, DOC, PROMPT. Stack with repo chips and search.
+- **Task status badges** — every task manifest shows a clickable status pill. Cycles `ongoing → completed → paused`. Persisted — survives DB resets, scan-root changes, and git branch switches.
+- **Split-pane preview** — click any row for a live rendered preview with lineage trace. No page navigation needed.
+- **Hub Feed** — floating drawer (`Ctrl+F`) showing recent file activity: what changed, which task, how long ago.
+- **Hub Timeline** — drawer (`Ctrl+T`) with a synthesised daily summary grouped by *today / yesterday / this week*, pulling from the activity log + `git log` across all repos.
+- **Auto-rebuild** — file watcher triggers a rebuild within ~3 s of any change in the scan root.
+- **Keyboard-first** — navigate the full list without a mouse.
+
+---
+
+## Configuration
+
+Everything is optional. Drop a `hub.toml` in the folder you run Hub from (or run `hub init` to scaffold one):
+
+```toml
+[hub]
+scan_root    = "."                      # directory to index (default: CWD)
+port         = 8787                      # local server port
+exclude_dirs = ["vendor", "fixtures"]   # extra dirs to skip (added to built-ins)
+default_view = "board"                   # work | list | board | calendar | activity
+```
+
+Environment variables override the file:
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `HUB_SCAN_ROOT` | *(current directory)* | Directory to scan |
+| `HUB_SERVER_PORT` | `8787` | Server port |
+| `HUB_OUTPUT` | `~/.local/state/hub/build/docs-index.html` | Generated HTML path |
+| `HUB_DB` | `~/.local/state/hub/hub.db` | SQLite database |
+| `HUB_DEBUG` | off | `1` enables logging to `~/.local/state/hub/hub.log` |
+
+Scan-root priority: `--root` flag → `HUB_SCAN_ROOT` → `hub.toml` → `.scan_root` sidecar → current directory.
+You can also change it live: click the scan-root path in the header → edit → **Save & Rebuild**.
+
+---
+
+## Task structure
+
+Hub understands this layout and builds a lineage graph automatically:
+
+```
+{repo}/tasks/{slug}/
+    ├── manifest.md        ← TASK  (links to all below)
+    ├── runs/YYYY-MM-DD/   ← RUN   (↑ back-link to manifest)
+    ├── artifacts/         ← ARTIFACT
+    └── prompts/           ← PROMPT
+```
+
+`hub new task <slug>` scaffolds a valid task for you.
+
+---
+
+## Agent plugin (optional)
+
+Hub is the **viewer**. If you drive work with Claude Code, the companion
+`hub-agent` plugin is the **producer** — it bundles the `manifest` skill, which
+creates and maintains the `tasks/<slug>/manifest.md` structure above as you
+work, so the board, trace, and timeline fill themselves in.
+
+```
+/plugin marketplace add auth-02/hub
+/plugin install hub-agent@hub
+```
+
+Fully opt-in — Hub needs no plugin and no agent to deliver the full
+index/search/preview/trace experience.
+
+---
+
+## Search
+
+| Query | Finds |
+|-------|-------|
+| `session tokens` | files whose title or body contains both words |
+| `repo:tasks manifest` | manifests in the tasks repo |
+| `repo:docs architecture` | docs matching "architecture" |
+
+## Keyboard shortcuts
+
+| Key | Action | | Key | Action |
+|-----|--------|-|-----|--------|
+| `/` | Focus search | | `Enter` | Open in new tab |
+| `Ctrl+F` | Toggle feed drawer | | `j` / `↓` | Next file |
+| `Ctrl+T` | Toggle timeline drawer | | `k` / `↑` | Previous file |
+| `Esc` | Close preview / drawer | | | |
+
+---
+
+## Keep it running (macOS)
+
+Two launchd agents start Hub at login — the server (+ watcher) and a periodic rebuild:
+
+```bash
+bash scripts/setup-launchd.sh
+# custom scan root:
+HUB_SCAN_ROOT=~/work bash scripts/setup-launchd.sh
+```
+
+Reload after upgrading:
+```bash
+launchctl kickstart -k gui/$(id -u)/com.user.hub-server
+launchctl kickstart -k gui/$(id -u)/com.user.hub
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/auth-02/hub && cd hub
+python3 -m hubspace.server      # run from source, no install
+python3 tests/run_tests.py      # 246 tests, stdlib unittest
+```
+
+Layout: code is the `hubspace/` package; all generated/writable state (index, DB, log)
+lives under `~/.local/state/hub/`, never the package directory.

hubspaces-0.1.0/README.md

@@ -0,0 +1,202 @@
+![Hub — Every .md & .html, one page](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/banner.png)
+
+<div align="center">
+
+# Hub
+
+**Point it at a folder. Get every `.md` and `.html` inside as one searchable, previewable page.**
+
+[![PyPI](https://img.shields.io/pypi/v/hubspaces)](https://pypi.org/project/hubspaces/)
+[![Python](https://img.shields.io/pypi/pyversions/hubspaces)](https://pypi.org/project/hubspaces/)
+[![tests](https://github.com/auth-02/hub/actions/workflows/tests.yml/badge.svg)](https://github.com/auth-02/hub/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**[📖 Docs & live demo →](https://auth-02.github.io/hub/)**
+
+</div>
+
+Hub scans a directory tree, indexes every document into SQLite with full-text search and task lineage, and serves a fast local browser at `http://localhost:8787`. No npm. No framework. No runtime dependencies — pure stdlib Python (3.11+).
+
+---
+
+## Install
+
+```bash
+pipx install hubspaces       # isolated, recommended
+# or
+pip install hubspaces
+```
+
+From a clone (no publish needed):
+
+```bash
+git clone https://github.com/auth-02/hub && cd hub
+pipx install .
+```
+
+This puts two commands on your `PATH`: **`hub`** (build the index) and **`hub-server`** (serve it + watch for changes).
+
+## Run
+
+```bash
+cd ~/my-project        # any folder you want to browse
+hub-server             # serves http://localhost:8787 and rebuilds on change
+```
+
+Then open <http://localhost:8787>. That's it — Hub indexes the current directory by default.
+
+Want to see it before pointing it at your own files? `hub --demo` builds the index from a bundled example repo, then `hub-server --demo` serves it.
+
+```bash
+hub-server --demo
+```
+
+---
+
+### Index — grouped by repo, filtered by kind, sorted by recency
+Status badges on every task manifest. Click to cycle `ongoing → completed → paused`, saved instantly.
+
+![Hub index](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/index.png)
+
+### Split-pane preview with task trace
+Click any row to open a live preview. The `// trace` panel links to related runs, artifacts, and the parent task.
+
+![Split-pane preview](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/preview.png)
+
+### Hub Feed — floating activity drawer
+Press `Ctrl+F` or click the `// feed` tab on the right edge. Shows the last 50 file events across the scan root — what changed, which task, when.
+
+![Hub feed drawer](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/feed-drawer.png)
+
+### Hub Timeline — daily work summary
+Press `Ctrl+T` or click the `// timeline` tab. Answers *What have I been working on? / yesterday? / this week?* — grouped by task, with git commits, runs logged, artifacts generated, and task status inline.
+
+![Hub timeline drawer](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/timeline.png)
+
+### Markdown & HTML document pages
+Every file opened in its own tab gets a clean reading view with a `// trace` bar below the heading. HTML artifacts are served with the hub's own CSS injected.
+
+![Markdown document page](https://raw.githubusercontent.com/auth-02/hub/main/hubspace/assets/screenshots/doc.png)
+
+---
+
+## Features
+
+- **Full-text search** — filter by repo, path, title, and body simultaneously. Implicit AND, `repo:name` prefix supported.
+- **Kind chips** — one-click filters for TASK, RUN, ARTIFACT, CLAUDE, README, DOC, PROMPT. Stack with repo chips and search.
+- **Task status badges** — every task manifest shows a clickable status pill. Cycles `ongoing → completed → paused`. Persisted — survives DB resets, scan-root changes, and git branch switches.
+- **Split-pane preview** — click any row for a live rendered preview with lineage trace. No page navigation needed.
+- **Hub Feed** — floating drawer (`Ctrl+F`) showing recent file activity: what changed, which task, how long ago.
+- **Hub Timeline** — drawer (`Ctrl+T`) with a synthesised daily summary grouped by *today / yesterday / this week*, pulling from the activity log + `git log` across all repos.
+- **Auto-rebuild** — file watcher triggers a rebuild within ~3 s of any change in the scan root.
+- **Keyboard-first** — navigate the full list without a mouse.
+
+---
+
+## Configuration
+
+Everything is optional. Drop a `hub.toml` in the folder you run Hub from (or run `hub init` to scaffold one):
+
+```toml
+[hub]
+scan_root    = "."                      # directory to index (default: CWD)
+port         = 8787                      # local server port
+exclude_dirs = ["vendor", "fixtures"]   # extra dirs to skip (added to built-ins)
+default_view = "board"                   # work | list | board | calendar | activity
+```
+
+Environment variables override the file:
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `HUB_SCAN_ROOT` | *(current directory)* | Directory to scan |
+| `HUB_SERVER_PORT` | `8787` | Server port |
+| `HUB_OUTPUT` | `~/.local/state/hub/build/docs-index.html` | Generated HTML path |
+| `HUB_DB` | `~/.local/state/hub/hub.db` | SQLite database |
+| `HUB_DEBUG` | off | `1` enables logging to `~/.local/state/hub/hub.log` |
+
+Scan-root priority: `--root` flag → `HUB_SCAN_ROOT` → `hub.toml` → `.scan_root` sidecar → current directory.
+You can also change it live: click the scan-root path in the header → edit → **Save & Rebuild**.
+
+---
+
+## Task structure
+
+Hub understands this layout and builds a lineage graph automatically:
+
+```
+{repo}/tasks/{slug}/
+    ├── manifest.md        ← TASK  (links to all below)
+    ├── runs/YYYY-MM-DD/   ← RUN   (↑ back-link to manifest)
+    ├── artifacts/         ← ARTIFACT
+    └── prompts/           ← PROMPT
+```
+
+`hub new task <slug>` scaffolds a valid task for you.
+
+---
+
+## Agent plugin (optional)
+
+Hub is the **viewer**. If you drive work with Claude Code, the companion
+`hub-agent` plugin is the **producer** — it bundles the `manifest` skill, which
+creates and maintains the `tasks/<slug>/manifest.md` structure above as you
+work, so the board, trace, and timeline fill themselves in.
+
+```
+/plugin marketplace add auth-02/hub
+/plugin install hub-agent@hub
+```
+
+Fully opt-in — Hub needs no plugin and no agent to deliver the full
+index/search/preview/trace experience.
+
+---
+
+## Search
+
+| Query | Finds |
+|-------|-------|
+| `session tokens` | files whose title or body contains both words |
+| `repo:tasks manifest` | manifests in the tasks repo |
+| `repo:docs architecture` | docs matching "architecture" |
+
+## Keyboard shortcuts
+
+| Key | Action | | Key | Action |
+|-----|--------|-|-----|--------|
+| `/` | Focus search | | `Enter` | Open in new tab |
+| `Ctrl+F` | Toggle feed drawer | | `j` / `↓` | Next file |
+| `Ctrl+T` | Toggle timeline drawer | | `k` / `↑` | Previous file |
+| `Esc` | Close preview / drawer | | | |
+
+---
+
+## Keep it running (macOS)
+
+Two launchd agents start Hub at login — the server (+ watcher) and a periodic rebuild:
+
+```bash
+bash scripts/setup-launchd.sh
+# custom scan root:
+HUB_SCAN_ROOT=~/work bash scripts/setup-launchd.sh
+```
+
+Reload after upgrading:
+```bash
+launchctl kickstart -k gui/$(id -u)/com.user.hub-server
+launchctl kickstart -k gui/$(id -u)/com.user.hub
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/auth-02/hub && cd hub
+python3 -m hubspace.server      # run from source, no install
+python3 tests/run_tests.py      # 246 tests, stdlib unittest
+```
+
+Layout: code is the `hubspace/` package; all generated/writable state (index, DB, log)
+lives under `~/.local/state/hub/`, never the package directory.

hubspaces-0.1.0/hubspace/assets/favicon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" fill="#F4EFE4"/>
+  <g stroke="#7A2828" stroke-width="1.5">
+    <line x1="16" y1="16" x2="16" y2="6"/>
+    <line x1="16" y1="16" x2="25" y2="22"/>
+    <line x1="16" y1="16" x2="7" y2="22"/>
+  </g>
+  <g fill="#7A2828">
+    <circle cx="16" cy="6" r="2.6"/>
+    <circle cx="25" cy="22" r="2.6"/>
+    <circle cx="7" cy="22" r="2.6"/>
+    <circle cx="16" cy="16" r="4.2"/>
+  </g>
+</svg>