Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
Initial commit: fork kasten as hyperresearch
Jordanc25137fb99f6
diff --git a/.gitignore b/.gitignorenew file mode 100644index 0000000..9b8b149--- /dev/null+++ b/.gitignore@@ -0,0 +1,13 @@+__pycache__/+*.py[cod]+*.egg-info/+dist/+build/+.venv/+.idea/+*.db+.hyperresearch/+.pytest_cache/+.mypy_cache/+.ruff_cache/+*.eggdiff --git a/CHANGELOG.md b/CHANGELOG.mdnew file mode 100644index 0000000..7a28c2e--- /dev/null+++ b/CHANGELOG.md@@ -0,0 +1,75 @@+# Changelog++All notable changes to this project will be documented in this file.++The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).++## [0.2.0] - 2026-04-07++### Added++- MCP server with 8 read-only tools (`pip install llm-kasten[mcp]`)+- `kasten mcp` command (stdio transport for Claude Desktop, Cursor)+- `kasten tags --min N` to filter out low-count tags+- `kasten tag alias` and `kasten tag suggest` for tag management+- `kasten note update` for single-note metadata changes+- `kasten note new --body-file` to avoid shell escaping+- `kasten note new` returns `existing_tags` in JSON to reduce tag noise+- `kasten search` auto-includes note bodies in JSON mode+- `kasten search --linked-from`, `--linked-to`, `--min-inbound` graph filters+- `kasten repair --enrich` auto-fills missing tags and summaries+- `kasten graph stub` creates stub notes for all broken links+- `kasten serve` with interactive force-directed knowledge graph+- `kasten dedup` for content similarity detection+- Auto-inject docs into CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md+- Temporal index pages: by-month, stale notes, most-linked+- `-j` short flag for `--json` on every command+- Alphanumeric search tokenization (mamba3 matches mamba 3)+- Plural tag normalization during sync+- Note lifecycle: draft, review, evergreen, stale, deprecated, archive+- `missing-summary` and `singleton-tags` lint rules+- Built-in note templates: concept, reference, guide, comparison, moc+- Vintage cream/brown theme for web UI++### Removed++- External LLM dependencies (OpenAI, Anthropic, Ollama providers)+- `kasten compile` and `kasten ask` commands (agents drive everything)+- `kasten ingest` (file, web, pdf) -- agents write files directly+- Semantic search and ranking modules (dead code)+- `kasten promote` and `kasten diff` (redundant with repair and sync --dry-run)++### Fixed++- Wiki-link parser strips trailing backslash from shell escaping artifacts+- URLs in `[[https://...]]` no longer treated as broken note references+- Index generator deletes stale pages before regenerating+- XSS protection in web UI+- Ctrl+C works on Windows for `kasten serve`+- FTS5 BM25 weights now read from config (were hardcoded)+- Import writes to knowledge directory, not vault root+- Batch operations validate status values and handle per-file errors++## [0.1.0] - 2026-04-06++Initial release.++### Core++- Markdown files with YAML frontmatter as source of truth+- SQLite FTS5 full-text search with BM25 ranking and porter stemming+- `[[wiki-link]]` parsing with backlink tracking and broken link detection+- mtime + SHA-256 change detection with atomic transactions++### CLI++- `kasten init`, `status`, `sync`, `search`, `note` CRUD, `graph`, `lint`, `repair`+- `kasten index build` auto-generated wiki pages+- `kasten batch` bulk operations+- `kasten export json` and `export vault`+- `kasten import`, `watch`, `serve`, `git log`+- `--json` on every command with consistent envelope format++[0.2.0]: https://github.com/jordan-gibbs/llm-kasten/releases/tag/v0.2.0+[0.1.0]: https://github.com/jordan-gibbs/llm-kasten/releases/tag/v0.1.0diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..ea4a219--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,76 @@+# Contributing to kasten++Thank you for your interest in contributing.++## Development setup++```bash+git clone https://github.com/jordan-gibbs/kasten.git+cd kasten+python -m venv .venv+source .venv/bin/activate # or .venv\Scripts\activate on Windows+pip install -e ".[dev]"+```++## Running tests++```bash+python -m pytest tests/ -v+```++All tests must pass before submitting a PR. The test suite runs in under 30 seconds.++## Code style++This project uses [ruff](https://docs.astral.sh/ruff/) for linting:++```bash+ruff check src/+ruff format src/+```++Configuration is in `pyproject.toml`. Line length is 100 characters.++## Type checking++```bash+mypy src/kasten/+```++Strict mode is enabled in `pyproject.toml`.++## Submitting changes++1. Fork the repository.+2. Create a branch from `main`.+3. Make your changes with tests.+4. Run `ruff check src/` and `python -m pytest tests/`.+5. Open a pull request against `main`.++Keep PRs focused on a single change. Include a clear description of what changed and why.++## Reporting issues++Open an issue at [github.com/jordan-gibbs/kasten/issues](https://github.com/jordan-gibbs/kasten/issues). Include:++- What you expected to happen+- What actually happened+- Steps to reproduce+- kasten version (`kasten --version`)+- Python version and OS++## Architecture overview++- `src/kasten/core/` -- vault management, sync engine, frontmatter parsing, SQLite schema+- `src/kasten/cli/` -- typer CLI commands, output formatting+- `src/kasten/search/` -- FTS5 search engine, filters, ranking+- `src/kasten/models/` -- Pydantic models for notes, output envelopes+- `src/kasten/graph/` -- link parsing (shared patterns)+- `src/kasten/indexgen/` -- auto-generated index page builder+- `src/kasten/ingest/` -- file, web, PDF ingestion+- `src/kasten/compile/` -- LLM compilation pipeline+- `src/kasten/llm/` -- provider abstraction (OpenAI, Anthropic, Ollama)+- `src/kasten/serve/` -- lightweight web UI server+- `tests/` -- pytest test suite++The key design principle: markdown files are the source of truth, SQLite is a derived cache that can be rebuilt at any time with `kasten sync --force`.diff --git a/LICENSE b/LICENSEnew file mode 100644index 0000000..5edb3e9--- /dev/null+++ b/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 Jordan Gibbs++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.diff --git a/README.md b/README.mdnew file mode 100644index 0000000..f32a337--- /dev/null+++ b/README.md@@ -0,0 +1,9 @@+# Hyperresearch++Agent-driven research knowledge base. Browse, collect, and synthesize web sources into a searchable wiki with `[[wiki-links]]`, full-text search, and structured JSON output.++```bash+pip install hyperresearch+hyperresearch init .+hyperresearch search "query" -j+```diff --git a/pyproject.toml b/pyproject.tomlnew file mode 100644index 0000000..6ba7674--- /dev/null+++ b/pyproject.toml@@ -0,0 +1,80 @@+[build-system]+requires = ["hatchling"]+build-backend = "hatchling.build"++[project]+name = "hyperresearch"+version = "0.1.0"+description = "Agent-driven research knowledge base. Browse, collect, and synthesize web sources into a searchable wiki."+readme = "README.md"+license = "MIT"+requires-python = ">=3.11"+authors = [{name = "Jordan Gibbs", email = "[email protected]"}]+keywords = ["research", "knowledge-base", "wiki", "llm", "markdown", "cli", "agent", "zettelkasten"]+classifiers = [+ "Development Status :: 3 - Alpha",+ "Environment :: Console",+ "Intended Audience :: Developers",+ "License :: OSI Approved :: MIT License",+ "Programming Language :: Python :: 3.11",+ "Programming Language :: Python :: 3.12",+ "Programming Language :: Python :: 3.13",+ "Topic :: Text Processing :: Markup :: Markdown",+]+dependencies = [+ "typer>=0.9.0",+ "rich>=13.0",+ "pyyaml>=6.0",+ "pydantic>=2.0",+ "jinja2>=3.1",+ "platformdirs>=4.0",+]++[project.optional-dependencies]+crawl4ai = ["Crawl4AI>=0.4"]+tavily = ["tavily-python>=0.5"]+firecrawl = ["firecrawl>=1.0"]+trafilatura = ["trafilatura>=2.0"]+mcp = ["mcp>=1.6"]+all = ["hyperresearch[crawl4ai,tavily,firecrawl,trafilatura,mcp]"]+dev = [+ "pytest>=7.4",+ "pytest-cov>=4.1",+ "ruff>=0.3",+ "mypy>=1.8",+]++[project.scripts]+hyperresearch = "hyperresearch.cli:app"+hpr = "hyperresearch.cli:app"++[project.urls]+Homepage = "https://github.com/jordan-gibbs/hyperresearch"+Repository = "https://github.com/jordan-gibbs/hyperresearch"+Issues = "https://github.com/jordan-gibbs/hyperresearch/issues"++[tool.hatch.build.targets.wheel]+packages = ["src/hyperresearch"]++[tool.ruff]+target-version = "py311"+line-length = 100+src = ["src"]++[tool.ruff.lint]+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]+ignore = [+ "E501",+ "B008",+ "B904",+ "E402",+ "N817",+]++[tool.mypy]+python_version = "3.11"+strict = true++[tool.pytest.ini_options]+testpaths = ["tests"]+addopts = "-ra -q --strict-markers"diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.pynew file mode 100644index 0000000..a2e70f5--- /dev/null+++ b/src/hyperresearch/__init__.py@@ -0,0 +1,3 @@+"""Hyperresearch — agent-driven research knowledge base."""++__version__ = "0.1.0"diff --git a/src/hyperresearch/__main__.py b/src/hyperresearch/__main__.pynew file mode 100644index 0000000..d357ec9--- /dev/null+++ b/src/hyperresearch/__main__.py@@ -0,0 +1,5 @@+"""Allow running as `python -m hyperresearch`."""++from hyperresearch.cli import app++app()diff --git a/src/hyperresearch/cli/__init__.py b/src/hyperresearch/cli/__init__.pynew file mode 100644index 0000000..e3aaa06--- /dev/null+++ b/src/hyperresearch/cli/__init__.py@@ -0,0 +1,79 @@+"""Hyperresearch CLI — main typer application."""++import typer++from hyperresearch import __version__+++def _version_callback(value: bool) -> None:+ if value:+ typer.echo(f"hyperresearch v{__version__}")+ raise typer.Exit()+++app = typer.Typer(+ name="hyperresearch",+ help="Agent-driven research knowledge base.",+ no_args_is_help=True,+ rich_markup_mode="rich",+)+++def main(+ version: bool = typer.Option(False, "--version", "-V", callback=_version_callback, is_eager=True, help="Show version"),+) -> None:+ pass+++# Root-level commands+from hyperresearch.cli.dedup import dedup as _dedup+from hyperresearch.cli.import_cmd import import_vault as _import+from hyperresearch.cli.main import init as _init+from hyperresearch.cli.main import status as _status+from hyperresearch.cli.main import sync as _sync+from hyperresearch.cli.mcp_cmd import mcp as _mcp+from hyperresearch.cli.note import note_show as _show+from hyperresearch.cli.repair import repair as _repair+from hyperresearch.cli.search import search as _search+from hyperresearch.cli.serve import serve as _serve+from hyperresearch.cli.tag import tag_list as _tags+from hyperresearch.cli.watch import watch as _watch++app.command("init")(_init)+app.command("status")(_status)+app.command("sync")(_sync)+app.command("search")(_search)+app.command("tags")(_tags)+app.command("show", hidden=True)(_show)+app.command("dedup")(_dedup)+app.command("import")(_import)+app.command("repair")(_repair)+app.command("watch")(_watch)+app.command("serve")(_serve)+app.command("mcp")(_mcp)++# Sub-apps+from hyperresearch.cli.batch import app as batch_app+from hyperresearch.cli.config_cmd import app as config_app+from hyperresearch.cli.export import app as export_app+from hyperresearch.cli.git_cmd import app as git_app+from hyperresearch.cli.graph import app as graph_app+from hyperresearch.cli.index import app as index_app+from hyperresearch.cli.lint import app as lint_app+from hyperresearch.cli.note import app as note_app+from hyperresearch.cli.tag import app as tag_app+from hyperresearch.cli.template import app as template_app+from hyperresearch.cli.topic import app as topic_app++app.add_typer(note_app, name="note", help="Note CRUD operations.")+app.add_typer(graph_app, name="graph", help="Knowledge graph and link analysis.")+app.add_typer(index_app, name="index", help="Auto-generated index pages.")+app.add_typer(lint_app, name="lint", help="Health-check the vault.")+app.add_typer(export_app, name="export", help="Export notes.")+app.add_typer(config_app, name="config", help="Configuration.")+app.add_typer(topic_app, name="topic", help="Topic hierarchy.")+app.add_typer(batch_app, name="batch", help="Bulk operations.")+app.add_typer(template_app, name="template", help="Note templates.")+app.add_typer(git_app, name="git", help="Git integration.")+app.add_typer(tag_app, name="tag", help="Tag management.")diff --git a/src/hyperresearch/cli/_output.py b/src/hyperresearch/cli/_output.pynew file mode 100644index 0000000..155d5c4--- /dev/null+++ b/src/hyperresearch/cli/_output.py@@ -0,0 +1,131 @@+"""Dual-mode output: rich terminal for humans, JSON for LLM agents."""++from __future__ import annotations++import json+from typing import Any++import typer+from rich.console import Console+from rich.table import Table+from rich.tree import Tree++from hyperresearch.models.output import Envelope++console = Console()+err_console = Console(stderr=True)+++def output(data: Any, *, json_mode: bool = False, **kwargs: Any) -> None:+ """Output data in either JSON or rich terminal format."""+ if json_mode:+ _output_json(data)+ else:+ _output_rich(data, **kwargs)+++def _output_json(data: Any) -> None:+ """Output as JSON. Uses sys.stdout with UTF-8 to avoid Windows encoding issues."""+ import sys++ if isinstance(data, Envelope) or hasattr(data, "model_dump_json"):+ text = data.model_dump_json(indent=2, exclude_none=True)+ else:+ text = json.dumps(data, indent=2, default=str)++ sys.stdout.buffer.write(text.encode("utf-8"))+ sys.stdout.buffer.write(b"\n")+ sys.stdout.buffer.flush()+++def _output_rich(data: Any, **kwargs: Any) -> None:+ """Output in rich terminal format."""+ if isinstance(data, Envelope):+ if not data.ok:+ err_console.print(f"[red bold]Error:[/] {data.error}")+ raise typer.Exit(1)+ _output_rich(data.data, **kwargs)+ return++ if isinstance(data, dict):+ _print_dict(data, **kwargs)+ elif isinstance(data, list):+ _print_list(data, **kwargs)+ elif isinstance(data, str):+ console.print(data)+ else:+ console.print(str(data))+++def _print_dict(data: dict, **kwargs: Any) -> None:+ """Pretty-print a dict."""+ for key, value in data.items():+ if isinstance(value, dict):+ console.print(f"[bold]{key}:[/]")+ _print_dict(value)+ elif isinstance(value, list) and value and isinstance(value[0], dict):+ console.print(f"\n[bold]{key}:[/]")+ _print_list(value)+ else:+ console.print(f" [dim]{key}:[/] {value}")+++def _print_list(data: list, **kwargs: Any) -> None:+ """Pretty-print a list of items, as a table if they're dicts."""+ if not data:+ console.print(" [dim](none)[/]")+ return++ if isinstance(data[0], dict):+ table = Table(show_header=True, header_style="bold")+ cols = list(data[0].keys())+ for col in cols:+ table.add_column(col)+ for item in data:+ table.add_row(*(str(item.get(c, "")) for c in cols))+ console.print(table)+ else:+ for item in data:+ console.print(f" - {item}")+++def print_note_summary(notes: list[dict], title: str = "Notes") -> None:+ """Print a table of notes."""+ table = Table(title=title, show_header=True, header_style="bold")+ table.add_column("ID", style="cyan", no_wrap=True)+ table.add_column("Title", style="white")+ table.add_column("Status", style="yellow")+ table.add_column("Tags", style="green")+ table.add_column("Words", justify="right", style="dim")+ for n in notes:+ tags = ", ".join(n.get("tags", []))+ table.add_row(+ n.get("id", ""),+ n.get("title", ""),+ n.get("status", ""),+ tags,+ str(n.get("word_count", "")),+ )+ console.print(table)+++def print_vault_status(data: dict) -> None:+ """Print vault status in a nice tree format."""+ tree = Tree(f"[bold]{data.get('vault_name', 'Vault')}[/]")+ notes = tree.add("[bold]Notes[/]")+ nd = data.get("notes", {})+ notes.add(f"Total: {nd.get('total', 0)}")+ for status, count in nd.get("by_status", {}).items():+ notes.add(f"{status}: {count}")++ tags = tree.add("[bold]Tags[/]")+ tags.add(f"Unique: {data.get('tags', {}).get('total_unique', 0)}")++ graph = tree.add("[bold]Graph[/]")+ gd = data.get("graph", {})+ graph.add(f"Links: {gd.get('total_links', 0)}")+ graph.add(f"Broken: {gd.get('broken_links', 0)}")+ graph.add(f"Orphans: {gd.get('orphan_notes', 0)}")++ tree.add(f"[dim]Words: {data.get('total_words', 0):,}[/]")+ console.print(tree)diff --git a/src/hyperresearch/cli/batch.py b/src/hyperresearch/cli/batch.pynew file mode 100644index 0000000..289443c--- /dev/null+++ b/src/hyperresearch/cli/batch.py@@ -0,0 +1,304 @@+"""Batch operations — modify multiple notes at once."""++from __future__ import annotations++from datetime import UTC, datetime+from pathlib import Path++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success++VALID_STATUSES = {"draft", "review", "evergreen", "stale", "deprecated", "archive"}+++def _discover_vault(json_output: bool):+ """Discover vault with proper error handling."""+ from hyperresearch.core.vault import Vault, VaultError+ try:+ return Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++app = typer.Typer()+++def _get_matching_notes(vault, status=None, tag=None, parent=None, note_type=None) -> list[dict]:+ """Find notes matching the given filters."""+ clauses = ["n.type NOT IN ('index')"]+ params: list = []++ if status:+ clauses.append("n.status = ?")+ params.append(status)+ if tag:+ clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")+ params.append(tag.lower())+ if parent:+ clauses.append("(n.parent = ? OR n.parent LIKE ?)")+ params.append(parent)+ params.append(parent + "/%")+ if note_type:+ clauses.append("n.type = ?")+ params.append(note_type)++ where = " AND ".join(clauses)+ rows = vault.db.execute(+ f"SELECT n.id, n.path, n.title FROM notes n WHERE {where} ORDER BY n.title",+ params,+ ).fetchall()+ return [dict(r) for r in rows]+++def _batch_update_files(vault, notes: list[dict], updates: dict) -> tuple[list[str], list[dict]]:+ """Update frontmatter on multiple files. Returns (modified_ids, errors)."""+ modified = []+ errors = []+ for n in notes:+ try:+ _update_file_frontmatter(vault.root, n["path"], updates)+ modified.append(n["id"])+ except Exception as e:+ errors.append({"id": n["id"], "path": n["path"], "error": str(e)})+ # Sync after all modifications+ if modified:+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)+ return modified, errors+++def _update_file_frontmatter(vault_root: Path, rel_path: str, updates: dict) -> None:+ """Read a note file, patch its frontmatter, write it back."""+ from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter++ file_path = vault_root / rel_path+ content = file_path.read_text(encoding="utf-8-sig")+ meta, body = parse_frontmatter(content)++ for key, value in updates.items():+ if key == "add_tag":+ if value.lower() not in meta.tags:+ meta.tags.append(value.lower())+ elif key == "remove_tag":+ meta.tags = [t for t in meta.tags if t != value.lower()]+ elif hasattr(meta, key):+ setattr(meta, key, value)++ meta.updated = datetime.now(UTC)+ new_content = serialize_frontmatter(meta) + "\n" + body+ file_path.write_text(new_content, encoding="utf-8")+++# --- Tag operations ---+[email protected]("tag-add")+def batch_tag_add(+ tag: str = typer.Argument(..., help="Tag to add"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ filter_tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by existing tag"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Add a tag to matching notes."""+ vault = _discover_vault(json_output)+ vault.auto_sync()+ notes = _get_matching_notes(vault, status=status, tag=filter_tag, parent=parent)++ if dry_run:+ data = {"action": "tag-add", "tag": tag, "would_modify": [n["id"] for n in notes]}+ if json_output:+ output(success(data, count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[bold]Would add tag '{tag}' to {len(notes)} notes:[/]")+ for n in notes:+ console.print(f" [cyan]{n['id']}[/] — {n['title']}")+ return++ for n in notes:+ _update_file_frontmatter(vault.root, n["path"], {"add_tag": tag})++ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)++ if json_output:+ output(success({"action": "tag-add", "tag": tag, "modified": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Added tag '{tag}' to {len(notes)} notes.[/]")++[email protected]("tag-remove")+def batch_tag_remove(+ tag: str = typer.Argument(..., help="Tag to remove"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ filter_tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by existing tag"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Remove a tag from matching notes."""+ vault = _discover_vault(json_output)+ vault.auto_sync()+ notes = _get_matching_notes(vault, status=status, tag=filter_tag or tag, parent=parent)++ if dry_run:+ data = {"action": "tag-remove", "tag": tag, "would_modify": [n["id"] for n in notes]}+ if json_output:+ output(success(data, count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[bold]Would remove tag '{tag}' from {len(notes)} notes:[/]")+ for n in notes:+ console.print(f" [cyan]{n['id']}[/] — {n['title']}")+ return++ for n in notes:+ _update_file_frontmatter(vault.root, n["path"], {"remove_tag": tag})++ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)++ if json_output:+ output(success({"action": "tag-remove", "tag": tag, "modified": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Removed tag '{tag}' from {len(notes)} notes.[/]")+++# --- Status operations ---+[email protected]("set-status")+def batch_set_status(+ new_status: str = typer.Argument(..., help="New status: draft|review|evergreen|stale|deprecated|archive"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by current status"),+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Set status on matching notes."""+ if new_status not in VALID_STATUSES:+ msg = f"Invalid status '{new_status}'. Valid: {', '.join(sorted(VALID_STATUSES))}"+ if json_output:+ output(error(msg, "INVALID_STATUS"), json_mode=True)+ else:+ console.print(f"[red]{msg}[/]")+ raise typer.Exit(1)++ vault = _discover_vault(json_output)+ vault.auto_sync()+ notes = _get_matching_notes(vault, status=status, tag=tag, parent=parent)++ if dry_run:+ if json_output:+ output(success({"action": "set-status", "status": new_status,+ "would_modify": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[bold]Would set status '{new_status}' on {len(notes)} notes.[/]")+ return++ for n in notes:+ _update_file_frontmatter(vault.root, n["path"], {"status": new_status})++ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)++ if json_output:+ output(success({"action": "set-status", "status": new_status,+ "modified": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Set status '{new_status}' on {len(notes)} notes.[/]")+++# --- Deprecate ---+[email protected]("deprecate")+def batch_deprecate(+ superseded_by: str | None = typer.Option(None, "--superseded-by", help="Note ID of replacement"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Mark matching notes as deprecated."""+ vault = _discover_vault(json_output)+ vault.auto_sync()+ notes = _get_matching_notes(vault, status=status, tag=tag, parent=parent)++ if dry_run:+ if json_output:+ output(success({"action": "deprecate", "superseded_by": superseded_by,+ "would_modify": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[bold]Would deprecate {len(notes)} notes.[/]")+ return++ updates = {"status": "deprecated", "deprecated": True}+ if superseded_by:+ updates["superseded_by"] = superseded_by++ for n in notes:+ _update_file_frontmatter(vault.root, n["path"], updates)++ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)++ if json_output:+ output(success({"action": "deprecate", "modified": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Deprecated {len(notes)} notes.[/]")+++# --- Parent ---+[email protected]("set-parent")+def batch_set_parent(+ new_parent: str = typer.Argument(..., help="New parent topic (e.g. ml/deep-learning)"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by current parent"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Set parent topic on matching notes."""+ vault = _discover_vault(json_output)+ vault.auto_sync()+ notes = _get_matching_notes(vault, status=status, tag=tag, parent=parent)++ if dry_run:+ if json_output:+ output(success({"action": "set-parent", "parent": new_parent,+ "would_modify": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[bold]Would set parent '{new_parent}' on {len(notes)} notes.[/]")+ return++ for n in notes:+ _update_file_frontmatter(vault.root, n["path"], {"parent": new_parent})++ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)++ if json_output:+ output(success({"action": "set-parent", "parent": new_parent,+ "modified": [n["id"] for n in notes]},+ count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Set parent '{new_parent}' on {len(notes)} notes.[/]")diff --git a/src/hyperresearch/cli/config_cmd.py b/src/hyperresearch/cli/config_cmd.pynew file mode 100644index 0000000..9d46653--- /dev/null+++ b/src/hyperresearch/cli/config_cmd.py@@ -0,0 +1,134 @@+"""Configuration CLI commands."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("show")+def config_show(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Display current vault configuration."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ config = vault.config++ data = {+ "vault_name": config.name,+ "vault_path": str(vault.root),+ "research_dir": config.research_dir,+ "auto_sync": config.auto_sync,+ "auto_build_index": config.auto_build_index,+ "search_boost_evergreen": config.search_boost_evergreen,+ "search_penalize_deprecated": config.search_penalize_deprecated,+ }++ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[bold]Vault Configuration[/]")+ for k, v in data.items():+ console.print(f" [dim]{k}:[/] {v}")++[email protected]("set")+def config_set(+ key: str = typer.Argument(..., help="Config key (dot notation: vault.name)"),+ value: str = typer.Argument(..., help="Config value"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Set a configuration value."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ config = vault.config++ # Map dot-notation keys to config attributes+ key_map = {+ "vault.name": "name",+ "vault.research_dir": "research_dir",+ "search.boost_evergreen": "search_boost_evergreen",+ "search.penalize_deprecated": "search_penalize_deprecated",+ "sync.auto_sync": "auto_sync",+ "index.auto_build": "auto_build_index",+ }++ attr = key_map.get(key)+ if not attr:+ console.print(f"[red]Unknown config key:[/] {key}")+ console.print(f"[dim]Valid keys: {', '.join(key_map.keys())}[/]")+ raise typer.Exit(1)++ # Type coercion+ if attr in ("auto_sync", "auto_build_index"):+ value = value.lower() in ("true", "1", "yes")++ setattr(config, attr, value)+ config.save(vault.config_path)++ if json_output:+ output(success({"key": key, "value": value}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Set[/] {key} = {value}")++[email protected]("get")+def config_get(+ key: str = typer.Argument(..., help="Config key"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Get a configuration value."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ config = vault.config++ key_map = {+ "vault.name": "name",+ "vault.research_dir": "research_dir",+ "search.boost_evergreen": "search_boost_evergreen",+ "search.penalize_deprecated": "search_penalize_deprecated",+ "sync.auto_sync": "auto_sync",+ "index.auto_build": "auto_build_index",+ }++ attr = key_map.get(key)+ if not attr:+ console.print(f"[red]Unknown config key:[/] {key}")+ raise typer.Exit(1)++ value = getattr(config, attr)++ if json_output:+ output(success({"key": key, "value": value}, vault=str(vault.root)), json_mode=True)+ else:+ typer.echo(value)++[email protected]("agent-docs")+def config_agent_docs(+ agents: list[str] = typer.Option(["claude"], "--agents", "-a", help="Which files: claude|agents|gemini|copilot"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Update agent config files (CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md)."""+ from hyperresearch.core.agent_docs import inject_agent_docs+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ modified = inject_agent_docs(vault.root, agents=agents)++ if json_output:+ output(success({"modified": modified}, vault=str(vault.root)), json_mode=True)+ else:+ if modified:+ for m in modified:+ console.print(f" [green]{m}[/]")+ else:+ console.print("[dim]Agent docs already up to date.[/]")diff --git a/src/hyperresearch/cli/dedup.py b/src/hyperresearch/cli/dedup.pynew file mode 100644index 0000000..e961dc7--- /dev/null+++ b/src/hyperresearch/cli/dedup.py@@ -0,0 +1,93 @@+"""Content deduplication — find near-duplicate notes."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.core.similarity import jaccard, shingle+from hyperresearch.models.output import success+++def dedup(+ threshold: float = typer.Option(0.6, "--threshold", "-t", help="Similarity threshold (0.0-1.0)"),+ limit: int = typer.Option(20, "--limit", "-l", help="Max pairs to show"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Find near-duplicate notes by content similarity."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output({"ok": False, "error": str(e)}, json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ vault.auto_sync()++ # Load all note content+ rows = vault.db.execute(+ "SELECT n.id, n.title, n.word_count, nc.body_plain "+ "FROM notes n JOIN note_content nc ON n.id = nc.note_id "+ "WHERE n.type NOT IN ('index') AND n.word_count > 20 "+ "ORDER BY n.id"+ ).fetchall()++ if len(rows) < 2:+ if json_output:+ output(success({"pairs": [], "total_compared": 0}, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[dim]Not enough notes to compare.[/]")+ return++ # Build shingle sets+ notes = []+ for row in rows:+ shingles = shingle(row["body_plain"])+ notes.append({+ "id": row["id"],+ "title": row["title"],+ "word_count": row["word_count"],+ "shingles": shingles,+ })++ # Compare all pairs+ pairs = []+ for i in range(len(notes)):+ for j in range(i + 1, len(notes)):+ sim = jaccard(notes[i]["shingles"], notes[j]["shingles"])+ if sim >= threshold:+ pairs.append({+ "similarity": round(sim, 3),+ "note_a": {"id": notes[i]["id"], "title": notes[i]["title"], "words": notes[i]["word_count"]},+ "note_b": {"id": notes[j]["id"], "title": notes[j]["title"], "words": notes[j]["word_count"]},+ })++ pairs.sort(key=lambda p: p["similarity"], reverse=True)+ pairs = pairs[:limit]++ total_compared = len(notes) * (len(notes) - 1) // 2++ if json_output:+ output(+ success({"pairs": pairs, "total_compared": total_compared, "threshold": threshold},+ count=len(pairs), vault=str(vault.root)),+ json_mode=True,+ )+ else:+ if not pairs:+ console.print(f"[green]No duplicates found (threshold {threshold:.0%}, compared {total_compared} pairs).[/]")+ return++ console.print(f"[bold]Similar notes (>{threshold:.0%}):[/]\n")+ for p in pairs:+ a, b = p["note_a"], p["note_b"]+ console.print(+ f" [bold]{p['similarity']:.0%}[/] | "+ f"[cyan]{a['id']}[/] ({a['words']}w) "+ f"<-> [cyan]{b['id']}[/] ({b['words']}w)"+ )+ console.print(f"\n[dim]Compared {total_compared} pairs.[/]")diff --git a/src/hyperresearch/cli/export.py b/src/hyperresearch/cli/export.pynew file mode 100644index 0000000..0c7b427--- /dev/null+++ b/src/hyperresearch/cli/export.py@@ -0,0 +1,117 @@+"""Export CLI commands."""++from __future__ import annotations++import json+from pathlib import Path++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("json")+def export_json(+ output_path: str | None = typer.Option(None, "--output", "-o", help="Output file path"),+ pretty: bool = typer.Option(True, "--pretty/--compact", help="Pretty print"),+ json_output: bool = typer.Option(False, "--json", help="JSON output for status"),+) -> None:+ """Export all notes as structured JSON."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ notes = []+ for row in vault.db.execute(+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id ORDER BY n.title"+ ):+ tags = [r["tag"] for r in vault.db.execute("SELECT tag FROM tags WHERE note_id = ?", (row["id"],))]+ notes.append({+ "id": row["id"],+ "title": row["title"],+ "path": row["path"],+ "status": row["status"],+ "type": row["type"],+ "tags": tags,+ "created": row["created"],+ "updated": row["updated"],+ "word_count": row["word_count"],+ "source": row["source"],+ "parent": row["parent"],+ "summary": row["summary"],+ "body": row["body"],+ })++ out = Path(output_path) if output_path else vault.exports_dir / "vault.json"+ out.parent.mkdir(parents=True, exist_ok=True)+ indent = 2 if pretty else None+ out.write_text(json.dumps(notes, indent=indent, default=str), encoding="utf-8")++ if json_output:+ output(success({"path": str(out), "count": len(notes)}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Exported {len(notes)} notes to:[/] {out}")++[email protected]("vault")+def export_vault(+ output_path: str = typer.Argument(..., help="Output directory"),+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would be exported"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Export a subset of notes to another directory."""+ import shutil++ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ clauses = ["n.type NOT IN ('index')"]+ params: list = []+ if tag:+ clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")+ params.append(tag.lower())+ if status:+ clauses.append("n.status = ?")+ params.append(status)+ if parent:+ clauses.append("(n.parent = ? OR n.parent LIKE ?)")+ params.append(parent)+ params.append(parent + "/%")++ where = " AND ".join(clauses)+ rows = vault.db.execute(f"SELECT id, path, title FROM notes n WHERE {where}", params).fetchall()++ out_dir = Path(output_path).resolve()+ exported = []+ for row in rows:+ src = vault.root / row["path"]+ if not src.exists():+ continue+ dest = out_dir / row["path"]+ exported.append({"id": row["id"], "path": row["path"]})+ if not dry_run:+ dest.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(src, dest)++ if json_output:+ action = "would_export" if dry_run else "exported"+ output(success({action: exported, "count": len(exported), "output_path": str(out_dir)},+ count=len(exported), vault=str(vault.root)), json_mode=True)+ else:+ verb = "Would export" if dry_run else "Exported"+ console.print(f"[green]{verb} {len(exported)} notes to:[/] {out_dir}")+ for item in exported[:20]:+ console.print(f" {item['path']}")+ if len(exported) > 20:+ console.print(f" [dim]...and {len(exported) - 20} more[/]")++diff --git a/src/hyperresearch/cli/git_cmd.py b/src/hyperresearch/cli/git_cmd.pynew file mode 100644index 0000000..e8799fd--- /dev/null+++ b/src/hyperresearch/cli/git_cmd.py@@ -0,0 +1,161 @@+"""Git integration — changelog, blame, changed files."""++from __future__ import annotations++import subprocess+from pathlib import Path++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success++app = typer.Typer()+++def _run_git(vault_root: Path, args: list[str]) -> tuple[int, str]:+ """Run a git command and return (returncode, stdout)."""+ result = subprocess.run(+ ["git", *args],+ capture_output=True,+ text=True,+ cwd=str(vault_root),+ )+ return result.returncode, result.stdout++[email protected]("log")+def git_log(+ limit: int = typer.Option(20, "--limit", "-l", help="Max commits"),+ since: str | None = typer.Option(None, "--since", help="Since date (YYYY-MM-DD)"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show notes changed in recent commits."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ # Use \x00 as delimiter to avoid pipe characters in commit messages+ args = ["log", f"--max-count={limit}", "--name-only", "--pretty=format:%H%x00%s%x00%ai"]+ if since:+ args.append(f"--since={since}")+ args.append("-- *.md")++ rc, out = _run_git(vault.root, args)+ if rc != 0:+ if json_output:+ output(error("Not a git repository", "NOT_GIT"), json_mode=True)+ else:+ console.print("[red]Not a git repository.[/]")+ raise typer.Exit(1)++ # Parse git log output+ commits = []+ current_commit = None+ for line in out.strip().split("\n"):+ if not line:+ continue+ if "\x00" in line and len(line.split("\x00")) >= 3:+ parts = line.split("\x00", 2)+ current_commit = {+ "hash": parts[0][:8],+ "message": parts[1],+ "date": parts[2].strip()[:10],+ "files": [],+ }+ commits.append(current_commit)+ elif current_commit and line.endswith(".md"):+ current_commit["files"].append(line.strip())++ if json_output:+ output(success(commits, count=len(commits), vault=str(vault.root)), json_mode=True)+ else:+ if not commits:+ console.print("[dim]No commits found with .md changes.[/]")+ return+ for c in commits:+ console.print(f"[dim]{c['date']}[/] [bold]{c['hash']}[/] {c['message']}")+ for f in c["files"]:+ console.print(f" [cyan]{f}[/]")++[email protected]("blame")+def git_blame(+ note_id: str = typer.Argument(..., help="Note ID"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show git blame for a note file."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()+ if not row:+ if json_output:+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]Not found:[/] {note_id}")+ raise typer.Exit(1)++ rc, out = _run_git(vault.root, ["blame", "--porcelain", row["path"]])+ if rc != 0:+ if json_output:+ output(error("Git blame failed", "GIT_ERROR"), json_mode=True)+ else:+ console.print("[red]Git blame failed.[/]")+ raise typer.Exit(1)++ if json_output:+ output(success({"note_id": note_id, "path": row["path"], "blame": out}, vault=str(vault.root)), json_mode=True)+ else:+ # Simplified blame output+ _rc2, simple = _run_git(vault.root, ["blame", "--date=short", row["path"]])+ console.print(simple)++[email protected]("changed")+def git_changed(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show notes with uncommitted changes."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()++ rc, out = _run_git(vault.root, ["status", "--porcelain"])+ if rc != 0:+ if json_output:+ output(error("Not a git repository", "NOT_GIT"), json_mode=True)+ else:+ console.print("[red]Not a git repository.[/]")+ raise typer.Exit(1)++ changes = []+ for line in out.strip().split("\n"):+ if not line:+ continue+ status_code = line[:2].strip()+ file_path = line[3:].strip()+ if file_path.endswith(".md"):+ change_type = {"M": "modified", "A": "added", "D": "deleted", "?": "untracked"}.get(+ status_code, status_code+ )+ changes.append({"status": change_type, "path": file_path})++ if json_output:+ output(success(changes, count=len(changes), vault=str(vault.root)), json_mode=True)+ else:+ if not changes:+ console.print("[green]No uncommitted changes to .md files.[/]")+ return+ for c in changes:+ style = {"modified": "yellow", "added": "green", "deleted": "red", "untracked": "dim"}.get(c["status"], "")+ console.print(f" [{style}]{c['status']:10s}[/] {c['path']}")diff --git a/src/hyperresearch/cli/graph.py b/src/hyperresearch/cli/graph.pynew file mode 100644index 0000000..9a01d86--- /dev/null+++ b/src/hyperresearch/cli/graph.py@@ -0,0 +1,286 @@+"""Knowledge graph CLI commands."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("backlinks")+def graph_backlinks(+ note_id: str = typer.Argument(..., help="Note ID"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show what links TO this note."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ """+ SELECT l.source_id, n.title as source_title, n.path as source_path,+ l.line_number, l.context+ FROM links l+ JOIN notes n ON l.source_id = n.id+ WHERE l.target_id = ?+ ORDER BY n.title+ """,+ (note_id,),+ ).fetchall()++ backlinks = [+ {+ "source_id": r["source_id"],+ "source_title": r["source_title"],+ "source_path": r["source_path"],+ "line_number": r["line_number"],+ "context": r["context"],+ }+ for r in rows+ ]++ if json_output:+ output(+ success({"note_id": note_id, "backlinks": backlinks}, count=len(backlinks), vault=str(vault.root)),+ json_mode=True,+ )+ else:+ if not backlinks:+ console.print(f"[dim]No backlinks to {note_id}[/]")+ return+ console.print(f"[bold]Backlinks to {note_id}:[/]")+ for bl in backlinks:+ console.print(+ f" [cyan]{bl['source_id']}[/] — {bl['source_title']} "+ f"[dim](line {bl['line_number']})[/]"+ )++[email protected]("outlinks")+def graph_outlinks(+ note_id: str = typer.Argument(..., help="Note ID"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show what this note links TO."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ """+ SELECT l.target_ref, l.target_id, n.title as target_title,+ l.line_number, l.context+ FROM links l+ LEFT JOIN notes n ON l.target_id = n.id+ WHERE l.source_id = ?+ ORDER BY l.line_number+ """,+ (note_id,),+ ).fetchall()++ outlinks = [+ {+ "target_ref": r["target_ref"],+ "target_id": r["target_id"],+ "target_title": r["target_title"],+ "line_number": r["line_number"],+ "resolved": r["target_id"] is not None,+ }+ for r in rows+ ]++ if json_output:+ output(+ success({"note_id": note_id, "outlinks": outlinks}, count=len(outlinks), vault=str(vault.root)),+ json_mode=True,+ )+ else:+ if not outlinks:+ console.print(f"[dim]No outgoing links from {note_id}[/]")+ return+ console.print(f"[bold]Links from {note_id}:[/]")+ for ol in outlinks:+ status = "[green]OK[/]" if ol["resolved"] else "[red]BROKEN[/]"+ title = ol.get("target_title") or ol["target_ref"]+ console.print(f" {status} [[{ol['target_ref']}]] → {title}")++[email protected]("orphans")+def graph_orphans(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Find notes with no inbound or outbound links."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute("""+ SELECT n.id, n.title, n.path, n.status+ FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ ORDER BY n.title+ """).fetchall()++ orphans = [{"id": r["id"], "title": r["title"], "path": r["path"], "status": r["status"]} for r in rows]++ if json_output:+ output(success(orphans, count=len(orphans), vault=str(vault.root)), json_mode=True)+ else:+ if not orphans:+ console.print("[green]No orphan notes.[/]")+ return+ console.print(f"[bold]Orphan notes ({len(orphans)}):[/]")+ for o in orphans:+ console.print(f" [cyan]{o['id']}[/] — {o['title']}")++[email protected]("broken")+def graph_broken(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Find broken [[links]] that don't resolve."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute("""+ SELECT l.source_id, n.title as source_title, l.target_ref, l.line_number+ FROM links l+ JOIN notes n ON l.source_id = n.id+ WHERE l.target_id IS NULL+ ORDER BY n.title, l.line_number+ """).fetchall()++ broken = [+ {+ "source_id": r["source_id"],+ "source_title": r["source_title"],+ "target_ref": r["target_ref"],+ "line_number": r["line_number"],+ }+ for r in rows+ ]++ if json_output:+ output(success(broken, count=len(broken), vault=str(vault.root)), json_mode=True)+ else:+ if not broken:+ console.print("[green]No broken links.[/]")+ return+ console.print(f"[bold red]Broken links ({len(broken)}):[/]")+ for b in broken:+ console.print(+ f" [cyan]{b['source_id']}[/] line {b['line_number']}: "+ f"[[{b['target_ref']}]]"+ )++[email protected]("stub")+def graph_stub(+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would be created"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Create stub notes for all broken [[links]]."""+ from hyperresearch.core.note import write_note+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ "SELECT DISTINCT l.target_ref FROM links l WHERE l.target_id IS NULL ORDER BY l.target_ref"+ ).fetchall()++ targets = [r["target_ref"] for r in rows]++ if not targets:+ if json_output:+ output(success({"stubbed": [], "count": 0}, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[green]No broken links to stub.[/]")+ return++ if dry_run:+ if json_output:+ output(success({"would_stub": targets, "count": len(targets)}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[bold]Would create {len(targets)} stub notes:[/]")+ for t in targets:+ console.print(f" [cyan]{t}[/]")+ return++ created = []+ for target in targets:+ # Create a minimal stub note+ title = target.replace("-", " ").replace("_", " ").title()+ path = write_note(+ vault.notes_dir,+ title,+ body=f"# {title}\n\n*Stub — created to resolve a broken link. Expand this note.*\n",+ note_id=target,+ status="draft",+ summary=f"Stub for [[{target}]]",+ )+ created.append({"id": target, "title": title, "path": path.relative_to(vault.root).as_posix()})++ # Sync to resolve the links+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)++ if json_output:+ output(success({"stubbed": created, "count": len(created)}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Created {len(created)} stub notes:[/]")+ for c in created:+ console.print(f" [cyan]{c['id']}[/] — {c['title']}")++[email protected]("hubs")+def graph_hubs(+ limit: int = typer.Option(20, "--limit", "-l", help="Max results"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show most-linked-to notes."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ """+ SELECT l.target_id, n.title, COUNT(*) as inbound+ FROM links l+ JOIN notes n ON l.target_id = n.id+ WHERE l.target_id IS NOT NULL+ GROUP BY l.target_id+ ORDER BY inbound DESC+ LIMIT ?+ """,+ (limit,),+ ).fetchall()++ hubs = [{"id": r["target_id"], "title": r["title"], "inbound_links": r["inbound"]} for r in rows]++ if json_output:+ output(success(hubs, count=len(hubs), vault=str(vault.root)), json_mode=True)+ else:+ from rich.table import Table++ table = Table(title="Hub Notes", show_header=True, header_style="bold")+ table.add_column("ID", style="cyan")+ table.add_column("Title")+ table.add_column("Inbound Links", justify="right", style="green")+ for h in hubs:+ table.add_row(h["id"], h["title"], str(h["inbound_links"]))+ console.print(table)diff --git a/src/hyperresearch/cli/import_cmd.py b/src/hyperresearch/cli/import_cmd.pynew file mode 100644index 0000000..59a5334--- /dev/null+++ b/src/hyperresearch/cli/import_cmd.py@@ -0,0 +1,85 @@+"""Import notes from another vault or directory."""++from __future__ import annotations++import shutil+from pathlib import Path++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success+++def import_vault(+ source: str = typer.Argument(..., help="Source directory to import from"),+ prefix: str = typer.Option("", "--prefix", "-p", help="Path prefix for imported notes (e.g. imported/ml)"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would be imported"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Import markdown notes from another directory into this vault."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ source_path = Path(source).resolve()+ if not source_path.is_dir():+ msg = f"Source directory not found: {source}"+ if json_output:+ output(error(msg, "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]{msg}[/]")+ raise typer.Exit(1)++ # Find all .md files in source+ md_files = sorted(source_path.rglob("*.md"))+ # Skip .hyperresearch/, templates/ etc. from source+ skip_dirs = {".hyperresearch", ".git", ".venv", "node_modules", "templates"}+ md_files = [+ f for f in md_files+ if not any(part in skip_dirs for part in f.relative_to(source_path).parts)+ ]++ if not md_files:+ if json_output:+ output(success({"imported": [], "count": 0}, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[dim]No markdown files found in source.[/]")+ return++ imported = []+ for src_file in md_files:+ rel = src_file.relative_to(source_path).as_posix()+ dest_rel = f"{prefix}/{rel}" if prefix else rel+ # Write into research/notes/, not vault root+ dest = vault.notes_dir / dest_rel++ imported.append({"source": rel, "destination": dest_rel})++ if not dry_run:+ dest.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(src_file, dest)++ if not dry_run:+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)++ if json_output:+ action = "would_import" if dry_run else "imported"+ output(success({action: imported, "count": len(imported)}, count=len(imported),+ vault=str(vault.root)), json_mode=True)+ else:+ verb = "Would import" if dry_run else "Imported"+ console.print(f"[green]{verb} {len(imported)} files:[/]")+ for item in imported[:20]:+ console.print(f" {item['source']} -> {item['destination']}")+ if len(imported) > 20:+ console.print(f" [dim]...and {len(imported) - 20} more[/]")diff --git a/src/hyperresearch/cli/index.py b/src/hyperresearch/cli/index.pynew file mode 100644index 0000000..be68aa2--- /dev/null+++ b/src/hyperresearch/cli/index.py@@ -0,0 +1,77 @@+"""Index generation CLI commands."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("build")+def index_build(+ force: bool = typer.Option(False, "--force", "-f", help="Rebuild all indexes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Regenerate all index pages."""+ from hyperresearch.core.vault import Vault+ from hyperresearch.indexgen.generator import IndexGenerator++ vault = Vault.discover()+ vault.auto_sync()+ gen = IndexGenerator(vault)+ built = gen.build_all()++ if json_output:+ output(success({"built": built}, count=len(built), vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Built {len(built)} index pages:[/]")+ for p in built:+ console.print(f" {p}")++[email protected]("list")+def index_list(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show which index pages exist."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ index_dir = vault.index_dir+ pages = sorted(p.name for p in index_dir.glob("*.md")) if index_dir.exists() else []++ if json_output:+ output(success(pages, count=len(pages), vault=str(vault.root)), json_mode=True)+ else:+ if not pages:+ console.print("[dim]No index pages. Run 'hyperresearch index build'.[/]")+ return+ for p in pages:+ console.print(f" [cyan]{p}[/]")++[email protected]("show")+def index_show(+ name: str = typer.Argument(..., help="Index page name (e.g. _tags)"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Display a specific index page."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ fname = name if name.endswith(".md") else f"{name}.md"+ path = vault.index_dir / fname+ if not path.exists():+ console.print(f"[red]Index page not found:[/] {fname}")+ raise typer.Exit(1)++ content = path.read_text(encoding="utf-8")+ if json_output:+ output(success({"name": name, "content": content}, vault=str(vault.root)), json_mode=True)+ else:+ from rich.markdown import Markdown++ console.print(Markdown(content))diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.pynew file mode 100644index 0000000..d7a6404--- /dev/null+++ b/src/hyperresearch/cli/lint.py@@ -0,0 +1,240 @@+"""Lint / health-check CLI commands."""++from __future__ import annotations++from datetime import UTC++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer(invoke_without_command=True)++RULES = {+ "missing-title": "Notes without a title",+ "missing-tags": "Notes without any tags",+ "missing-summary": "Notes without a summary",+ "singleton-tags": "Tags used by only one note",+ "broken-links": "Wiki-links that don't resolve",+ "orphaned-notes": "Notes with no inbound or outbound links",+ "duplicate-ids": "Multiple notes with the same ID",+ "empty-notes": "Notes with no body content",+ "stale-indexes": "Index pages that need rebuilding",+ "expired-notes": "Notes past their expiry date",+ "deprecated-no-successor": "Deprecated notes without a superseded_by link",+ "stale-reviews": "Notes not reviewed in over 90 days",+ "low-confidence": "Notes with confidence < 0.5",+}++[email protected](invoke_without_command=True)+def lint(+ ctx: typer.Context,+ fix: bool = typer.Option(False, "--fix", help="Auto-fix what's possible"),+ rule: str | None = typer.Option(None, "--rule", "-r", help="Run specific rule only"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Health-check the vault."""+ if ctx.invoked_subcommand is not None:+ return++ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()+ conn = vault.db++ issues: list[dict] = []++ rules_to_run = [rule] if rule else list(RULES.keys())++ if "missing-title" in rules_to_run:+ for row in conn.execute("SELECT id, path FROM notes WHERE title = '' OR title = 'Untitled'"):+ issues.append({+ "rule": "missing-title",+ "severity": "warning",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": "Note has no meaningful title.",+ })++ if "missing-tags" in rules_to_run:+ for row in conn.execute(+ "SELECT n.id, n.path FROM notes n "+ "WHERE n.type NOT IN ('index','raw') "+ "AND n.id NOT IN (SELECT DISTINCT note_id FROM tags)"+ ):+ issues.append({+ "rule": "missing-tags",+ "severity": "warning",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": "Note has no tags.",+ })++ if "missing-summary" in rules_to_run:+ for row in conn.execute(+ "SELECT n.id, n.path FROM notes n "+ "WHERE n.type NOT IN ('index','raw') "+ "AND (n.summary IS NULL OR LENGTH(TRIM(n.summary)) = 0)"+ ):+ issues.append({+ "rule": "missing-summary",+ "severity": "warning",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": "Note has no summary. Add one for better search and listings.",+ })++ if "singleton-tags" in rules_to_run:+ for row in conn.execute(+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag HAVING c = 1"+ ):+ issues.append({+ "rule": "singleton-tags",+ "severity": "info",+ "note_id": row["tag"],+ "message": f"Tag '{row['tag']}' is used by only 1 note. Consider merging.",+ })++ if "broken-links" in rules_to_run:+ for row in conn.execute(+ "SELECT l.source_id, n.path, l.target_ref, l.line_number "+ "FROM links l JOIN notes n ON l.source_id = n.id "+ "WHERE l.target_id IS NULL"+ ):+ issues.append({+ "rule": "broken-links",+ "severity": "warning",+ "note_id": row["source_id"],+ "note_path": row["path"],+ "line": row["line_number"],+ "message": f"Broken link: [[{row['target_ref']}]]",+ })++ if "orphaned-notes" in rules_to_run:+ for row in conn.execute("""+ SELECT n.id, n.path FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ """):+ issues.append({+ "rule": "orphaned-notes",+ "severity": "info",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": "Note is orphaned (no links in or out).",+ })++ if "duplicate-ids" in rules_to_run:+ for row in conn.execute(+ "SELECT id, COUNT(*) as c FROM notes GROUP BY id HAVING c > 1"+ ):+ issues.append({+ "rule": "duplicate-ids",+ "severity": "error",+ "note_id": row["id"],+ "message": f"Duplicate ID found {row['c']} times.",+ })++ if "empty-notes" in rules_to_run:+ for row in conn.execute(+ "SELECT n.id, n.path FROM notes n "+ "JOIN note_content nc ON n.id = nc.note_id "+ "WHERE LENGTH(TRIM(nc.body)) < 10 AND n.type NOT IN ('index')"+ ):+ issues.append({+ "rule": "empty-notes",+ "severity": "info",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": "Note has little or no content.",+ })++ if "expired-notes" in rules_to_run:+ from datetime import datetime+ now_iso = datetime.now(UTC).isoformat()+ for row in conn.execute(+ "SELECT id, path, expires FROM notes WHERE expires IS NOT NULL AND expires < ?",+ (now_iso,),+ ):+ issues.append({+ "rule": "expired-notes",+ "severity": "warning",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": f"Note expired on {row['expires']}. Review or update.",+ })++ if "deprecated-no-successor" in rules_to_run:+ for row in conn.execute(+ "SELECT id, path FROM notes "+ "WHERE (deprecated = 1 OR status = 'deprecated') AND superseded_by IS NULL"+ ):+ issues.append({+ "rule": "deprecated-no-successor",+ "severity": "warning",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": "Deprecated but no superseded_by link. What replaces this?",+ })++ if "stale-reviews" in rules_to_run:+ from datetime import datetime, timedelta+ cutoff = (datetime.now(UTC) - timedelta(days=90)).isoformat()+ for row in conn.execute(+ "SELECT id, path, reviewed FROM notes "+ "WHERE reviewed IS NOT NULL AND reviewed < ? AND status = 'evergreen'",+ (cutoff,),+ ):+ issues.append({+ "rule": "stale-reviews",+ "severity": "info",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": f"Last reviewed {row['reviewed'][:10]}. Consider re-reviewing.",+ })++ if "low-confidence" in rules_to_run:+ for row in conn.execute(+ "SELECT id, path, confidence FROM notes "+ "WHERE confidence IS NOT NULL AND confidence < 0.5 AND status != 'deprecated'"+ ):+ issues.append({+ "rule": "low-confidence",+ "severity": "info",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": f"Low confidence ({row['confidence']:.1%}). Verify or flag.",+ })++ summary = {+ "errors": sum(1 for i in issues if i.get("severity") == "error"),+ "warnings": sum(1 for i in issues if i.get("severity") == "warning"),+ "info": sum(1 for i in issues if i.get("severity") == "info"),+ "total": len(issues),+ }++ if json_output:+ output(+ success({"issues": issues, "summary": summary}, count=len(issues), vault=str(vault.root)),+ json_mode=True,+ )+ else:+ if not issues:+ console.print("[green]Vault is healthy. No issues found.[/]")+ return++ severity_style = {"error": "red bold", "warning": "yellow", "info": "dim"}+ for issue in issues:+ style = severity_style.get(issue.get("severity", "info"), "dim")+ loc = issue.get("note_path", issue.get("note_id", ""))+ line = f" line {issue['line']}" if issue.get("line") else ""+ console.print(f" [{style}]{issue['rule']}[/] {loc}{line}: {issue['message']}")++ console.print(+ f"\n[bold]Summary:[/] {summary['errors']} errors, "+ f"{summary['warnings']} warnings, {summary['info']} info"+ )diff --git a/src/hyperresearch/cli/main.py b/src/hyperresearch/cli/main.pynew file mode 100644index 0000000..e3f514e--- /dev/null+++ b/src/hyperresearch/cli/main.py@@ -0,0 +1,170 @@+"""Root-level commands: init, status, sync."""++from __future__ import annotations++from pathlib import Path++import typer++from hyperresearch.cli._output import console, output, print_vault_status+from hyperresearch.models.output import error, success++app = typer.Typer()+++def init(+ path: str = typer.Argument(".", help="Path to initialize vault in"),+ name: str = typer.Option("Research Base", "--name", "-n", help="Vault name"),+ research_dir: str = typer.Option("research", "--dir", "-d", help="Research directory name"),+ agents: list[str] = typer.Option(["claude"], "--agents", "-a", help="Agent config files: claude|agents|gemini|copilot"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Initialize a new hyperresearch vault."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.init(Path(path).resolve(), name=name, research_dir=research_dir, agents=agents)+ data = {"vault_path": str(vault.root), "name": name}+ if json_output:+ output(success(data), json_mode=True)+ else:+ console.print(f"[green]Initialized vault:[/] {vault.root}")+ except VaultError as e:+ if json_output:+ output(error(str(e), "VAULT_EXISTS"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)+++def status(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show vault health and statistics."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ vault.auto_sync()+ conn = vault.db++ # Gather stats+ total = conn.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]+ by_status = {}+ for row in conn.execute("SELECT status, COUNT(*) as c FROM notes GROUP BY status"):+ by_status[row["status"]] = row["c"]+ by_type = {}+ for row in conn.execute("SELECT type, COUNT(*) as c FROM notes GROUP BY type"):+ by_type[row["type"]] = row["c"]++ tag_count = conn.execute("SELECT COUNT(DISTINCT tag) as c FROM tags").fetchone()["c"]+ top_tags = []+ for row in conn.execute(+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC LIMIT 10"+ ):+ top_tags.append({"tag": row["tag"], "count": row["c"]})++ total_links = conn.execute("SELECT COUNT(*) as c FROM links").fetchone()["c"]+ broken = conn.execute(+ "SELECT COUNT(*) as c FROM links WHERE target_id IS NULL"+ ).fetchone()["c"]+ orphans = conn.execute("""+ SELECT COUNT(*) as c FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ """).fetchone()["c"]++ total_words = conn.execute(+ "SELECT COALESCE(SUM(word_count), 0) as c FROM notes"+ ).fetchone()["c"]++ last_sync = conn.execute(+ "SELECT value FROM _meta WHERE key = 'last_sync'"+ ).fetchone()+ last_sync_val = last_sync["value"] if last_sync else "never"++ data = {+ "vault_name": vault.config.name,+ "vault_path": str(vault.root),+ "notes": {"total": total, "by_status": by_status, "by_type": by_type},+ "tags": {"total_unique": tag_count, "top": top_tags},+ "graph": {"total_links": total_links, "broken_links": broken, "orphan_notes": orphans},+ "total_words": total_words,+ "last_sync": last_sync_val,+ }++ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ print_vault_status(data)+++def sync(+ force: bool = typer.Option(False, "--force", "-f", help="Full rescan ignoring mtime/hash"),+ dry_run: bool = typer.Option(False, "--dry-run", help="Show what would change"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Sync database with markdown files on disk."""+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ plan = compute_sync_plan(vault, force=force)++ if dry_run:+ data = {+ "to_add": [str(p.relative_to(vault.root)) for p in plan.to_add],+ "to_update": [str(p.relative_to(vault.root)) for p in plan.to_update],+ "to_delete": plan.to_delete,+ "unchanged": plan.unchanged,+ }+ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[bold]Sync plan:[/]")+ console.print(f" Add: {len(plan.to_add)}")+ console.print(f" Update: {len(plan.to_update)}")+ console.print(f" Delete: {len(plan.to_delete)}")+ console.print(f" Unchanged: {plan.unchanged}")+ return++ result = execute_sync(vault, plan)+ data = {+ "added": result.added,+ "updated": result.updated,+ "deleted": result.deleted,+ "unchanged": result.unchanged,+ "errors": result.errors,+ "duration_ms": round(result.duration_ms, 1),+ }++ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print(+ f"[green]Synced:[/] +{result.added} ~{result.updated} "+ f"-{result.deleted} ={result.unchanged} "+ f"({result.duration_ms:.0f}ms)"+ )+ if result.errors:+ for err in result.errors:+ console.print(f" [red]Error:[/] {err['path']}: {err['error']}")diff --git a/src/hyperresearch/cli/mcp_cmd.py b/src/hyperresearch/cli/mcp_cmd.pynew file mode 100644index 0000000..8a8d25c--- /dev/null+++ b/src/hyperresearch/cli/mcp_cmd.py@@ -0,0 +1,19 @@+"""MCP server command — start the hyperresearch MCP server for agent integration."""++from __future__ import annotations++import sys+++def mcp() -> None:+ """Start the MCP server (stdio transport) for Claude Desktop, Cursor, etc.++ Requires: pip install hyperresearch[mcp]+ """+ try:+ from hyperresearch.mcp.server import server+ except ImportError:+ print("MCP server requires: pip install hyperresearch[mcp]", file=sys.stderr)+ sys.exit(1)++ server.run()diff --git a/src/hyperresearch/cli/note.py b/src/hyperresearch/cli/note.pynew file mode 100644index 0000000..8e4aa40--- /dev/null+++ b/src/hyperresearch/cli/note.py@@ -0,0 +1,490 @@+"""Note CRUD CLI commands."""++from __future__ import annotations++from datetime import UTC++import typer++from hyperresearch.cli._output import console, output, print_note_summary+from hyperresearch.models.output import error, success++app = typer.Typer()++[email protected]("new")+def note_new(+ title: str = typer.Argument(..., help="Note title"),+ body_text: str | None = typer.Option(None, "--body", "-b", help="Note body content (markdown)"),+ body_file: str | None = typer.Option(None, "--body-file", "-B", help="Read body from file path"),+ body_stdin: bool = typer.Option(False, "--body-stdin", help="Read body from stdin"),+ tags: list[str] = typer.Option([], "--tag", "-t", help="Tags"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Parent topic"),+ note_type: str = typer.Option("note", "--type", help="Note type"),+ status: str = typer.Option("draft", "--status", "-s", help="Initial status"),+ summary: str | None = typer.Option(None, "--summary", help="One-line summary"),+ source: str | None = typer.Option(None, "--source", help="Source URL or path"),+ confidence: float | None = typer.Option(None, "--confidence", help="Confidence 0.0-1.0"),+ template: str | None = typer.Option(None, "--template", "-T", help="Template: note|concept|reference|guide|comparison|moc"),+ edit: bool = typer.Option(False, "--edit", "-e", help="Open in $EDITOR"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Create a new note.++ Body content: use --body for short text, --body-file for longer content+ (avoids shell escaping), or --body-stdin to pipe it in.+ """+ import sys+ from pathlib import Path as P++ from hyperresearch.core.note import write_note+ from hyperresearch.core.vault import Vault+ from hyperresearch.models.note import slugify++ vault = Vault.discover()+ vault.auto_sync()++ # Determine body content+ if body_file:+ body = P(body_file).read_text(encoding="utf-8")+ elif body_stdin:+ body = sys.stdin.read()+ elif body_text:+ body = body_text+ else:+ body = f"# {title}\n\n"++ nid = slugify(title)++ # Check for duplicate before creating+ similar = vault.db.execute(+ "SELECT id, title FROM notes WHERE id = ? OR LOWER(title) = LOWER(?)",+ (nid, title),+ ).fetchall()+ if similar:+ existing = [{"id": r["id"], "title": r["title"]} for r in similar]+ if json_output:+ # Warn but still create — agent can decide+ pass # Will include warning in response below+ else:+ for s in existing:+ console.print(f"[yellow]Similar note exists:[/] {s['id']} — {s['title']}")++ # Use template if specified+ if template:+ from hyperresearch.core.templates import get_template, render_template++ tpl = get_template(template, vault.templates_dir)+ if tpl:+ rendered = render_template(tpl, title, nid, tags)+ target_dir = vault.notes_dir+ if parent:+ target_dir = target_dir / slugify(parent)+ target_dir.mkdir(parents=True, exist_ok=True)+ file_path = target_dir / f"{nid}.md"+ counter = 2+ while file_path.exists():+ file_path = target_dir / f"{nid}-{counter}.md"+ nid = f"{nid}-{counter}"+ counter += 1+ file_path.write_text(rendered, encoding="utf-8")+ path = file_path+ else:+ console.print(f"[yellow]Template '{template}' not found, using default.[/]")+ path = write_note(vault.notes_dir, title, body=body, tags=tags, status=status,+ note_type=note_type, parent=parent, summary=summary,+ source=source)+ else:+ path = write_note(vault.notes_dir, title, body=body, tags=tags, status=status,+ note_type=note_type, parent=parent, summary=summary,+ source=source)++ # Read back the note ID (may have been collision-adjusted)+ from hyperresearch.core.note import read_note+ note = read_note(path, vault.root)+ nid = note.meta.id++ rel = path.relative_to(vault.root).as_posix()++ if json_output:+ data = {"id": nid, "path": rel, "title": title}+ if similar:+ data["warning"] = f"Similar note already exists: {similar[0]['id']}"+ data["similar"] = [{"id": r["id"], "title": r["title"]} for r in similar]+ top_tags = vault.db.execute(+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC LIMIT 30"+ ).fetchall()+ if top_tags:+ data["existing_tags"] = [r["tag"] for r in top_tags]+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Created:[/] {rel}")++ if edit:+ import os+ import subprocess++ editor = os.environ.get("EDITOR", "vim")+ subprocess.run([editor, str(path)])++[email protected]("show")+def note_show(+ note_ids: list[str] = typer.Argument(..., help="Note ID(s) — pass multiple to read several at once"),+ raw: bool = typer.Option(False, "--raw", "-r", help="Show raw markdown"),+ meta: bool = typer.Option(False, "--meta", "-m", help="Show only frontmatter"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Display one or more notes. Pass multiple IDs for batch read."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ def _fetch_note(nid: str) -> dict | None:+ row = vault.db.execute(+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?",+ (nid,),+ ).fetchone()+ if not row:+ return None+ tag_list = vault.db.execute(+ "SELECT GROUP_CONCAT(tag, ',') as tl FROM tags WHERE note_id = ?", (nid,)+ ).fetchone()+ tags = tag_list["tl"].split(",") if tag_list and tag_list["tl"] else []+ data = {+ "id": row["id"], "title": row["title"], "path": row["path"],+ "status": row["status"], "type": row["type"], "tags": tags,+ "created": row["created"], "updated": row["updated"],+ "word_count": row["word_count"], "source": row["source"],+ "parent": row["parent"], "summary": row["summary"],+ }+ if not meta:+ data["body"] = row["body"]+ return data++ # Single note — original behavior+ if len(note_ids) == 1:+ note_id = note_ids[0]+ if raw:+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()+ if not row:+ if json_output:+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]Note not found:[/] {note_id}")+ raise typer.Exit(1)+ console.print((vault.root / row["path"]).read_text(encoding="utf-8"))+ return++ data = _fetch_note(note_id)+ if not data:+ if json_output:+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]Note not found:[/] {note_id}")+ raise typer.Exit(1)++ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ if meta:+ for k, v in data.items():+ if v is not None:+ console.print(f" [dim]{k}:[/] {v}")+ else:+ tags = data.get("tags", [])+ console.print(f"[bold]{data['title']}[/] [dim]({data['id']})[/]")+ console.print(f"[dim]Status: {data['status']} | Tags: {', '.join(tags)}[/]")+ console.print()+ from rich.markdown import Markdown+ console.print(Markdown(data.get("body", "")))+ return++ # Multi-note — batch read+ notes = []+ not_found = []+ for nid in note_ids:+ data = _fetch_note(nid)+ if data:+ notes.append(data)+ else:+ not_found.append(nid)++ if json_output:+ result = {"notes": notes, "not_found": not_found}+ output(success(result, count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ for data in notes:+ tags = data.get("tags", [])+ console.print(f"\n[bold]{data['title']}[/] [dim]({data['id']})[/]")+ console.print(f"[dim]Status: {data['status']} | Tags: {', '.join(tags)}[/]")+ if not meta:+ console.print()+ from rich.markdown import Markdown+ console.print(Markdown(data.get("body", "")))+ if not_found:+ console.print(f"\n[red]Not found:[/] {', '.join(not_found)}")++[email protected]("list")+def note_list(+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ note_type: str | None = typer.Option(None, "--type", help="Filter by type"),+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent"),+ sort: str = typer.Option("updated", "--sort", help="Sort: created|updated|title|words"),+ limit: int = typer.Option(20, "--limit", "-l", help="Max results"),+ all_notes: bool = typer.Option(False, "--all", "-a", help="Return all notes (no limit)"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """List notes with optional filters."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ clauses = []+ params: list = []++ if status:+ clauses.append("n.status = ?")+ params.append(status)+ if note_type:+ clauses.append("n.type = ?")+ params.append(note_type)+ if parent:+ clauses.append("n.parent = ?")+ params.append(parent)+ if tag:+ clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")+ params.append(tag.lower())++ where = " AND ".join(clauses) if clauses else "1=1"++ sort_map = {+ "created": "n.created DESC",+ "updated": "COALESCE(n.updated, n.created) DESC",+ "title": "n.title ASC",+ "words": "n.word_count DESC",+ }+ order = sort_map.get(sort, "COALESCE(n.updated, n.created) DESC")++ effective_limit = 999999 if all_notes else limit+ rows = vault.db.execute(+ f"""SELECT n.*,+ (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list+ FROM notes n WHERE {where} ORDER BY {order} LIMIT ?""",+ [*params, effective_limit],+ ).fetchall()++ notes = []+ for row in rows:+ tag_list = row["tag_list"].split(",") if row["tag_list"] else []+ notes.append({+ "id": row["id"],+ "title": row["title"],+ "path": row["path"],+ "status": row["status"],+ "type": row["type"],+ "tags": tag_list,+ "word_count": row["word_count"],+ "summary": row["summary"],+ "created": row["created"],+ "updated": row["updated"],+ })++ if json_output:+ output(+ success(notes, count=len(notes), vault=str(vault.root)),+ json_mode=True,+ )+ else:+ print_note_summary(notes)++[email protected]("edit")+def note_edit(+ note_id: str = typer.Argument(..., help="Note ID to edit"),+) -> None:+ """Open a note in $EDITOR."""+ import os+ import subprocess++ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()+ if not row:+ console.print(f"[red]Not found:[/] {note_id}")+ raise typer.Exit(1)++ file_path = vault.root / row["path"]+ editor = os.environ.get("EDITOR", os.environ.get("VISUAL", "notepad" if os.name == "nt" else "vim"))+ subprocess.run([editor, str(file_path)])++[email protected]("update")+def note_update(+ note_id: str = typer.Argument(..., help="Note ID"),+ set_status: str | None = typer.Option(None, "--status", "-s", help="Set status"),+ add_tag: list[str] = typer.Option([], "--add-tag", help="Add tag(s)"),+ remove_tag: list[str] = typer.Option([], "--remove-tag", help="Remove tag(s)"),+ set_summary: str | None = typer.Option(None, "--summary", help="Set summary"),+ set_parent: str | None = typer.Option(None, "--parent", "-p", help="Set parent topic"),+ set_source: str | None = typer.Option(None, "--source", help="Set source URL/path"),+ set_confidence: float | None = typer.Option(None, "--confidence", help="Set confidence 0.0-1.0"),+ set_superseded_by: str | None = typer.Option(None, "--superseded-by", help="Mark as superseded"),+ deprecate: bool = typer.Option(False, "--deprecate", help="Mark as deprecated"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Update frontmatter fields on a single note."""+ from datetime import datetime++ from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()+ if not row:+ if json_output:+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]Not found:[/] {note_id}")+ raise typer.Exit(1)++ file_path = vault.root / row["path"]+ content = file_path.read_text(encoding="utf-8-sig")+ meta, body = parse_frontmatter(content)++ changed = []+ if set_status:+ meta.status = set_status+ changed.append(f"status={set_status}")+ for t in add_tag:+ if t.lower() not in meta.tags:+ meta.tags.append(t.lower())+ changed.append(f"+tag:{t}")+ for t in remove_tag:+ if t.lower() in meta.tags:+ meta.tags.remove(t.lower())+ changed.append(f"-tag:{t}")+ if set_summary is not None:+ meta.summary = set_summary+ changed.append("summary")+ if set_parent is not None:+ meta.parent = set_parent+ changed.append(f"parent={set_parent}")+ if set_source is not None:+ meta.source = set_source+ changed.append("source")+ if set_confidence is not None:+ meta.confidence = set_confidence+ changed.append(f"confidence={set_confidence}")+ if set_superseded_by is not None:+ meta.superseded_by = set_superseded_by+ changed.append(f"superseded_by={set_superseded_by}")+ if deprecate:+ meta.deprecated = True+ meta.status = "deprecated"+ changed.append("deprecated")++ if not changed:+ if json_output:+ output(success({"id": note_id, "changed": []}, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[dim]Nothing to update.[/]")+ return++ meta.updated = datetime.now(UTC)+ new_content = serialize_frontmatter(meta) + "\n" + body+ file_path.write_text(new_content, encoding="utf-8")++ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)++ if json_output:+ output(success({"id": note_id, "changed": changed}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Updated {note_id}:[/] {', '.join(changed)}")++[email protected]("mv")+def note_mv(+ note_id: str = typer.Argument(..., help="Note ID to move"),+ new_path: str = typer.Argument(..., help="New relative path (e.g. notes/python/renamed.md)"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Move/rename a note, updating all references."""+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()+ if not row:+ if json_output:+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]Not found:[/] {note_id}")+ raise typer.Exit(1)++ old_file = vault.root / row["path"]+ new_file = vault.root / new_path++ new_file.parent.mkdir(parents=True, exist_ok=True)+ old_file.rename(new_file)++ # Re-sync+ plan = compute_sync_plan(vault, force=True)+ execute_sync(vault, plan)++ if json_output:+ output(success({"old_path": row["path"], "new_path": new_path}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Moved:[/] {row['path']} → {new_path}")++[email protected]("rm")+def note_rm(+ note_id: str = typer.Argument(..., help="Note ID to delete"),+ force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Delete a note."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()+ if not row:+ if json_output:+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)+ else:+ console.print(f"[red]Not found:[/] {note_id}")+ raise typer.Exit(1)++ file_path = vault.root / row["path"]+ if not force and not json_output:+ typer.confirm(f"Delete {row['path']}?", abort=True)++ if file_path.exists():+ file_path.unlink()++ # Re-sync to update DB+ from hyperresearch.core.sync import compute_sync_plan, execute_sync++ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)++ if json_output:+ output(success({"deleted": note_id}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[red]Deleted:[/] {note_id}")++diff --git a/src/hyperresearch/cli/repair.py b/src/hyperresearch/cli/repair.pynew file mode 100644index 0000000..b4e49c4--- /dev/null+++ b/src/hyperresearch/cli/repair.py@@ -0,0 +1,254 @@+"""Repair command — fix and rebuild everything in one shot."""++from __future__ import annotations++from datetime import UTC++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success+++def repair(+ stub_broken: bool = typer.Option(True, "--stub/--no-stub", help="Create stubs for broken links"),+ enrich: bool = typer.Option(True, "--enrich/--no-enrich", help="Auto-tag and auto-summarize notes"),+ promote_notes: bool = typer.Option(True, "--promote/--no-promote", help="Auto-promote qualifying notes"),+ rebuild_index: bool = typer.Option(True, "--index/--no-index", help="Rebuild index pages"),+ update_docs: bool = typer.Option(True, "--docs/--no-docs", help="Update CLAUDE.md/AGENTS.md"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Repair and rebuild the vault — full sync, fix broken links, promote notes, rebuild indexes."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ report: dict = {}++ # Step 1: Force sync — rebuild DB from all files+ if not json_output:+ console.print("[bold]1/6 Syncing...[/]")+ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ plan = compute_sync_plan(vault, force=True)+ result = execute_sync(vault, plan)+ report["sync"] = {+ "added": result.added, "updated": result.updated,+ "deleted": result.deleted, "errors": len(result.errors),+ }+ if not json_output:+ console.print(+ f" +{result.added} ~{result.updated} -{result.deleted} "+ f"({result.duration_ms:.0f}ms)"+ )++ # Step 2: Stub broken links+ stubs_created = 0+ if stub_broken:+ if not json_output:+ console.print("[bold]2/6 Stubbing broken links...[/]")+ from hyperresearch.core.note import write_note+ rows = vault.db.execute(+ "SELECT DISTINCT target_ref FROM links WHERE target_id IS NULL"+ ).fetchall()+ for row in rows:+ target = row["target_ref"]+ title = target.replace("-", " ").replace("_", " ").title()+ try:+ write_note(+ vault.notes_dir, title,+ body=f"# {title}\n\n*Stub — created to resolve a broken link. Expand this note.*\n",+ note_id=target, status="draft",+ summary=f"Stub for [[{target}]]",+ )+ stubs_created += 1+ except Exception:+ pass+ if stubs_created:+ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)+ report["stubs"] = stubs_created+ if not json_output:+ console.print(f" {stubs_created} stubs created")+ else:+ if not json_output:+ console.print("[dim]2/6 Skipping stubs[/]")++ # Step 3: Enrich — auto-tag and auto-summarize+ enriched_count = 0+ if enrich:+ if not json_output:+ console.print("[bold]3/6 Enriching metadata...[/]")+ from datetime import datetime as _dt++ from hyperresearch.core.enrich import auto_summary, auto_tag+ from hyperresearch.core.frontmatter import parse_frontmatter as _parse_fm+ from hyperresearch.core.frontmatter import serialize_frontmatter as _ser_fm++ # Get existing tag vocabulary+ tag_vocab = [+ {"tag": r["tag"], "count": r["c"]}+ for r in vault.db.execute("SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC")+ ]++ # Find notes missing tags or summary+ deficient = vault.db.execute(+ "SELECT n.id, n.path, n.summary FROM notes n "+ "LEFT JOIN note_content nc ON n.id = nc.note_id "+ "WHERE n.type NOT IN ('index', 'raw') AND ("+ " n.id NOT IN (SELECT DISTINCT note_id FROM tags) OR "+ " n.summary IS NULL OR LENGTH(TRIM(COALESCE(n.summary, ''))) = 0"+ ")"+ ).fetchall()++ for row in deficient:+ try:+ fp = vault.root / row["path"]+ meta, body = _parse_fm(fp.read_text(encoding="utf-8-sig"))+ changed = False++ # Auto-tag if no tags+ if not meta.tags:+ from hyperresearch.core.note import strip_markdown+ body_plain = strip_markdown(body)+ suggested = auto_tag(body_plain, tag_vocab)+ if suggested:+ meta.tags = suggested+ changed = True++ # Auto-summary if no summary+ if not meta.summary or not meta.summary.strip():+ suggested = auto_summary(body)+ if suggested:+ meta.summary = suggested+ changed = True++ if changed:+ meta.updated = _dt.now(UTC)+ fp.write_text(_ser_fm(meta) + "\n" + body, encoding="utf-8")+ enriched_count += 1+ except Exception:+ pass++ if enriched_count:+ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)+ report["enriched"] = enriched_count+ if not json_output:+ console.print(f" {enriched_count} notes enriched")+ else:+ if not json_output:+ console.print("[dim]3/6 Skipping enrichment[/]")++ # Step 4: Promote notes+ promoted_count = 0+ if promote_notes:+ if not json_output:+ console.print("[bold]4/6 Promoting notes...[/]")+ from datetime import datetime++ from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter++ # Draft -> Review+ drafts = vault.db.execute("""+ SELECT n.id, n.path FROM notes n+ WHERE n.status = 'draft' AND n.type NOT IN ('index')+ AND n.word_count >= 50+ AND n.summary IS NOT NULL AND LENGTH(n.summary) > 0+ AND n.id IN (SELECT note_id FROM tags)+ """).fetchall()+ for row in drafts:+ try:+ fp = vault.root / row["path"]+ meta, body = parse_frontmatter(fp.read_text(encoding="utf-8-sig"))+ meta.status = "review"+ meta.updated = datetime.now(UTC)+ fp.write_text(serialize_frontmatter(meta) + "\n" + body, encoding="utf-8")+ promoted_count += 1+ except Exception:+ pass++ # Review -> Evergreen+ reviews = vault.db.execute("""+ SELECT n.id, n.path FROM notes n+ WHERE n.status = 'review' AND n.type NOT IN ('index')+ AND n.word_count >= 100+ AND (n.id IN (SELECT DISTINCT source_id FROM links)+ OR n.id IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL))+ """).fetchall()+ for row in reviews:+ try:+ fp = vault.root / row["path"]+ meta, body = parse_frontmatter(fp.read_text(encoding="utf-8-sig"))+ meta.status = "evergreen"+ meta.updated = datetime.now(UTC)+ fp.write_text(serialize_frontmatter(meta) + "\n" + body, encoding="utf-8")+ promoted_count += 1+ except Exception:+ pass++ if promoted_count:+ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)+ report["promoted"] = promoted_count+ if not json_output:+ console.print(f" {promoted_count} notes promoted")+ else:+ if not json_output:+ console.print("[dim]4/6 Skipping promotion[/]")++ # Step 4: Rebuild indexes+ if rebuild_index:+ if not json_output:+ console.print("[bold]5/6 Rebuilding indexes...[/]")+ from hyperresearch.indexgen.generator import IndexGenerator+ gen = IndexGenerator(vault)+ built = gen.build_all()+ # Sync the new index pages+ plan = compute_sync_plan(vault)+ execute_sync(vault, plan)+ report["indexes"] = len(built)+ if not json_output:+ console.print(f" {len(built)} index pages built")+ else:+ if not json_output:+ console.print("[dim]5/6 Skipping indexes[/]")++ # Step 5: Update agent docs+ if update_docs:+ if not json_output:+ console.print("[bold]6/6 Updating agent docs...[/]")+ from hyperresearch.core.agent_docs import inject_agent_docs+ modified = inject_agent_docs(vault.root)+ report["agent_docs"] = modified+ if not json_output:+ if modified:+ for m in modified:+ console.print(f" {m}")+ else:+ console.print(" Already up to date")+ else:+ if not json_output:+ console.print("[dim]6/6 Skipping agent docs[/]")++ # Final lint summary+ broken = vault.db.execute("SELECT COUNT(*) as c FROM links WHERE target_id IS NULL").fetchone()["c"]+ orphans = vault.db.execute("""+ SELECT COUNT(*) as c FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ """).fetchone()["c"]+ total = vault.db.execute("SELECT COUNT(*) as c FROM notes WHERE type NOT IN ('index')").fetchone()["c"]+ report["health"] = {"total_notes": total, "broken_links": broken, "orphans": orphans}++ if json_output:+ output(success(report, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"\n[bold]Done.[/] {total} notes, {broken} broken links, {orphans} orphans.")diff --git a/src/hyperresearch/cli/search.py b/src/hyperresearch/cli/search.pynew file mode 100644index 0000000..ea191dc--- /dev/null+++ b/src/hyperresearch/cli/search.py@@ -0,0 +1,104 @@+"""Search CLI — full-text search across all notes."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success+++def search(+ query: str = typer.Argument(..., help="Search query"),+ tag: list[str] = typer.Option([], "--tag", "-t", help="Filter by tag (AND logic)"),+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),+ note_type: str | None = typer.Option(None, "--type", help="Filter by type"),+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),+ after: str | None = typer.Option(None, "--after", help="Created after date (YYYY-MM-DD)"),+ before: str | None = typer.Option(None, "--before", help="Created before date (YYYY-MM-DD)"),+ path_glob: str | None = typer.Option(None, "--path", help="Glob filter on path"),+ min_words: int | None = typer.Option(None, "--min-words", help="Minimum word count"),+ max_words: int | None = typer.Option(None, "--max-words", help="Maximum word count"),+ linked_from: str | None = typer.Option(None, "--linked-from", help="Only notes linked FROM this note ID"),+ linked_to: str | None = typer.Option(None, "--linked-to", help="Only notes that link TO this note ID"),+ min_inbound: int | None = typer.Option(None, "--min-inbound", help="Minimum inbound link count"),+ has_backlinks: bool = typer.Option(False, "--has-backlinks", help="Only notes with backlinks"),+ include_body: bool = typer.Option(False, "--include-body", help="Include full note body (auto-enabled with --json)"),+ no_body: bool = typer.Option(False, "--no-body", help="Disable auto body inclusion in JSON mode"),+ limit: int = typer.Option(20, "--limit", "-l", help="Max results"),+ offset: int = typer.Option(0, "--offset", help="Offset for pagination"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Full-text search across all notes."""+ from hyperresearch.core.vault import Vault, VaultError+ from hyperresearch.search.filters import SearchFilters+ from hyperresearch.search.fts import search_fts++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)+ vault.auto_sync()++ filters = SearchFilters(+ tags=tag or None,+ status=status,+ note_type=note_type,+ parent=parent,+ after=after,+ before=before,+ path_glob=path_glob,+ min_words=min_words,+ max_words=max_words,+ linked_from=linked_from,+ linked_to=linked_to,+ min_inbound=min_inbound,+ has_backlinks=has_backlinks or None,+ )++ ranking = {+ "title_weight": vault.config.search_title_weight,+ "body_weight": vault.config.search_body_weight,+ "tags_weight": vault.config.search_tags_weight,+ "aliases_weight": vault.config.search_aliases_weight,+ "boost_evergreen": vault.config.search_boost_evergreen,+ "penalize_deprecated": vault.config.search_penalize_deprecated,+ "penalize_stale": vault.config.search_penalize_stale,+ }+ results = search_fts(vault.db, query, filters=filters, limit=limit, offset=offset, ranking=ranking)++ # Auto-include body in JSON mode (agents almost always need it)+ want_body = include_body or (json_output and not no_body)+ if want_body and results:+ for r in results:+ row = vault.db.execute(+ "SELECT body FROM note_content WHERE note_id = ?", (r["id"],)+ ).fetchone()+ r["body"] = row["body"] if row else ""++ if json_output:+ output(+ success(+ {"query": query, "results": results, "total": len(results)},+ count=len(results),+ vault=str(vault.root),+ ),+ json_mode=True,+ )+ else:+ if not results:+ console.print("[dim]No results found.[/]")+ return+ for r in results:+ tags_str = ", ".join(r.get("tags", []))+ console.print(+ f" [cyan]{r['id']}[/] [bold]{r['title']}[/] "+ f"[dim]({r['status']})[/] [green]{tags_str}[/]"+ )+ if r.get("snippet"):+ console.print(f" [dim]{r['snippet'][:200]}[/]")+ console.print()diff --git a/src/hyperresearch/cli/serve.py b/src/hyperresearch/cli/serve.pynew file mode 100644index 0000000..f7a98bb--- /dev/null+++ b/src/hyperresearch/cli/serve.py@@ -0,0 +1,26 @@+"""Serve CLI command — browse vault in a web browser."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console+++def serve(+ port: int = typer.Option(8080, "--port", "-p", help="Port to serve on"),+ open_browser: bool = typer.Option(False, "--open", "-o", help="Open browser automatically"),+) -> None:+ """Start a web server to browse the vault."""+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ vault.auto_sync()++ from hyperresearch.serve.server import run_server+ run_server(vault, port=port, open_browser=open_browser)diff --git a/src/hyperresearch/cli/tag.py b/src/hyperresearch/cli/tag.pynew file mode 100644index 0000000..31652d9--- /dev/null+++ b/src/hyperresearch/cli/tag.py@@ -0,0 +1,121 @@+"""Tag management CLI — list, alias, suggest merges, clean."""++from __future__ import annotations++from difflib import SequenceMatcher++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("list")+def tag_list(+ min_count: int = typer.Option(1, "--min", "-m", help="Only show tags with N+ notes"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """List all tags with note counts."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()+ rows = vault.db.execute(+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag HAVING count >= ? ORDER BY count DESC",+ (min_count,),+ ).fetchall()+ tags = [{"tag": r["tag"], "count": r["count"]} for r in rows]++ if json_output:+ output(success(tags, count=len(tags), vault=str(vault.root)), json_mode=True)+ else:+ from rich.table import Table++ table = Table(title="Tags", show_header=True, header_style="bold")+ table.add_column("Tag", style="green")+ table.add_column("Notes", justify="right")+ for t in tags:+ table.add_row(t["tag"], str(t["count"]))+ console.print(table)++[email protected]("alias")+def tag_alias(+ from_tag: str = typer.Argument(..., help="Tag to alias (the variant)"),+ to_tag: str = typer.Argument(..., help="Canonical tag to map to"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Create a tag alias. Notes with the variant tag will be indexed under the canonical tag."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.db.execute(+ "INSERT OR REPLACE INTO tag_aliases (alias, canonical) VALUES (?, ?)",+ (from_tag.lower(), to_tag.lower()),+ )+ vault.db.commit()++ if json_output:+ output(success({"alias": from_tag, "canonical": to_tag}, vault=str(vault.root)), json_mode=True)+ else:+ console.print(f"[green]Alias:[/] {from_tag} -> {to_tag}")+ console.print("[dim]Run 'hyperresearch sync --force' to apply.[/]")++[email protected]("suggest")+def tag_suggest(+ threshold: float = typer.Option(0.7, "--threshold", help="Similarity threshold"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Suggest tag merges based on string similarity."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag ORDER BY count DESC"+ ).fetchall()+ tags = [(r["tag"], r["count"]) for r in rows]++ # Find similar tag pairs+ suggestions = []+ popular = [t for t in tags if t[1] >= 3]+ singletons = [t for t in tags if t[1] == 1]++ for stag, _scount in singletons:+ for ptag, pcount in popular:+ sim = SequenceMatcher(None, stag, ptag).ratio()+ if sim >= threshold and stag != ptag:+ suggestions.append({+ "singleton": stag,+ "suggested_canonical": ptag,+ "similarity": round(sim, 2),+ "canonical_count": pcount,+ })+ break # Best match++ # Also catch simple plurals+ tag_set = {t[0] for t in tags}+ for stag, _sc in singletons:+ if stag.endswith("s") and stag[:-1] in tag_set and stag not in [s["singleton"] for s in suggestions]:+ suggestions.append({"singleton": stag, "suggested_canonical": stag[:-1],+ "similarity": 0.95, "canonical_count": next((c for t, c in tags if t == stag[:-1]), 0)})++ suggestions.sort(key=lambda s: s["similarity"], reverse=True)++ if json_output:+ output(success(suggestions, count=len(suggestions), vault=str(vault.root)), json_mode=True)+ else:+ if not suggestions:+ console.print("[dim]No merge suggestions found.[/]")+ return+ console.print(f"[bold]Suggested merges ({len(suggestions)}):[/]\n")+ for s in suggestions[:30]:+ console.print(+ f" {s['singleton']:30s} -> {s['suggested_canonical']:20s} "+ f"({s['similarity']:.0%} similar, {s['canonical_count']} notes)"+ )+ console.print("\n[dim]Apply with: hyperresearch tag alias <from> <to>[/]")diff --git a/src/hyperresearch/cli/template.py b/src/hyperresearch/cli/template.pynew file mode 100644index 0000000..bd8a0db--- /dev/null+++ b/src/hyperresearch/cli/template.py@@ -0,0 +1,58 @@+"""Template CLI commands."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("list")+def template_list(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """List available note templates."""+ from hyperresearch.core.templates import list_templates+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ templates = list_templates(vault.templates_dir)+ except VaultError:+ templates = list_templates()++ if json_output:+ output(success(templates, count=len(templates)), json_mode=True)+ else:+ from rich.table import Table++ table = Table(title="Templates", show_header=True, header_style="bold")+ table.add_column("Name", style="cyan")+ table.add_column("Source", style="dim")+ for t in templates:+ table.add_row(t["name"], t["source"])+ console.print(table)++[email protected]("show")+def template_show(+ name: str = typer.Argument(..., help="Template name"),+) -> None:+ """Preview a template."""+ from hyperresearch.core.templates import get_template+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ tpl = get_template(name, vault.templates_dir)+ except VaultError:+ tpl = get_template(name)++ if not tpl:+ console.print(f"[red]Template not found:[/] {name}")+ raise typer.Exit(1)++ console.print(tpl)diff --git a/src/hyperresearch/cli/topic.py b/src/hyperresearch/cli/topic.pynew file mode 100644index 0000000..56dd683--- /dev/null+++ b/src/hyperresearch/cli/topic.py@@ -0,0 +1,163 @@+"""Topic tree CLI commands — hierarchical parent navigation."""++from __future__ import annotations++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import success++app = typer.Typer()++[email protected]("tree")+def topic_tree(+ depth: int = typer.Option(0, "--depth", "-d", help="Max depth (0=unlimited)"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show the full topic hierarchy as a tree."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ "SELECT parent, COUNT(*) as count FROM notes "+ "WHERE parent IS NOT NULL AND type NOT IN ('index') "+ "GROUP BY parent ORDER BY parent"+ ).fetchall()++ # Collect all unique topic paths and their counts+ topics = {}+ for row in rows:+ path = row["parent"]+ topics[path] = row["count"]+ # Add ancestor paths with 0 count if missing+ parts = path.split("/")+ for i in range(1, len(parts)):+ ancestor = "/".join(parts[:i])+ if ancestor not in topics:+ topics[ancestor] = 0++ if json_output:+ data = [{"topic": k, "direct_notes": v} for k, v in sorted(topics.items())]+ output(success(data, count=len(data), vault=str(vault.root)), json_mode=True)+ else:+ if not topics:+ console.print("[dim]No topics found. Set 'parent' in note frontmatter.[/]")+ return++ from rich.tree import Tree++ root = Tree("[bold]Topics[/]")+ _build_rich_tree(root, topics, depth)+ console.print(root)+++def _build_rich_tree(parent_node, topics: dict, max_depth: int, prefix: str = "", current_depth: int = 0):+ """Recursively build a Rich tree from topic paths."""+ if max_depth > 0 and current_depth >= max_depth:+ return++ # Find direct children at this level+ children: dict[str, int] = {}+ for path, count in sorted(topics.items()):+ if prefix:+ if not path.startswith(prefix + "/"):+ continue+ remainder = path[len(prefix) + 1:]+ else:+ remainder = path++ if "/" not in remainder:+ children[remainder] = count++ for child_name, count in sorted(children.items()):+ full_path = f"{prefix}/{child_name}" if prefix else child_name+ # Count all notes under this subtree+ subtree_count = sum(v for k, v in topics.items() if k == full_path or k.startswith(full_path + "/"))+ label = f"[cyan]{child_name}[/]"+ if count > 0:+ label += f" ({count} notes)"+ if subtree_count > count:+ label += f" [dim]({subtree_count} total)[/]"+ child_node = parent_node.add(label)+ _build_rich_tree(child_node, topics, max_depth, full_path, current_depth + 1)++[email protected]("list")+def topic_list(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Flat list of all topics with note counts."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ rows = vault.db.execute(+ "SELECT parent, COUNT(*) as count FROM notes "+ "WHERE parent IS NOT NULL AND type NOT IN ('index') "+ "GROUP BY parent ORDER BY count DESC"+ ).fetchall()++ topics = [{"topic": r["parent"], "count": r["count"]} for r in rows]++ if json_output:+ output(success(topics, count=len(topics), vault=str(vault.root)), json_mode=True)+ else:+ from rich.table import Table++ table = Table(title="Topics", show_header=True, header_style="bold")+ table.add_column("Topic", style="cyan")+ table.add_column("Notes", justify="right")+ for t in topics:+ table.add_row(t["topic"], str(t["count"]))+ console.print(table)++[email protected]("show")+def topic_show(+ topic: str = typer.Argument(..., help="Topic path (e.g. ml/deep-learning)"),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Show all notes under a topic (including subtopics)."""+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ vault.auto_sync()++ # Match exact and subtopics+ rows = vault.db.execute(+ """SELECT n.id, n.title, n.parent, n.status, n.word_count, n.summary,+ (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list+ FROM notes n+ WHERE (n.parent = ? OR n.parent LIKE ?)+ AND n.type NOT IN ('index')+ ORDER BY n.parent, n.title""",+ (topic, topic + "/%"),+ ).fetchall()++ notes = []+ for row in rows:+ tag_list = row["tag_list"].split(",") if row["tag_list"] else []+ notes.append({+ "id": row["id"],+ "title": row["title"],+ "parent": row["parent"],+ "status": row["status"],+ "tags": tag_list,+ "word_count": row["word_count"],+ "summary": row["summary"],+ })++ if json_output:+ output(success({"topic": topic, "notes": notes}, count=len(notes), vault=str(vault.root)), json_mode=True)+ else:+ if not notes:+ console.print(f"[dim]No notes under topic '{topic}'[/]")+ return+ console.print(f"[bold]Topic: {topic}[/] ({len(notes)} notes)\n")+ for n in notes:+ summary = f" — {n['summary']}" if n["summary"] else ""+ console.print(f" [cyan]{n['id']}[/] {n['title']}{summary} [dim]`{n['status']}`[/]")diff --git a/src/hyperresearch/cli/watch.py b/src/hyperresearch/cli/watch.pynew file mode 100644index 0000000..9c3bf86--- /dev/null+++ b/src/hyperresearch/cli/watch.py@@ -0,0 +1,113 @@+"""Watch mode — auto-sync on file changes."""++from __future__ import annotations++import time++import typer++from hyperresearch.cli._output import console+++def watch(+ rebuild_index: bool = typer.Option(False, "--rebuild-index", "-i", help="Rebuild indexes after sync"),+ run_lint: bool = typer.Option(False, "--lint", "-l", help="Run lint after sync"),+) -> None:+ """Watch for file changes and auto-sync."""+ try:+ from watchdog.events import FileSystemEvent, FileSystemEventHandler+ from watchdog.observers import Observer+ except ImportError:+ console.print("[red]Watch mode requires: pip install hyperresearch[watch][/]")+ raise typer.Exit(1)++ from hyperresearch.core.sync import compute_sync_plan, execute_sync+ from hyperresearch.core.vault import Vault++ vault = Vault.discover()+ console.print(f"[bold]Watching:[/] {vault.root}")+ console.print("[dim]Press Ctrl+C to stop.[/]\n")++ class DebouncedHandler(FileSystemEventHandler):+ def __init__(self):+ self._pending = False+ self._last_event = 0.0++ def on_any_event(self, event: FileSystemEvent):+ if not event.src_path.endswith(".md"):+ return+ # Skip .hyperresearch directory+ if ".hyperresearch" in event.src_path:+ return+ self._pending = True+ self._last_event = time.monotonic()++ def check_and_sync(self) -> bool:+ if not self._pending:+ return False+ # Debounce: wait 500ms after last event+ if time.monotonic() - self._last_event < 0.5:+ return False+ self._pending = False++ try:+ plan = compute_sync_plan(vault)+ if plan.to_add or plan.to_update or plan.to_delete:+ result = execute_sync(vault, plan)+ console.print(+ f"[green]Synced:[/] +{result.added} ~{result.updated} "+ f"-{result.deleted} ({result.duration_ms:.0f}ms)"+ )+ for err in result.errors:+ console.print(f" [red]Error:[/] {err['path']}: {err['error']}")++ if rebuild_index:+ from hyperresearch.indexgen.generator import IndexGenerator+ gen = IndexGenerator(vault)+ built = gen.build_all()+ # Re-sync to index the index pages+ plan2 = compute_sync_plan(vault)+ if plan2.to_add or plan2.to_update:+ execute_sync(vault, plan2)+ console.print(f" [dim]Rebuilt {len(built)} indexes[/]")++ if run_lint:+ _quick_lint(vault)++ return True+ except Exception as e:+ console.print(f"[red]Sync error:[/] {e}")+ return False++ handler = DebouncedHandler()+ observer = Observer()+ observer.schedule(handler, str(vault.research_dir), recursive=True)+ observer.start()++ try:+ while True:+ handler.check_and_sync()+ time.sleep(0.2)+ except KeyboardInterrupt:+ observer.stop()+ console.print("\n[dim]Stopped watching.[/]")+ observer.join()+++def _quick_lint(vault) -> None:+ """Run a quick lint and print summary."""+ conn = vault.db+ broken = conn.execute("SELECT COUNT(*) as c FROM links WHERE target_id IS NULL").fetchone()["c"]+ orphans = conn.execute("""+ SELECT COUNT(*) as c FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ """).fetchone()["c"]+ if broken or orphans:+ parts = []+ if broken:+ parts.append(f"{broken} broken links")+ if orphans:+ parts.append(f"{orphans} orphans")+ console.print(f" [yellow]Lint: {', '.join(parts)}[/]")diff --git a/src/hyperresearch/core/__init__.py b/src/hyperresearch/core/__init__.pynew file mode 100644index 0000000..4bbde6c--- /dev/null+++ b/src/hyperresearch/core/__init__.py@@ -0,0 +1 @@+"""Core vault operations."""diff --git a/src/hyperresearch/core/agent_docs.py b/src/hyperresearch/core/agent_docs.pynew file mode 100644index 0000000..f582f18--- /dev/null+++ b/src/hyperresearch/core/agent_docs.py@@ -0,0 +1,158 @@+"""Agent documentation integration — inject hyperresearch docs into agent config files.++Supports: CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md+By default on init, only creates CLAUDE.md. Others created via --agents flags+or if the file already exists in the repo.+"""++from __future__ import annotations++import re+from pathlib import Path++HYPERRESEARCH_SECTION_MARKER = "<!-- hyperresearch:start -->"+HYPERRESEARCH_SECTION_END = "<!-- hyperresearch:end -->"++HYPERRESEARCH_BLURB = """\++{marker}+## Research Base (hyperresearch)++This project uses hyperresearch as an agent-driven research knowledge base. The `research/` directory contains markdown notes collected from web sources and original research. Append `--json` to any command for structured output.++### Search and read++```bash+hyperresearch search "query" --json # Full-text search+hyperresearch search "query" --tag ml --json # Filter by tag, status, date, parent+hyperresearch search "query" --include-body --json # Include full note bodies in results+hyperresearch note show <id> --json # Read a note+hyperresearch note show <id1> <id2> <id3> --json # Read multiple notes at once+hyperresearch note list --json # List all notes with summaries+```++### Collect research++When you find useful information via web search or browsing, save it as a note:++```bash+hyperresearch note new "Title" --tag t1 --body-file /tmp/content.md --source "https://..." --summary "One-liner" --json+hyperresearch note update <id> --status evergreen --add-tag ml --summary "Updated" --json+```++**Always check the research base BEFORE searching the web** — the answer may already be here.++### Knowledge graph and maintenance++```bash+hyperresearch graph backlinks <id> --json # What links TO this note+hyperresearch graph hubs --json # Most linked-to notes+hyperresearch graph broken --json # Broken [[links]]+hyperresearch lint --json # Health check+hyperresearch repair --json # Full rebuild + fix broken links + promote notes+hyperresearch status --json # Vault overview+```++### Note quality requirements++Every note MUST have:+- At least one tag (`--tag`). REUSE existing tags from `hyperresearch tags -j` -- do not invent new ones unless necessary.+- A summary (`--summary`). One sentence, under 120 characters.+- A body with meaningful content (50+ words).+- A source URL (`--source`) when the content comes from the web.+- Use `--body-file` instead of `--body` to avoid shell escaping issues.++Run `hyperresearch lint -j` to check quality, `hyperresearch repair -j` to auto-fix.++### Key conventions++- Notes live in `research/notes/` as markdown with YAML frontmatter+- Link between notes with `[[note-id]]` syntax+- After editing .md files directly, run `hyperresearch sync` to update the index+- Statuses: draft -> review -> evergreen -> stale -> deprecated -> archive+- Run `hyperresearch --help` for the full command list+{end_marker}+"""++# Which files each agent flag creates+AGENT_FILES = {+ "claude": "CLAUDE.md",+ "agents": "AGENTS.md",+ "gemini": "GEMINI.md",+ "copilot": ".github/copilot-instructions.md",+}+++def inject_agent_docs(+ vault_root: Path,+ agents: list[str] | None = None,+) -> list[str]:+ """Inject hyperresearch docs into agent config files.++ Args:+ vault_root: The repo root.+ agents: Which agent files to create. Default: ["claude"].+ Options: "claude", "agents", "gemini", "copilot".+ If a file already exists, it's always updated regardless of this list.+ """+ if agents is None:+ agents = ["claude"]++ blurb = HYPERRESEARCH_BLURB.format(marker=HYPERRESEARCH_SECTION_MARKER, end_marker=HYPERRESEARCH_SECTION_END)+ modified = []++ # Determine which files to handle+ files_to_inject: list[tuple[Path, str]] = []++ # CLAUDE.md+ if "claude" in agents or (vault_root / "CLAUDE.md").exists():+ files_to_inject.append((vault_root / "CLAUDE.md", "CLAUDE.md"))++ # AGENTS.md — prefer uppercase, respect existing lowercase+ if "agents" in agents or (vault_root / "AGENTS.md").exists() or (vault_root / "agents.md").exists():+ if (vault_root / "agents.md").exists() and not (vault_root / "AGENTS.md").exists():+ files_to_inject.append((vault_root / "agents.md", "agents.md"))+ else:+ files_to_inject.append((vault_root / "AGENTS.md", "AGENTS.md"))++ # GEMINI.md+ if "gemini" in agents or (vault_root / "GEMINI.md").exists():+ files_to_inject.append((vault_root / "GEMINI.md", "GEMINI.md"))++ # .github/copilot-instructions.md+ copilot_path = vault_root / ".github" / "copilot-instructions.md"+ if "copilot" in agents or copilot_path.exists():+ files_to_inject.append((copilot_path, ".github/copilot-instructions.md"))++ for filepath, filename in files_to_inject:+ result = _inject_into_file(filepath, blurb, filename)+ if result:+ modified.append(result)++ return modified+++def _inject_into_file(filepath: Path, blurb: str, filename: str) -> str | None:+ """Inject the hyperresearch blurb into a single file. Returns action taken or None."""+ if filepath.exists():+ content = filepath.read_text(encoding="utf-8-sig")++ if HYPERRESEARCH_SECTION_MARKER in content:+ pattern = re.compile(+ re.escape(HYPERRESEARCH_SECTION_MARKER) + r".*?" + re.escape(HYPERRESEARCH_SECTION_END),+ re.DOTALL,+ )+ new_content = pattern.sub(blurb.strip(), content)+ if new_content != content:+ filepath.write_text(new_content, encoding="utf-8")+ return f"{filename} (updated)"+ return None+ else:+ separator = "\n\n" if not content.endswith("\n") else "\n"+ filepath.write_text(content + separator + blurb.strip() + "\n", encoding="utf-8")+ return f"{filename} (appended)"+ else:+ filepath.parent.mkdir(parents=True, exist_ok=True)+ header = f"# {filepath.stem}\n"+ filepath.write_text(header + blurb.strip() + "\n", encoding="utf-8")+ return f"{filename} (created)"diff --git a/src/hyperresearch/core/config.py b/src/hyperresearch/core/config.pynew file mode 100644index 0000000..cdcaf14--- /dev/null+++ b/src/hyperresearch/core/config.py@@ -0,0 +1,99 @@+"""Vault configuration management (.hyperresearch/config.toml)."""++from __future__ import annotations++import tomllib+from dataclasses import dataclass, field+from pathlib import Path+++@dataclass+class VaultConfig:+ name: str = "Research Base"+ default_status: str = "draft"+ research_dir: str = "research"++ # Search ranking+ search_title_weight: float = 10.0+ search_body_weight: float = 1.0+ search_tags_weight: float = 5.0+ search_aliases_weight: float = 3.0+ search_boost_evergreen: float = 1.5+ search_penalize_deprecated: float = 0.3+ search_penalize_stale: float = 0.7++ # Sync+ auto_sync: bool = True+ exclude_patterns: list[str] = field(+ default_factory=lambda: [+ ".hyperresearch/*", "exports/*", ".git/*", ".venv/*", "node_modules/*", "templates/*",+ "CLAUDE.md", "AGENTS.md", "agents.md", "GEMINI.md", "README.md", "CHANGELOG.md",+ ]+ )++ # Index+ auto_build_index: bool = True+ index_pages: list[str] = field(+ default_factory=lambda: ["_index", "_tags", "_recent", "_orphans", "_stats"]+ )++ @classmethod+ def load(cls, config_path: Path) -> VaultConfig:+ if not config_path.exists():+ return cls()+ with open(config_path, "rb") as f:+ data = tomllib.load(f)++ vault = data.get("vault", {})+ sync = data.get("sync", {})+ index = data.get("index", {})+ search = data.get("search", {})++ return cls(+ name=vault.get("name", cls.name),+ default_status=vault.get("default_status", cls.default_status),+ research_dir=vault.get("research_dir", cls.research_dir),+ search_title_weight=search.get("title_weight", cls.search_title_weight),+ search_body_weight=search.get("body_weight", cls.search_body_weight),+ search_tags_weight=search.get("tags_weight", cls.search_tags_weight),+ search_aliases_weight=search.get("aliases_weight", cls.search_aliases_weight),+ search_boost_evergreen=search.get("boost_evergreen", cls.search_boost_evergreen),+ search_penalize_deprecated=search.get("penalize_deprecated", cls.search_penalize_deprecated),+ search_penalize_stale=search.get("penalize_stale", cls.search_penalize_stale),+ auto_sync=sync.get("auto_sync", cls.auto_sync),+ exclude_patterns=sync.get("exclude_patterns", cls().exclude_patterns),+ auto_build_index=index.get("auto_build", cls.auto_build_index),+ index_pages=index.get("pages", cls().index_pages),+ )++ @staticmethod+ def _toml_array(items: list[str]) -> str:+ quoted = ", ".join(f'"{item}"' for item in items)+ return f"[{quoted}]"++ def save(self, config_path: Path) -> None:+ lines = [+ "[vault]",+ f'name = "{self.name}"',+ f'default_status = "{self.default_status}"',+ f'research_dir = "{self.research_dir}"',+ "",+ "[search]",+ f"title_weight = {self.search_title_weight}",+ f"body_weight = {self.search_body_weight}",+ f"tags_weight = {self.search_tags_weight}",+ f"aliases_weight = {self.search_aliases_weight}",+ f"boost_evergreen = {self.search_boost_evergreen}",+ f"penalize_deprecated = {self.search_penalize_deprecated}",+ f"penalize_stale = {self.search_penalize_stale}",+ "",+ "[sync]",+ f"auto_sync = {'true' if self.auto_sync else 'false'}",+ f"exclude_patterns = {self._toml_array(self.exclude_patterns)}",+ "",+ "[index]",+ f"auto_build = {'true' if self.auto_build_index else 'false'}",+ f"pages = {self._toml_array(self.index_pages)}",+ ]+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text("\n".join(lines) + "\n")diff --git a/src/hyperresearch/core/db.py b/src/hyperresearch/core/db.pynew file mode 100644index 0000000..e122dd4--- /dev/null+++ b/src/hyperresearch/core/db.py@@ -0,0 +1,138 @@+"""SQLite database management — schema, connection, migrations."""++from __future__ import annotations++import sqlite3+from pathlib import Path++SCHEMA_VERSION = 2++SCHEMA_SQL = """+PRAGMA journal_mode=WAL;+PRAGMA foreign_keys=ON;++CREATE TABLE IF NOT EXISTS _meta (+ key TEXT PRIMARY KEY,+ value TEXT NOT NULL+);++CREATE TABLE IF NOT EXISTS notes (+ id TEXT PRIMARY KEY,+ title TEXT NOT NULL,+ path TEXT NOT NULL UNIQUE,+ status TEXT NOT NULL DEFAULT 'draft'+ CHECK (status IN ('draft','review','evergreen','stale','deprecated','archive')),+ type TEXT NOT NULL DEFAULT 'note'+ CHECK (type IN ('note','raw','index','moc')),+ source TEXT,+ parent TEXT,+ confidence REAL,+ superseded_by TEXT,+ deprecated INTEGER NOT NULL DEFAULT 0,+ reviewed TEXT,+ expires TEXT,+ llm_compiled INTEGER NOT NULL DEFAULT 0,+ llm_model TEXT,+ compile_source TEXT,+ word_count INTEGER NOT NULL DEFAULT 0,+ summary TEXT,+ created TEXT NOT NULL,+ updated TEXT,+ file_mtime REAL NOT NULL,+ content_hash TEXT NOT NULL,+ synced_at TEXT NOT NULL+);++CREATE INDEX IF NOT EXISTS idx_notes_status ON notes(status);+CREATE INDEX IF NOT EXISTS idx_notes_type ON notes(type);+CREATE INDEX IF NOT EXISTS idx_notes_parent ON notes(parent);+CREATE INDEX IF NOT EXISTS idx_notes_created ON notes(created);+CREATE INDEX IF NOT EXISTS idx_notes_updated ON notes(updated);+CREATE INDEX IF NOT EXISTS idx_notes_word_count ON notes(word_count);+CREATE INDEX IF NOT EXISTS idx_notes_status_type ON notes(status, type);+CREATE INDEX IF NOT EXISTS idx_notes_parent_status ON notes(parent, status);++CREATE TABLE IF NOT EXISTS note_content (+ note_id TEXT PRIMARY KEY REFERENCES notes(id) ON DELETE CASCADE,+ body TEXT NOT NULL,+ body_plain TEXT NOT NULL+);++CREATE TABLE IF NOT EXISTS tags (+ note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,+ tag TEXT NOT NULL,+ PRIMARY KEY (note_id, tag)+);++CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);++CREATE TABLE IF NOT EXISTS aliases (+ note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,+ alias TEXT NOT NULL,+ PRIMARY KEY (note_id, alias)+);++CREATE INDEX IF NOT EXISTS idx_aliases_alias ON aliases(alias COLLATE NOCASE);++CREATE TABLE IF NOT EXISTS links (+ source_id TEXT NOT NULL,+ target_ref TEXT NOT NULL,+ target_id TEXT,+ line_number INTEGER NOT NULL DEFAULT 0,+ context TEXT,+ PRIMARY KEY (source_id, target_ref, line_number)+);++CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_id);+CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);++CREATE TABLE IF NOT EXISTS embeddings (+ note_id TEXT PRIMARY KEY REFERENCES notes(id) ON DELETE CASCADE,+ model TEXT NOT NULL,+ dimensions INTEGER NOT NULL,+ vector BLOB NOT NULL,+ created_at TEXT NOT NULL+);++CREATE TABLE IF NOT EXISTS tag_aliases (+ alias TEXT PRIMARY KEY,+ canonical TEXT NOT NULL+);++"""++FTS_SQL = """+CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(+ id UNINDEXED,+ title,+ body_plain,+ tags,+ aliases,+ tokenize='porter unicode61'+);+"""+++def get_connection(db_path: Path) -> sqlite3.Connection:+ """Open a SQLite connection with WAL mode and FK enforcement."""+ db_path.parent.mkdir(parents=True, exist_ok=True)+ conn = sqlite3.connect(str(db_path))+ conn.row_factory = sqlite3.Row+ conn.execute("PRAGMA journal_mode=WAL")+ conn.execute("PRAGMA foreign_keys=ON")+ return conn+++def init_schema(conn: sqlite3.Connection) -> None:+ """Create all tables if they don't exist, then run pending migrations."""+ conn.executescript(SCHEMA_SQL)+ conn.executescript(FTS_SQL)+ conn.execute(+ "INSERT OR IGNORE INTO _meta (key, value) VALUES ('schema_version', ?)",+ (str(SCHEMA_VERSION),),+ )+ conn.commit()++ # Run any pending migrations+ from hyperresearch.core.migrations import migrate+ migrate(conn, SCHEMA_VERSION)diff --git a/src/hyperresearch/core/enrich.py b/src/hyperresearch/core/enrich.pynew file mode 100644index 0000000..87ba706--- /dev/null+++ b/src/hyperresearch/core/enrich.py@@ -0,0 +1,70 @@+"""Auto-enrichment: keyword-based tagging and first-line summary extraction."""++from __future__ import annotations++import re+++def auto_tag(body_plain: str, existing_tags: list[dict]) -> list[str]:+ """Suggest tags for a note based on keyword matching against existing tag vocabulary.++ Args:+ body_plain: Stripped plain text of the note body.+ existing_tags: List of {"tag": str, "count": int} from the vault.++ Returns:+ List of suggested tag strings (max 5).+ """+ if not body_plain or not existing_tags:+ return []++ body_lower = body_plain.lower()+ words = set(body_lower.split())++ scored = []+ for entry in existing_tags:+ tag = entry["tag"]+ count = entry["count"]+ # Check if tag (or hyphenated parts) appear in body+ tag_words = set(tag.replace("-", " ").split())+ matches = tag_words & words+ if matches:+ # Score: fraction of tag words found * log popularity+ import math+ frac = len(matches) / len(tag_words)+ score = frac * (1 + math.log(max(count, 1)))+ scored.append((tag, score))++ scored.sort(key=lambda x: x[1], reverse=True)+ return [tag for tag, _ in scored[:5]]+++def auto_summary(body: str) -> str | None:+ """Extract a summary from the first meaningful line of the body.++ Skips headings, blank lines, and very short lines. Truncates to 120 chars.+ """+ for line in body.split("\n"):+ stripped = line.strip()+ # Skip headings, blank lines, short lines, frontmatter markers+ if not stripped:+ continue+ if stripped.startswith("#"):+ continue+ if stripped.startswith("---"):+ continue+ if stripped.startswith("*Stub"):+ continue+ if len(stripped) < 25:+ continue+ # Strip markdown formatting+ clean = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", stripped)+ clean = re.sub(r"\[\[([^\]|]+)(?:\|[^\]]+)?\]\]", r"\1", clean)+ clean = re.sub(r"[*_`]", "", clean)+ clean = clean.strip()+ if len(clean) < 25:+ continue+ if len(clean) > 120:+ return clean[:117] + "..."+ return clean+ return Nonediff --git a/src/hyperresearch/core/frontmatter.py b/src/hyperresearch/core/frontmatter.pynew file mode 100644index 0000000..50b68dc--- /dev/null+++ b/src/hyperresearch/core/frontmatter.py@@ -0,0 +1,55 @@+"""YAML frontmatter parsing and serialization."""++from __future__ import annotations++import re++import yaml++from hyperresearch.models.note import NoteMeta++FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)+++def parse_frontmatter(content: str) -> tuple[NoteMeta, str]:+ """Parse YAML frontmatter from markdown content.++ Returns (metadata, body) where body is the content after frontmatter.+ """+ match = FRONTMATTER_RE.match(content)+ if not match:+ return NoteMeta(title="Untitled"), content++ yaml_str = match.group(1)+ body = content[match.end():]++ data = yaml.safe_load(yaml_str) or {}+ if not isinstance(data, dict):+ return NoteMeta(title="Untitled"), content++ # Handle missing title gracefully+ if "title" not in data:+ data["title"] = "Untitled"++ meta = NoteMeta.model_validate(data)+ return meta, body+++def serialize_frontmatter(meta: NoteMeta) -> str:+ """Serialize NoteMeta to YAML frontmatter string."""+ data = meta.model_dump(mode="json", exclude_none=True, exclude_defaults=False)+ # Remove empty lists+ for key in ("tags", "aliases"):+ if key in data and not data[key]:+ del data[key]+ # Remove empty id+ if "id" in data and not data["id"]:+ del data["id"]++ yaml_str = yaml.dump(data, default_flow_style=False, sort_keys=False, allow_unicode=True)+ return f"---\n{yaml_str}---\n"+++def render_note(meta: NoteMeta, body: str) -> str:+ """Render a full markdown note with frontmatter + body."""+ return serialize_frontmatter(meta) + "\n" + bodydiff --git a/src/hyperresearch/core/migrations.py b/src/hyperresearch/core/migrations.pynew file mode 100644index 0000000..1748f25--- /dev/null+++ b/src/hyperresearch/core/migrations.py@@ -0,0 +1,46 @@+"""Schema migration system for hyperresearch SQLite databases."""++from __future__ import annotations++import sqlite3++# Each migration is a SQL script that upgrades from version N-1 to N.+# Migrations MUST be idempotent (safe to re-run).+MIGRATIONS: dict[int, str] = {+ 2: """+CREATE TABLE IF NOT EXISTS tag_aliases (+ alias TEXT PRIMARY KEY,+ canonical TEXT NOT NULL+);+""",+}+++def get_schema_version(conn: sqlite3.Connection) -> int:+ try:+ row = conn.execute("SELECT value FROM _meta WHERE key = 'schema_version'").fetchone()+ return int(row[0] if isinstance(row, tuple) else row["value"]) if row else 0+ except sqlite3.OperationalError:+ return 0+++def migrate(conn: sqlite3.Connection, target_version: int) -> list[int]:+ """Run pending migrations. Returns list of versions applied."""+ current = get_schema_version(conn)+ if current >= target_version:+ return []++ applied = []+ for version in range(current + 1, target_version + 1):+ sql = MIGRATIONS.get(version)+ if sql:+ conn.executescript(sql)+ conn.execute(+ "INSERT OR REPLACE INTO _meta (key, value) VALUES ('schema_version', ?)",+ (str(version),),+ )+ applied.append(version)++ if applied:+ conn.commit()+ return applieddiff --git a/src/hyperresearch/core/note.py b/src/hyperresearch/core/note.pynew file mode 100644index 0000000..e3fc684--- /dev/null+++ b/src/hyperresearch/core/note.py@@ -0,0 +1,112 @@+"""Note file operations — read, write, list from disk."""++from __future__ import annotations++import hashlib+import re+from datetime import UTC, datetime+from pathlib import Path++from hyperresearch.core.frontmatter import parse_frontmatter, render_note+from hyperresearch.core.patterns import CODE_BLOCK_RE, INLINE_CODE_RE, WIKI_LINK_RE+from hyperresearch.models.note import Note, NoteMeta, slugify+++def read_note(file_path: Path, vault_root: Path) -> Note:+ """Read a markdown file and parse into a Note."""+ raw_bytes = file_path.read_bytes()+ content_hash = hashlib.sha256(raw_bytes).hexdigest()+ content = raw_bytes.decode("utf-8-sig") # Handles BOM+ meta, body = parse_frontmatter(content)++ rel_path = file_path.relative_to(vault_root).as_posix()++ # Derive ID from filename if not set in frontmatter+ if not meta.id:+ meta.id = slugify(file_path.stem)++ # Extract outgoing wiki links+ cleaned = CODE_BLOCK_RE.sub("", body)+ cleaned = INLINE_CODE_RE.sub("", cleaned)+ raw_links = (m.group(1).strip().rstrip("\\") for m in WIKI_LINK_RE.finditer(cleaned))+ outgoing = list(dict.fromkeys(+ ref for ref in raw_links+ if ref and not ref.startswith(("http://", "https://", "ftp://", "mailto:"))+ ))++ # Word count (simple split)+ word_count = len(body.split())++ return Note(+ meta=meta,+ body=body,+ path=rel_path,+ content_hash=content_hash,+ word_count=word_count,+ outgoing_links=outgoing,+ )+++def write_note(+ notes_dir: Path,+ title: str,+ body: str = "",+ *,+ note_id: str | None = None,+ tags: list[str] | None = None,+ status: str = "draft",+ note_type: str = "note",+ parent: str | None = None,+ source: str | None = None,+ summary: str | None = None,+) -> Path:+ """Create a new note file on disk. Returns the file path.++ Args:+ notes_dir: The directory to write into (e.g. vault.notes_dir).+ """+ nid = note_id or slugify(title)+ meta = NoteMeta(+ title=title,+ id=nid,+ tags=tags or [],+ status=status,+ type=note_type,+ parent=parent,+ source=source,+ summary=summary,+ created=datetime.now(UTC),+ )++ # Determine output path, avoid collisions+ target_dir = notes_dir+ if parent:+ target_dir = target_dir / slugify(parent)+ target_dir.mkdir(parents=True, exist_ok=True)++ file_path = target_dir / f"{nid}.md"+ counter = 2+ while file_path.exists():+ file_path = target_dir / f"{nid}-{counter}.md"+ meta.id = f"{nid}-{counter}"+ counter += 1++ content = render_note(meta, body)+ file_path.write_text(content, encoding="utf-8")+ return file_path+++def strip_markdown(text: str) -> str:+ """Strip markdown formatting to plain text for FTS indexing."""+ text = CODE_BLOCK_RE.sub("", text)+ text = INLINE_CODE_RE.sub("", text)+ text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)+ text = re.sub(r"\*{1,3}([^*]+)\*{1,3}", r"\1", text)+ text = re.sub(r"_{1,3}([^_]+)_{1,3}", r"\1", text)+ text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)+ text = re.sub(r"\[\[([^\]|]+)\|([^\]]+)\]\]", r"\2", text)+ text = re.sub(r"\[\[([^\]]+)\]\]", r"\1", text)+ text = re.sub(r"!\[([^\]]*)\]\([^)]+\)", r"\1", text)+ text = re.sub(r"<[^>]+>", "", text)+ text = re.sub(r"\s+", " ", text)+ return text.strip()diff --git a/src/hyperresearch/core/patterns.py b/src/hyperresearch/core/patterns.pynew file mode 100644index 0000000..bd28465--- /dev/null+++ b/src/hyperresearch/core/patterns.py@@ -0,0 +1,12 @@+"""Shared regex patterns for wiki-link parsing."""++from __future__ import annotations++import re++# Match [[target]] and [[target|display text]]+WIKI_LINK_RE = re.compile(r"\[\[([^\]|]+)(?:\|[^\]]+)?\]\]")++# Code block patterns for stripping before link extraction+CODE_BLOCK_RE = re.compile(r"```.*?```", re.DOTALL)+INLINE_CODE_RE = re.compile(r"`[^`]+`")diff --git a/src/hyperresearch/core/similarity.py b/src/hyperresearch/core/similarity.pynew file mode 100644index 0000000..8b4982e--- /dev/null+++ b/src/hyperresearch/core/similarity.py@@ -0,0 +1,20 @@+"""Content similarity — shingle-based Jaccard for dedup and create-time checks."""++from __future__ import annotations+++def shingle(text: str, n: int = 3) -> set[str]:+ """Extract word-level n-grams (shingles) from text."""+ words = text.lower().split()+ if len(words) < n:+ return {" ".join(words)} if words else set()+ return {" ".join(words[i : i + n]) for i in range(len(words) - n + 1)}+++def jaccard(a: set, b: set) -> float:+ """Jaccard similarity between two sets."""+ if not a or not b:+ return 0.0+ intersection = len(a & b)+ union = len(a | b)+ return intersection / union if union else 0.0diff --git a/src/hyperresearch/core/sync.py b/src/hyperresearch/core/sync.pynew file mode 100644index 0000000..f5f7c5a--- /dev/null+++ b/src/hyperresearch/core/sync.py@@ -0,0 +1,314 @@+"""File-to-DB sync engine — the bridge between markdown files and SQLite."""++from __future__ import annotations++import hashlib+import sqlite3+import time+from dataclasses import dataclass, field+from datetime import UTC, datetime+from pathlib import Path++from hyperresearch.core.note import read_note, strip_markdown+from hyperresearch.core.patterns import CODE_BLOCK_RE, INLINE_CODE_RE, WIKI_LINK_RE+++@dataclass+class SyncPlan:+ to_add: list[Path] = field(default_factory=list)+ to_update: list[Path] = field(default_factory=list)+ to_delete: list[str] = field(default_factory=list) # relative paths+ unchanged: int = 0+++@dataclass+class SyncResult:+ added: int = 0+ updated: int = 0+ deleted: int = 0+ unchanged: int = 0+ errors: list[dict] = field(default_factory=list)+ duration_ms: float = 0+++def _should_exclude(rel_path: str, exclude_parts: list[str]) -> bool:+ """Fast exclusion check — match on first path component."""+ first = rel_path.split("/", 1)[0]+ return first in exclude_parts+++def compute_sync_plan(vault, force: bool = False) -> SyncPlan:+ """Compare disk state against DB state. Returns a plan."""+ plan = SyncPlan()++ # Only scan inside the research directory (notes/, index/)+ # This avoids walking .git/, .venv/, src/, etc. entirely+ kb_dir = vault.research_dir+ if not kb_dir.exists():+ return plan++ disk_files: dict[str, float] = {}+ for md_file in kb_dir.rglob("*.md"):+ rel = md_file.relative_to(vault.root).as_posix()+ disk_files[rel] = md_file.stat().st_mtime++ # Load DB state — only catch "table not found" on fresh vaults+ db_state: dict[str, tuple[float, str]] = {}+ try:+ for row in vault.db.execute("SELECT path, file_mtime, content_hash FROM notes"):+ db_state[row["path"]] = (row["file_mtime"], row["content_hash"])+ except sqlite3.OperationalError:+ # Table doesn't exist yet (fresh vault before schema init)+ pass++ for rel_path, mtime in disk_files.items():+ full_path = vault.root / rel_path+ if rel_path not in db_state:+ plan.to_add.append(full_path)+ elif force or abs(mtime - db_state[rel_path][0]) > 0.001:+ # mtime differs — verify with content hash (raw bytes)+ current_hash = hashlib.sha256(full_path.read_bytes()).hexdigest()+ if force or current_hash != db_state[rel_path][1]:+ plan.to_update.append(full_path)+ else:+ plan.unchanged += 1+ else:+ plan.unchanged += 1++ for db_path in db_state:+ if db_path not in disk_files:+ plan.to_delete.append(db_path)++ return plan+++def execute_sync(vault, plan: SyncPlan) -> SyncResult:+ """Execute the sync plan within a single transaction for atomicity."""+ result = SyncResult(unchanged=plan.unchanged)+ start = time.monotonic()+ now_iso = datetime.now(UTC).isoformat()++ conn = vault.db+ conn.execute("BEGIN IMMEDIATE")++ changed_ids: set[str] = set()++ try:+ # Process deletes+ for rel_path in plan.to_delete:+ try:+ row = conn.execute("SELECT id FROM notes WHERE path = ?", (rel_path,)).fetchone()+ if row:+ _delete_note_from_db(conn, row["id"])+ changed_ids.add(row["id"])+ result.deleted += 1+ except Exception as e:+ result.errors.append({"path": rel_path, "error": str(e)})++ # Process adds+ for file_path in plan.to_add:+ try:+ note = read_note(file_path, vault.root)+ _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)+ changed_ids.add(note.meta.id)+ result.added += 1+ except Exception as e:+ result.errors.append({"path": str(file_path), "error": str(e)})++ # Process updates+ for file_path in plan.to_update:+ try:+ note = read_note(file_path, vault.root)+ _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)+ changed_ids.add(note.meta.id)+ result.updated += 1+ except Exception as e:+ result.errors.append({"path": str(file_path), "error": str(e)})++ # Resolve links — only for changed notes' outgoing + incoming+ _resolve_links_incremental(conn, changed_ids)++ # Record sync timestamp+ conn.execute(+ "INSERT OR REPLACE INTO _meta (key, value) VALUES ('last_sync', ?)",+ (now_iso,),+ )+ conn.commit()+ except Exception:+ conn.rollback()+ raise++ result.duration_ms = (time.monotonic() - start) * 1000+ return result+++def _upsert_note_to_db(conn, note, synced_at: str, file_mtime: float = 0) -> None:+ """Insert or update a note and all related tables using proper UPSERT."""+ meta = note.meta+ created_iso = meta.created.isoformat() if meta.created else synced_at+ updated_iso = meta.updated.isoformat() if meta.updated else None++ reviewed_iso = meta.reviewed.isoformat() if meta.reviewed else None+ expires_iso = meta.expires.isoformat() if meta.expires else None++ # Use INSERT ... ON CONFLICT to avoid CASCADE deletes from INSERT OR REPLACE+ conn.execute(+ """+ INSERT INTO notes+ (id, title, path, status, type, source, parent, confidence,+ superseded_by, deprecated, reviewed, expires,+ llm_compiled, llm_model, compile_source, word_count, summary,+ created, updated, file_mtime, content_hash, synced_at)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ ON CONFLICT(id) DO UPDATE SET+ title=excluded.title, path=excluded.path, status=excluded.status,+ type=excluded.type, source=excluded.source, parent=excluded.parent,+ confidence=excluded.confidence,+ superseded_by=excluded.superseded_by, deprecated=excluded.deprecated,+ reviewed=excluded.reviewed, expires=excluded.expires,+ llm_compiled=excluded.llm_compiled,+ llm_model=excluded.llm_model, compile_source=excluded.compile_source,+ word_count=excluded.word_count, summary=excluded.summary,+ created=excluded.created, updated=excluded.updated,+ file_mtime=excluded.file_mtime, content_hash=excluded.content_hash,+ synced_at=excluded.synced_at+ """,+ (+ meta.id, meta.title, note.path, meta.status, meta.type,+ meta.source, meta.parent, meta.confidence,+ meta.superseded_by, 1 if meta.deprecated else 0,+ reviewed_iso, expires_iso,+ 1 if meta.llm_compiled else 0, meta.llm_model, meta.compile_source,+ note.word_count, meta.summary, created_iso, updated_iso,+ file_mtime, note.content_hash, synced_at,+ ),+ )++ # Update tags — resolve aliases before writing+ conn.execute("DELETE FROM tags WHERE note_id = ?", (meta.id,))+ alias_map = {}+ try:+ for row in conn.execute("SELECT alias, canonical FROM tag_aliases"):+ alias_map[row["alias"]] = row["canonical"]+ except Exception:+ pass+ for tag in meta.tags:+ resolved = alias_map.get(tag, tag)+ # Auto-normalize plurals: "transformers" -> "transformer" if singular exists+ if resolved.endswith("s") and len(resolved) > 3:+ singular = resolved[:-1]+ if singular in alias_map.values() or conn.execute(+ "SELECT 1 FROM tags WHERE tag = ? LIMIT 1", (singular,)+ ).fetchone():+ resolved = singular+ conn.execute("INSERT OR IGNORE INTO tags (note_id, tag) VALUES (?, ?)", (meta.id, resolved))++ # Update aliases+ conn.execute("DELETE FROM aliases WHERE note_id = ?", (meta.id,))+ for alias in meta.aliases:+ conn.execute("INSERT INTO aliases (note_id, alias) VALUES (?, ?)", (meta.id, alias))++ # Update content (UPSERT)+ body_plain = strip_markdown(note.body)+ conn.execute(+ """+ INSERT INTO note_content (note_id, body, body_plain) VALUES (?, ?, ?)+ ON CONFLICT(note_id) DO UPDATE SET body=excluded.body, body_plain=excluded.body_plain+ """,+ (meta.id, note.body, body_plain),+ )++ # Update FTS — delete then insert (FTS5 doesn't support ON CONFLICT)+ conn.execute("DELETE FROM notes_fts WHERE id = ?", (meta.id,))+ conn.execute(+ "INSERT INTO notes_fts (id, title, body_plain, tags, aliases) VALUES (?, ?, ?, ?, ?)",+ (meta.id, meta.title, body_plain, " ".join(meta.tags), " ".join(meta.aliases)),+ )++ # Update links — extract from original body (not stripped)+ conn.execute("DELETE FROM links WHERE source_id = ?", (meta.id,))+ cleaned = CODE_BLOCK_RE.sub("", note.body)+ cleaned = INLINE_CODE_RE.sub("", cleaned)+ for line_num, line in enumerate(cleaned.split("\n"), 1):+ for m in WIKI_LINK_RE.finditer(line):+ target_ref = m.group(1).strip().rstrip("\\") # Strip trailing backslash (shell escaping artifact)+ # Skip URLs — they're not note references+ if target_ref.startswith(("http://", "https://", "ftp://", "mailto:")):+ continue+ if not target_ref:+ continue+ conn.execute(+ "INSERT OR IGNORE INTO links (source_id, target_ref, line_number, context) "+ "VALUES (?, ?, ?, ?)",+ (meta.id, target_ref, line_num, line.strip()[:200]),+ )+++def _delete_note_from_db(conn, note_id: str) -> None:+ """Delete a note and all related data (CASCADE handles child tables)."""+ conn.execute("DELETE FROM notes_fts WHERE id = ?", (note_id,))+ conn.execute("DELETE FROM links WHERE source_id = ?", (note_id,))+ conn.execute("DELETE FROM notes WHERE id = ?", (note_id,))+++def _resolve_links_incremental(conn, changed_ids: set[str]) -> None:+ """Resolve links incrementally — only for links affected by changed notes.++ This handles two cases:+ 1. Outgoing links from changed notes need resolution+ 2. Unresolved links from ANY note might now resolve to a newly added note+ """+ if not changed_ids:+ return++ # Re-resolve outgoing links from changed notes+ placeholders = ",".join("?" for _ in changed_ids)+ ids = list(changed_ids)++ # Reset target_id for links from changed notes+ conn.execute(+ f"UPDATE links SET target_id = NULL WHERE source_id IN ({placeholders})", ids+ )++ # Also reset links that pointed TO deleted/changed notes (they may have moved)+ conn.execute(+ f"UPDATE links SET target_id = NULL WHERE target_id IN ({placeholders})", ids+ )++ # Now resolve all currently-NULL links (which includes the ones we just reset+ # plus any that were already broken and might now resolve)+ _resolve_null_links(conn)+++def _resolve_null_links(conn) -> None:+ """Resolve all links with target_id = NULL."""+ # Exact ID match+ conn.execute("""+ UPDATE links SET target_id = (+ SELECT n.id FROM notes n WHERE n.id = links.target_ref LIMIT 1+ )+ WHERE target_id IS NULL+ """)+ # Case-insensitive ID match+ conn.execute("""+ UPDATE links SET target_id = (+ SELECT n.id FROM notes n WHERE LOWER(n.id) = LOWER(links.target_ref) LIMIT 1+ )+ WHERE target_id IS NULL+ """)+ # Alias match+ conn.execute("""+ UPDATE links SET target_id = (+ SELECT a.note_id FROM aliases a+ WHERE LOWER(a.alias) = LOWER(links.target_ref)+ LIMIT 1+ )+ WHERE target_id IS NULL+ """)+ # Title match+ conn.execute("""+ UPDATE links SET target_id = (+ SELECT n.id FROM notes n WHERE LOWER(n.title) = LOWER(links.target_ref) LIMIT 1+ )+ WHERE target_id IS NULL+ """)diff --git a/src/hyperresearch/core/templates.py b/src/hyperresearch/core/templates.pynew file mode 100644index 0000000..98a6375--- /dev/null+++ b/src/hyperresearch/core/templates.py@@ -0,0 +1,210 @@+"""Built-in note templates."""++from __future__ import annotations++from datetime import UTC++BUILTIN_TEMPLATES: dict[str, str] = {+ "note": """\+---+title: "{{ title }}"+id: "{{ id }}"+tags: [{{ tags }}]+status: draft+type: note+created: {{ created }}+---++# {{ title }}++""",+ "concept": """\+---+title: "{{ title }}"+id: "{{ id }}"+tags: [{{ tags }}]+status: draft+type: note+summary: ""+created: {{ created }}+---++# {{ title }}++## Definition++_What is this concept?_++## Key Properties++-++## Examples++-++## Related++- [[]]+""",+ "reference": """\+---+title: "{{ title }}"+id: "{{ id }}"+tags: [{{ tags }}]+status: draft+type: raw+source: ""+summary: ""+confidence: 0.7+created: {{ created }}+---++# {{ title }}++## Citation++_Author, Title, Year. URL._++## Key Points++-++## Quotes++>++## My Notes++""",+ "guide": """\+---+title: "{{ title }}"+id: "{{ id }}"+tags: [{{ tags }}]+status: draft+type: note+summary: ""+created: {{ created }}+---++# {{ title }}++## Prerequisites++- [[]]++## Steps++### 1.++### 2.++### 3.++## Pitfalls++-++## See Also++- [[]]+""",+ "comparison": """\+---+title: "{{ title }}"+id: "{{ id }}"+tags: [{{ tags }}]+status: draft+type: note+summary: ""+created: {{ created }}+---++# {{ title }}++## Overview++_What are we comparing and why?_++## Comparison++| Criteria | Option A | Option B |+|----------|----------|----------|+| | | |+| | | |++## Verdict++## Related++- [[]]+""",+ "moc": """\+---+title: "{{ title }}"+id: "{{ id }}"+tags: [{{ tags }}]+status: draft+type: moc+summary: "Map of content for {{ title }}"+created: {{ created }}+---++# {{ title }}++## Core Concepts++- [[]]++## Guides++- [[]]++## References++- [[]]++## Open Questions++-+""",+}+++def get_template(name: str, templates_dir=None) -> str | None:+ """Get a template by name. Checks vault templates dir first, then built-ins."""+ if templates_dir:+ custom = templates_dir / f"{name}.md"+ if custom.exists():+ return custom.read_text(encoding="utf-8")+ return BUILTIN_TEMPLATES.get(name)+++def list_templates(templates_dir=None) -> list[dict]:+ """List available templates."""+ templates = []+ for name in BUILTIN_TEMPLATES:+ templates.append({"name": name, "source": "builtin"})++ if templates_dir and templates_dir.exists():+ for f in sorted(templates_dir.glob("*.md")):+ name = f.stem+ if name not in BUILTIN_TEMPLATES:+ templates.append({"name": name, "source": "custom"})+ return templates+++def render_template(template_str: str, title: str, note_id: str, tags: list[str]) -> str:+ """Render a template with Jinja2-like variable substitution."""+ from datetime import datetime++ now = datetime.now(UTC).isoformat()+ tags_str = ", ".join(tags) if tags else ""++ result = template_str+ result = result.replace("{{ title }}", title)+ result = result.replace("{{ id }}", note_id)+ result = result.replace("{{ tags }}", tags_str)+ result = result.replace("{{ created }}", now)+ return resultdiff --git a/src/hyperresearch/core/vault.py b/src/hyperresearch/core/vault.pynew file mode 100644index 0000000..785ac15--- /dev/null+++ b/src/hyperresearch/core/vault.py@@ -0,0 +1,153 @@+"""Vault discovery, initialization, and management."""++from __future__ import annotations++import sqlite3+from pathlib import Path++from hyperresearch.core.config import VaultConfig+from hyperresearch.core.db import get_connection, init_schema++HYPERRESEARCH_DIR = ".hyperresearch"+CONFIG_FILE = "config.toml"+DB_FILE = "hyperresearch.db"+++class VaultError(Exception):+ pass+++class Vault:+ """Represents a hyperresearch research base vault."""++ def __init__(self, root: Path) -> None:+ self.root = root.resolve()+ self.hyperresearch_dir = self.root / HYPERRESEARCH_DIR+ self.config_path = self.hyperresearch_dir / CONFIG_FILE+ self.db_path = self.hyperresearch_dir / DB_FILE+ self._conn: sqlite3.Connection | None = None+ self._config: VaultConfig | None = None++ @property+ def config(self) -> VaultConfig:+ if self._config is None:+ self._config = VaultConfig.load(self.config_path)+ return self._config++ @property+ def db(self) -> sqlite3.Connection:+ if self._conn is None:+ self._conn = get_connection(self.db_path)+ return self._conn++ @property+ def is_initialized(self) -> bool:+ return self.hyperresearch_dir.is_dir() and self.db_path.exists()++ # --- Path properties: single source of truth for directory layout ---++ @property+ def research_dir(self) -> Path:+ """The one visible directory at repo root (default: research/)."""+ return self.root / self.config.research_dir++ @property+ def notes_dir(self) -> Path:+ return self.research_dir / "notes"++ @property+ def index_dir(self) -> Path:+ return self.research_dir / "index"++ @property+ def templates_dir(self) -> Path:+ """Templates live inside .hyperresearch/ (hidden)."""+ return self.hyperresearch_dir / "templates"++ @property+ def exports_dir(self) -> Path:+ """Exports live inside .hyperresearch/ (hidden)."""+ return self.hyperresearch_dir / "exports"++ def close(self) -> None:+ if self._conn is not None:+ self._conn.close()+ self._conn = None++ def __enter__(self) -> Vault:+ return self++ def __exit__(self, *args) -> None:+ self.close()++ @staticmethod+ def init(root: Path, name: str = "Research Base", research_dir: str = "research", agents: list[str] | None = None) -> Vault:+ """Initialize a new vault at the given path."""+ root = root.resolve()+ hyperresearch_dir = root / HYPERRESEARCH_DIR++ if hyperresearch_dir.exists():+ raise VaultError(f"Vault already initialized at {root}")++ # Create .hyperresearch/ structure (hidden)+ hyperresearch_dir.mkdir(parents=True)+ (hyperresearch_dir / "templates").mkdir()+ (hyperresearch_dir / "exports").mkdir()++ # Create the one visible directory+ kb_dir = root / research_dir+ (kb_dir / "notes").mkdir(parents=True, exist_ok=True)+ (kb_dir / "index").mkdir(exist_ok=True)++ # Write config+ config = VaultConfig(name=name, research_dir=research_dir)+ config.save(hyperresearch_dir / CONFIG_FILE)++ # Initialize database+ vault = Vault(root)+ init_schema(vault.db)++ # Write default note template+ template_path = hyperresearch_dir / "templates" / "note.md"+ template_path.write_text(+ "---\n"+ "title: \"{{ title }}\"\n"+ "id: \"{{ id }}\"\n"+ "tags: []\n"+ "status: draft\n"+ "type: note\n"+ "created: {{ created }}\n"+ "---\n\n"+ "# {{ title }}\n\n"+ )++ # Inject hyperresearch docs into agent config files (CLAUDE.md, AGENTS.md)+ from hyperresearch.core.agent_docs import inject_agent_docs+ inject_agent_docs(root, agents=agents)++ return vault++ @staticmethod+ def discover(start: Path | None = None) -> Vault:+ """Walk up from start (default: cwd) to find a vault root."""+ current = (start or Path.cwd()).resolve()+ while True:+ if (current / HYPERRESEARCH_DIR).is_dir():+ return Vault(current)+ parent = current.parent+ if parent == current:+ break+ current = parent+ raise VaultError(+ "No hyperresearch vault found. Run 'hyperresearch init' to create one."+ )++ def auto_sync(self) -> None:+ """Run an incremental sync if auto_sync is enabled."""+ if not self.config.auto_sync:+ return+ from hyperresearch.core.sync import compute_sync_plan, execute_sync++ plan = compute_sync_plan(self)+ if plan.to_add or plan.to_update or plan.to_delete:+ execute_sync(self, plan)diff --git a/src/hyperresearch/export/__init__.py b/src/hyperresearch/export/__init__.pynew file mode 100644index 0000000..6b9304d--- /dev/null+++ b/src/hyperresearch/export/__init__.py@@ -0,0 +1 @@+"""Export formatters."""diff --git a/src/hyperresearch/graph/__init__.py b/src/hyperresearch/graph/__init__.pynew file mode 100644index 0000000..267c26c--- /dev/null+++ b/src/hyperresearch/graph/__init__.py@@ -0,0 +1 @@+"""Knowledge graph operations."""diff --git a/src/hyperresearch/indexgen/__init__.py b/src/hyperresearch/indexgen/__init__.pynew file mode 100644index 0000000..b9be36c--- /dev/null+++ b/src/hyperresearch/indexgen/__init__.py@@ -0,0 +1 @@+"""Auto-generated index page builder."""diff --git a/src/hyperresearch/indexgen/generator.py b/src/hyperresearch/indexgen/generator.pynew file mode 100644index 0000000..24a3273--- /dev/null+++ b/src/hyperresearch/indexgen/generator.py@@ -0,0 +1,256 @@+"""Index page generation — builds auto-maintained .md index files."""++from __future__ import annotations++from datetime import UTC, datetime+++class IndexGenerator:+ def __init__(self, vault) -> None:+ self.vault = vault+ self.index_dir = vault.index_dir+ self.index_dir.mkdir(exist_ok=True)++ def build_all(self) -> list[str]:+ """Build all index pages. Cleans up stale pages first."""+ # Delete all existing index pages before regenerating+ if self.index_dir.exists():+ for old_file in self.index_dir.glob("*.md"):+ old_file.unlink()++ built = []+ built.append(self._build_master_index())+ built.append(self._build_tags_index())+ built.extend(self._build_per_tag_indexes())+ built.append(self._build_recent())+ built.append(self._build_orphans())+ built.append(self._build_stats())+ built.append(self._build_raw_pending())+ built.extend(self._build_by_month())+ built.append(self._build_stale())+ built.append(self._build_most_linked())+ return [b for b in built if b]++ def _write_index(self, filename: str, title: str, body: str) -> str:+ now_iso = datetime.now(UTC).isoformat()+ content = (+ f"---\n"+ f"title: \"{title}\"\n"+ f"id: \"{filename.replace('.md', '')}\"\n"+ f"type: index\n"+ f"created: {now_iso}\n"+ f"updated: {now_iso}\n"+ f"---\n\n"+ f"{body}\n\n"+ f"---\n*Auto-generated by hyperresearch. Do not edit manually.*\n"+ )+ path = self.index_dir / filename+ path.write_text(content, encoding="utf-8")+ return f"index/{filename}"++ def _build_master_index(self) -> str:+ rows = self.vault.db.execute(+ "SELECT id, title, path, status, type, parent, word_count, summary "+ "FROM notes WHERE type NOT IN ('index') ORDER BY parent, title"+ ).fetchall()++ lines = ["# Master Index\n", f"**{len(rows)}** notes in vault.\n"]++ # Group by parent+ groups: dict[str, list] = {}+ for r in rows:+ parent = r["parent"] or "Uncategorized"+ groups.setdefault(parent, []).append(r)++ for parent, notes in sorted(groups.items()):+ lines.append(f"\n## {parent}\n")+ for n in notes:+ status_badge = f"`{n['status']}`"+ summary = f" — {n['summary']}" if n["summary"] else ""+ lines.append(f"- [[{n['id']}]] — {n['title']}{summary} {status_badge} ({n['word_count']} words)")++ return self._write_index("_index.md", "Master Index", "\n".join(lines))++ def _build_tags_index(self) -> str:+ rows = self.vault.db.execute(+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag ORDER BY count DESC"+ ).fetchall()++ lines = ["# Tags Index\n", f"**{len(rows)}** unique tags.\n"]+ for r in rows:+ # Only link to per-tag page if tag has 3+ notes (avoids index bloat)+ if r["count"] >= 3:+ lines.append(f"- **{r['tag']}** ({r['count']} notes) → [[_tag-{r['tag']}]]")+ else:+ lines.append(f"- **{r['tag']}** ({r['count']} notes)")++ return self._write_index("_tags.md", "Tags Index", "\n".join(lines))++ def _build_per_tag_indexes(self) -> list[str]:+ """Only generate per-tag index pages for tags with 3+ notes."""+ built = []+ tags = self.vault.db.execute(+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag HAVING c >= 3 ORDER BY tag"+ ).fetchall()+ for tag_row in tags:+ tag = tag_row["tag"]+ rows = self.vault.db.execute(+ "SELECT n.id, n.title, n.status, n.word_count, n.summary "+ "FROM notes n JOIN tags t ON n.id = t.note_id "+ "WHERE t.tag = ? ORDER BY n.title",+ (tag,),+ ).fetchall()+ lines = [f"# Tag: {tag}\n", f"**{len(rows)}** notes.\n"]+ for r in rows:+ summary = f" — {r['summary']}" if r["summary"] else ""+ lines.append(f"- [[{r['id']}]] — {r['title']}{summary} `{r['status']}`")+ built.append(self._write_index(f"_tag-{tag}.md", f"Tag: {tag}", "\n".join(lines)))+ return built++ def _build_recent(self) -> str:+ rows = self.vault.db.execute(+ "SELECT id, title, status, type, created, updated, word_count "+ "FROM notes WHERE type NOT IN ('index') "+ "ORDER BY COALESCE(updated, created) DESC LIMIT 50"+ ).fetchall()++ lines = ["# Recently Updated\n"]+ for r in rows:+ date = r["updated"] or r["created"]+ if date and len(date) > 10:+ date = date[:10]+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']}")++ return self._write_index("_recent.md", "Recently Updated", "\n".join(lines))++ def _build_orphans(self) -> str:+ rows = self.vault.db.execute("""+ SELECT n.id, n.title, n.path, n.status+ FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ ORDER BY n.title+ """).fetchall()++ lines = ["# Orphan Notes\n", f"**{len(rows)}** notes with no inbound or outbound links.\n"]+ if not rows:+ lines.append("*No orphans — all notes are connected!*")+ for r in rows:+ lines.append(f"- [[{r['id']}]] — {r['title']} ({r['path']})")++ return self._write_index("_orphans.md", "Orphan Notes", "\n".join(lines))++ def _build_stats(self) -> str:+ total = self.vault.db.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]+ total_words = self.vault.db.execute(+ "SELECT COALESCE(SUM(word_count), 0) as c FROM notes"+ ).fetchone()["c"]+ total_links = self.vault.db.execute("SELECT COUNT(*) as c FROM links").fetchone()["c"]+ broken = self.vault.db.execute(+ "SELECT COUNT(*) as c FROM links WHERE target_id IS NULL"+ ).fetchone()["c"]+ total_tags = self.vault.db.execute(+ "SELECT COUNT(DISTINCT tag) as c FROM tags"+ ).fetchone()["c"]++ by_status = {}+ for r in self.vault.db.execute("SELECT status, COUNT(*) as c FROM notes GROUP BY status"):+ by_status[r["status"]] = r["c"]++ by_type = {}+ for r in self.vault.db.execute("SELECT type, COUNT(*) as c FROM notes GROUP BY type"):+ by_type[r["type"]] = r["c"]++ lines = [+ "# Vault Statistics\n",+ "| Metric | Value |",+ "|--------|-------|",+ f"| Total notes | {total} |",+ f"| Total words | {total_words:,} |",+ f"| Unique tags | {total_tags} |",+ f"| Total links | {total_links} |",+ f"| Broken links | {broken} |",+ "",+ "## By Status\n",+ ]+ for s, c in sorted(by_status.items()):+ lines.append(f"- **{s}**: {c}")++ lines.append("\n## By Type\n")+ for t, c in sorted(by_type.items()):+ lines.append(f"- **{t}**: {c}")++ return self._write_index("_stats.md", "Vault Statistics", "\n".join(lines))++ def _build_raw_pending(self) -> str:+ rows = self.vault.db.execute(+ "SELECT id, title, path, created FROM notes WHERE type = 'raw' ORDER BY created DESC"+ ).fetchall()++ lines = ["# Unprocessed (Pending Compilation)\n", f"**{len(rows)}** raw notes awaiting compilation.\n"]+ for r in rows:+ date = r["created"][:10] if r["created"] and len(r["created"]) > 10 else r["created"]+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']}")++ return self._write_index("_raw-pending.md", "Raw Pending", "\n".join(lines))++ def _build_by_month(self) -> list[str]:+ """Generate per-month index pages for months with 3+ notes."""+ rows = self.vault.db.execute(+ "SELECT id, title, status, summary, created FROM notes "+ "WHERE type NOT IN ('index') AND created IS NOT NULL "+ "ORDER BY created DESC"+ ).fetchall()++ months: dict[str, list] = {}+ for r in rows:+ created = r["created"] or ""+ month = created[:7] if len(created) >= 7 else "unknown"+ months.setdefault(month, []).append(r)++ built = []+ for month, notes in sorted(months.items(), reverse=True):+ if len(notes) < 3 or month == "unknown":+ continue+ lines = [f"# Notes from {month}\n", f"**{len(notes)}** notes.\n"]+ for r in notes:+ date = (r["created"] or "")[:10]+ summary = f" — {r['summary']}" if r["summary"] else ""+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']}{summary}")+ built.append(self._write_index(f"_month-{month}.md", f"Month: {month}", "\n".join(lines)))+ return built++ def _build_stale(self) -> str:+ """Evergreen notes not updated in 6+ months — candidates for review."""+ from datetime import datetime, timedelta+ cutoff = (datetime.now(UTC) - timedelta(days=180)).isoformat()+ rows = self.vault.db.execute(+ "SELECT id, title, status, updated, created, word_count FROM notes "+ "WHERE status = 'evergreen' AND type NOT IN ('index') "+ "AND COALESCE(updated, created) < ? "+ "ORDER BY COALESCE(updated, created)",+ (cutoff,),+ ).fetchall()++ lines = ["# Stale Notes\n", f"**{len(rows)}** evergreen notes not updated in 6+ months.\n"]+ for r in rows:+ date = (r["updated"] or r["created"] or "")[:10]+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']} ({r['word_count']}w)")++ return self._write_index("_stale.md", "Stale Notes", "\n".join(lines))++ def _build_most_linked(self) -> str:+ """Top 30 notes by inbound link count."""+ rows = self.vault.db.execute(+ "SELECT l.target_id as id, n.title, COUNT(*) as inbound "+ "FROM links l JOIN notes n ON l.target_id = n.id "+ "WHERE l.target_id IS NOT NULL "+ "GROUP BY l.target_id ORDER BY inbound DESC LIMIT 30"+ ).fetchall()++ lines = ["# Most Linked Notes\n", f"Top {len(rows)} notes by inbound link count.\n"]+ for r in rows:+ lines.append(f"- [[{r['id']}]] — {r['title']} ({r['inbound']} inbound links)")++ return self._write_index("_most-linked.md", "Most Linked", "\n".join(lines))diff --git a/src/hyperresearch/mcp/__init__.py b/src/hyperresearch/mcp/__init__.pynew file mode 100644index 0000000..f269048--- /dev/null+++ b/src/hyperresearch/mcp/__init__.py@@ -0,0 +1 @@+"""MCP server for hyperresearch — exposes research base tools to any MCP-compatible agent."""diff --git a/src/hyperresearch/mcp/server.py b/src/hyperresearch/mcp/server.pynew file mode 100644index 0000000..3c12804--- /dev/null+++ b/src/hyperresearch/mcp/server.py@@ -0,0 +1,235 @@+"""hyperresearch MCP server — thin protocol layer over existing hyperresearch functions.++Exposes 8 tools for agents: search, read, read_many, list, backlinks, hubs, status, lint.+Read-only by design — agents create/edit notes via file operations, hyperresearch auto-syncs.+"""++from __future__ import annotations++import json++from mcp.server.fastmcp import FastMCP++server = FastMCP("hyperresearch", instructions=(+ "hyperresearch is an agent-driven research knowledge base. Use these tools to search, read, "+ "and navigate research notes with wiki-links, tags, and summaries. Notes live in the research/ "+ "directory as markdown files with YAML frontmatter. To create or edit notes, write "+ "files directly and they will be auto-indexed."+))++_vault = None+++def _get_vault():+ global _vault+ if _vault is None:+ from hyperresearch.core.vault import Vault+ _vault = Vault.discover()+ _vault.auto_sync()+ return _vault+++def search_notes(query: str, tag: str = "", status: str = "", parent: str = "", limit: int = 10) -> str:+ """Search the research base by text. Returns matching notes with titles, summaries, and full bodies.++ Args:+ query: Search query (supports natural language, FTS5 with porter stemming)+ tag: Filter by tag (comma-separated for multiple, AND logic)+ status: Filter by status (draft, review, evergreen, stale, deprecated, archive)+ parent: Filter by parent topic (e.g. "ml/deep-learning")+ limit: Max results to return (default 10)+ """+ vault = _get_vault()+ vault.auto_sync()+ from hyperresearch.search.filters import SearchFilters+ from hyperresearch.search.fts import search_fts+ tags = [t.strip() for t in tag.split(",") if t.strip()] or None+ filters = SearchFilters(tags=tags, status=status or None, parent=parent or None)+ ranking = {+ "title_weight": vault.config.search_title_weight,+ "body_weight": vault.config.search_body_weight,+ "tags_weight": vault.config.search_tags_weight,+ "aliases_weight": vault.config.search_aliases_weight,+ "boost_evergreen": vault.config.search_boost_evergreen,+ "penalize_deprecated": vault.config.search_penalize_deprecated,+ "penalize_stale": vault.config.search_penalize_stale,+ }+ results = search_fts(vault.db, query, filters=filters, limit=limit, ranking=ranking)+ for r in results:+ row = vault.db.execute("SELECT body FROM note_content WHERE note_id = ?", (r["id"],)).fetchone()+ r["body"] = row["body"] if row else ""+ return json.dumps(results, default=str)+++def read_note(note_id: str) -> str:+ """Read a single note by ID. Returns full metadata and body content.++ Args:+ note_id: The note's slug ID (e.g. "transformer-architecture")+ """+ vault = _get_vault()+ vault.auto_sync()+ row = vault.db.execute(+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?",+ (note_id,),+ ).fetchone()+ if not row:+ return json.dumps({"error": f"Note not found: {note_id}"})+ tag_row = vault.db.execute("SELECT GROUP_CONCAT(tag, ',') as tl FROM tags WHERE note_id = ?", (note_id,)).fetchone()+ tags = tag_row["tl"].split(",") if tag_row and tag_row["tl"] else []+ return json.dumps({+ "id": row["id"], "title": row["title"], "path": row["path"],+ "status": row["status"], "type": row["type"], "tags": tags,+ "created": row["created"], "updated": row["updated"],+ "word_count": row["word_count"], "summary": row["summary"],+ "source": row["source"], "parent": row["parent"], "body": row["body"],+ }, default=str)+++def read_many(note_ids: str) -> str:+ """Read multiple notes at once. Pass comma-separated IDs.++ Args:+ note_ids: Comma-separated note IDs (e.g. "auth-flow,session-mgmt,jwt-tokens")+ """+ vault = _get_vault()+ vault.auto_sync()+ ids = [nid.strip() for nid in note_ids.split(",") if nid.strip()]+ notes, not_found = [], []+ for nid in ids:+ row = vault.db.execute(+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?", (nid,)+ ).fetchone()+ if row:+ tag_row = vault.db.execute("SELECT GROUP_CONCAT(tag, ',') as tl FROM tags WHERE note_id = ?", (nid,)).fetchone()+ tags = tag_row["tl"].split(",") if tag_row and tag_row["tl"] else []+ notes.append({"id": row["id"], "title": row["title"], "status": row["status"],+ "tags": tags, "word_count": row["word_count"], "summary": row["summary"], "body": row["body"]})+ else:+ not_found.append(nid)+ return json.dumps({"notes": notes, "not_found": not_found}, default=str)+++def list_notes(status: str = "", tag: str = "", parent: str = "", sort: str = "updated", limit: int = 50) -> str:+ """List notes with optional filters. Returns summaries (no bodies).++ Args:+ status: Filter by status+ tag: Filter by tag+ parent: Filter by parent topic+ sort: Sort order (created, updated, title, words)+ limit: Max results (default 50, use 0 for all)+ """+ vault = _get_vault()+ vault.auto_sync()+ clauses, params = ["n.type NOT IN ('index')"], []+ if status:+ clauses.append("n.status = ?")+ params.append(status)+ if tag:+ clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")+ params.append(tag.lower())+ if parent:+ clauses.append("(n.parent = ? OR n.parent LIKE ?)")+ params.extend([parent, parent + "/%"])+ where = " AND ".join(clauses)+ sort_map = {"created": "n.created DESC", "updated": "COALESCE(n.updated, n.created) DESC",+ "title": "n.title ASC", "words": "n.word_count DESC"}+ order = sort_map.get(sort, "COALESCE(n.updated, n.created) DESC")+ effective_limit = 999999 if limit == 0 else limit+ rows = vault.db.execute(+ f"SELECT n.*, (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list "+ f"FROM notes n WHERE {where} ORDER BY {order} LIMIT ?", [*params, effective_limit]+ ).fetchall()+ notes = [{"id": r["id"], "title": r["title"], "status": r["status"],+ "tags": r["tag_list"].split(",") if r["tag_list"] else [],+ "word_count": r["word_count"], "summary": r["summary"]} for r in rows]+ return json.dumps(notes, default=str)+++def get_backlinks(note_id: str) -> str:+ """Get all notes that link TO a given note.++ Args:+ note_id: The target note ID+ """+ vault = _get_vault()+ vault.auto_sync()+ rows = vault.db.execute(+ "SELECT l.source_id, n.title, l.line_number, l.context "+ "FROM links l JOIN notes n ON l.source_id = n.id WHERE l.target_id = ? ORDER BY n.title",+ (note_id,),+ ).fetchall()+ backlinks = [{"source_id": r["source_id"], "title": r["title"],+ "line": r["line_number"], "context": r["context"]} for r in rows]+ return json.dumps({"note_id": note_id, "backlinks": backlinks, "count": len(backlinks)})+++def get_hubs(limit: int = 20) -> str:+ """Get the most-linked-to notes in the research base (hub notes).++ Args:+ limit: Max results (default 20)+ """+ vault = _get_vault()+ vault.auto_sync()+ rows = vault.db.execute(+ "SELECT l.target_id as id, n.title, COUNT(*) as inbound "+ "FROM links l JOIN notes n ON l.target_id = n.id "+ "WHERE l.target_id IS NOT NULL GROUP BY l.target_id ORDER BY inbound DESC LIMIT ?",+ (limit,),+ ).fetchall()+ return json.dumps([{"id": r["id"], "title": r["title"], "inbound_links": r["inbound"]} for r in rows])+++def vault_status() -> str:+ """Get vault health overview: note counts, tag distribution, link stats, word count."""+ vault = _get_vault()+ vault.auto_sync()+ conn = vault.db+ total = conn.execute("SELECT COUNT(*) as c FROM notes WHERE type NOT IN ('index')").fetchone()["c"]+ by_status = {r["status"]: r["c"] for r in conn.execute(+ "SELECT status, COUNT(*) as c FROM notes WHERE type NOT IN ('index') GROUP BY status")}+ tag_count = conn.execute("SELECT COUNT(DISTINCT tag) as c FROM tags").fetchone()["c"]+ top_tags = [{"tag": r["tag"], "count": r["count"]} for r in conn.execute(+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag ORDER BY count DESC LIMIT 10")]+ total_links = conn.execute("SELECT COUNT(*) as c FROM links").fetchone()["c"]+ broken = conn.execute("SELECT COUNT(*) as c FROM links WHERE target_id IS NULL").fetchone()["c"]+ total_words = conn.execute("SELECT COALESCE(SUM(word_count), 0) as c FROM notes").fetchone()["c"]+ return json.dumps({"vault_name": vault.config.name, "total_notes": total, "by_status": by_status,+ "unique_tags": tag_count, "top_tags": top_tags, "total_links": total_links,+ "broken_links": broken, "total_words": total_words})+++def lint_vault(rule: str = "") -> str:+ """Run health checks on the vault. Returns issues found.++ Args:+ rule: Specific rule to check (leave empty for all)+ """+ vault = _get_vault()+ vault.auto_sync()+ conn = vault.db+ issues: list[dict] = []+ rules = [rule] if rule else ["missing-tags", "missing-summary", "broken-links", "orphaned-notes"]+ if "missing-tags" in rules:+ for r in conn.execute("SELECT id FROM notes WHERE type NOT IN ('index','raw') AND id NOT IN (SELECT DISTINCT note_id FROM tags)"):+ issues.append({"rule": "missing-tags", "severity": "warning", "note_id": r["id"], "message": "No tags"})+ if "missing-summary" in rules:+ for r in conn.execute("SELECT id FROM notes WHERE type NOT IN ('index','raw') AND (summary IS NULL OR LENGTH(TRIM(COALESCE(summary, ''))) = 0)"):+ issues.append({"rule": "missing-summary", "severity": "warning", "note_id": r["id"], "message": "No summary"})+ if "broken-links" in rules:+ for r in conn.execute("SELECT source_id, target_ref FROM links WHERE target_id IS NULL"):+ issues.append({"rule": "broken-links", "severity": "warning", "note_id": r["source_id"], "message": f"Broken: [[{r['target_ref']}]]"})+ if "orphaned-notes" in rules:+ for r in conn.execute("SELECT id FROM notes WHERE type NOT IN ('index','raw') AND id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL) AND id NOT IN (SELECT DISTINCT source_id FROM links)"):+ issues.append({"rule": "orphaned-notes", "severity": "info", "note_id": r["id"], "message": "No links"})+ return json.dumps({"issues": issues, "total": len(issues), "warnings": sum(1 for i in issues if i["severity"] == "warning")})diff --git a/src/hyperresearch/models/__init__.py b/src/hyperresearch/models/__init__.pynew file mode 100644index 0000000..852edf5--- /dev/null+++ b/src/hyperresearch/models/__init__.py@@ -0,0 +1 @@+"""Pydantic models for hyperresearch data structures."""diff --git a/src/hyperresearch/models/graph.py b/src/hyperresearch/models/graph.pynew file mode 100644index 0000000..abd5ee3--- /dev/null+++ b/src/hyperresearch/models/graph.py@@ -0,0 +1,21 @@+"""Graph and link models."""++from __future__ import annotations++from pydantic import BaseModel+++class LinkEntry(BaseModel):+ source_id: str+ target_ref: str+ target_id: str | None+ line_number: int | None+ context: str = ""+++class BacklinkEntry(BaseModel):+ source_id: str+ source_title: str+ source_path: str+ line_number: int | None+ context: str = ""diff --git a/src/hyperresearch/models/note.py b/src/hyperresearch/models/note.pynew file mode 100644index 0000000..336fa8c--- /dev/null+++ b/src/hyperresearch/models/note.py@@ -0,0 +1,88 @@+"""Note and frontmatter models."""++from __future__ import annotations++import re+from datetime import UTC, datetime+from enum import StrEnum++from pydantic import BaseModel, Field, field_validator+++class NoteStatus(StrEnum):+ DRAFT = "draft"+ REVIEW = "review"+ EVERGREEN = "evergreen"+ STALE = "stale"+ DEPRECATED = "deprecated"+ ARCHIVE = "archive"+++class NoteType(StrEnum):+ NOTE = "note"+ RAW = "raw"+ INDEX = "index"+ MOC = "moc"+++def slugify(text: str) -> str:+ """Convert text to a URL-friendly slug. Preserves underscores."""+ text = text.lower().strip()+ text = re.sub(r"[^\w\s-]", "", text, flags=re.ASCII)+ text = re.sub(r"\s+", "-", text)+ text = re.sub(r"-+", "-", text)+ result = text.strip("-")+ if not result:+ # Fallback for titles with only special/non-ASCII characters+ import hashlib+ result = "note-" + hashlib.sha256(text.encode()).hexdigest()[:8]+ return result+++class NoteMeta(BaseModel):+ """YAML frontmatter schema for a hyperresearch note."""++ title: str+ id: str = ""+ tags: list[str] = Field(default_factory=list)+ created: datetime = Field(default_factory=lambda: datetime.now(UTC))+ updated: datetime | None = None+ source: str | None = None+ status: NoteStatus = NoteStatus.DRAFT+ type: NoteType = NoteType.NOTE+ aliases: list[str] = Field(default_factory=list)+ parent: str | None = None+ confidence: float | None = None+ superseded_by: str | None = None # Note ID that replaces this one+ deprecated: bool = False # Explicitly marked as outdated+ reviewed: datetime | None = None # Last time a human verified accuracy+ expires: datetime | None = None # Auto-stale after this date+ llm_compiled: bool = False+ llm_model: str | None = None+ compile_source: str | None = None+ summary: str | None = None++ @field_validator("tags", mode="before")+ @classmethod+ def lowercase_tags(cls, v: list[str]) -> list[str]:+ return [t.lower().strip() for t in v]++ @field_validator("id", mode="before")+ @classmethod+ def ensure_slug(cls, v: str) -> str:+ if v:+ return slugify(v)+ return v++ model_config = {"use_enum_values": True}+++class Note(BaseModel):+ """A full note: metadata + body + disk info."""++ meta: NoteMeta+ body: str+ path: str # Relative path from vault root+ content_hash: str = ""+ word_count: int = 0+ outgoing_links: list[str] = Field(default_factory=list)diff --git a/src/hyperresearch/models/output.py b/src/hyperresearch/models/output.pynew file mode 100644index 0000000..48df8c4--- /dev/null+++ b/src/hyperresearch/models/output.py@@ -0,0 +1,28 @@+"""Envelope models for consistent CLI output."""++from __future__ import annotations++from datetime import UTC, datetime+from typing import Any++from pydantic import BaseModel, Field+++class Envelope(BaseModel):+ """Standard JSON output wrapper for all commands."""++ ok: bool = True+ data: Any = None+ error: str | None = None+ error_code: str | None = None+ count: int | None = None+ vault: str | None = None+ timestamp: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())+++def success(data: Any, count: int | None = None, vault: str | None = None) -> Envelope:+ return Envelope(ok=True, data=data, count=count, vault=vault)+++def error(message: str, code: str = "ERROR", vault: str | None = None) -> Envelope:+ return Envelope(ok=False, error=message, error_code=code, vault=vault)diff --git a/src/hyperresearch/models/search.py b/src/hyperresearch/models/search.pynew file mode 100644index 0000000..2e7e6aa--- /dev/null+++ b/src/hyperresearch/models/search.py@@ -0,0 +1,24 @@+"""Search result models."""++from __future__ import annotations++from pydantic import BaseModel+++class SearchResult(BaseModel):+ id: str+ title: str+ path: str+ status: str+ tags: list[str]+ created: str+ updated: str | None+ score: float+ snippet: str = ""+++class SearchResponse(BaseModel):+ query: str+ filters: dict+ total: int+ results: list[SearchResult]diff --git a/src/hyperresearch/py.typed b/src/hyperresearch/py.typednew file mode 100644index 0000000..e69de29diff --git a/src/hyperresearch/search/__init__.py b/src/hyperresearch/search/__init__.pynew file mode 100644index 0000000..d08db2d--- /dev/null+++ b/src/hyperresearch/search/__init__.py@@ -0,0 +1 @@+"""Search engines for hyperresearch."""diff --git a/src/hyperresearch/search/filters.py b/src/hyperresearch/search/filters.pynew file mode 100644index 0000000..675a4b5--- /dev/null+++ b/src/hyperresearch/search/filters.py@@ -0,0 +1,95 @@+"""Structured field filter builder for search queries."""++from __future__ import annotations++from dataclasses import dataclass+++@dataclass+class SearchFilters:+ tags: list[str] | None = None+ status: str | None = None+ note_type: str | None = None+ after: str | None = None+ before: str | None = None+ path_glob: str | None = None+ parent: str | None = None+ min_words: int | None = None+ max_words: int | None = None+ # Graph-aware filters+ linked_from: str | None = None # Only notes linked FROM this note ID+ linked_to: str | None = None # Only notes that link TO this note ID+ min_inbound: int | None = None # Minimum inbound link count+ has_backlinks: bool | None = None # Must have at least one inbound link++ def to_sql(self, table_alias: str = "n") -> tuple[str, list]:+ """Build SQL WHERE clauses and parameters."""+ clauses: list[str] = []+ params: list = []++ if self.tags:+ for tag in self.tags:+ clauses.append(+ f"{table_alias}.id IN (SELECT note_id FROM tags WHERE tag = ?)"+ )+ params.append(tag.lower())++ if self.status:+ clauses.append(f"{table_alias}.status = ?")+ params.append(self.status)++ if self.note_type:+ clauses.append(f"{table_alias}.type = ?")+ params.append(self.note_type)++ if self.after:+ clauses.append(f"{table_alias}.created >= ?")+ params.append(self.after)++ if self.before:+ clauses.append(f"{table_alias}.created <= ?")+ params.append(self.before)++ if self.path_glob:+ clauses.append(f"{table_alias}.path GLOB ?")+ params.append(self.path_glob)++ if self.parent:+ clauses.append(f"{table_alias}.parent = ?")+ params.append(self.parent)++ if self.min_words is not None:+ clauses.append(f"{table_alias}.word_count >= ?")+ params.append(self.min_words)++ if self.max_words is not None:+ clauses.append(f"{table_alias}.word_count <= ?")+ params.append(self.max_words)++ # Graph-aware filters+ if self.linked_from:+ clauses.append(+ f"{table_alias}.id IN (SELECT target_id FROM links WHERE source_id = ? AND target_id IS NOT NULL)"+ )+ params.append(self.linked_from)++ if self.linked_to:+ clauses.append(+ f"{table_alias}.id IN (SELECT source_id FROM links WHERE target_id = ?)"+ )+ params.append(self.linked_to)++ if self.min_inbound is not None:+ clauses.append(+ f"{table_alias}.id IN (SELECT target_id FROM links WHERE target_id IS NOT NULL "+ f"GROUP BY target_id HAVING COUNT(*) >= ?)"+ )+ params.append(self.min_inbound)++ if self.has_backlinks is True:+ clauses.append(+ f"{table_alias}.id IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)"+ )++ where = " AND ".join(clauses) if clauses else "1=1"+ return where, paramsdiff --git a/src/hyperresearch/search/fts.py b/src/hyperresearch/search/fts.pynew file mode 100644index 0000000..abb2fb6--- /dev/null+++ b/src/hyperresearch/search/fts.py@@ -0,0 +1,139 @@+"""FTS5 full-text search engine."""++from __future__ import annotations++import re+import sqlite3++from hyperresearch.search.filters import SearchFilters+++def _split_alphanum(word: str) -> list[str]:+ """Split words where letters meet digits: 'mamba3' -> ['mamba', '3'],+ 'gpt4o' -> ['gpt', '4', 'o'], 'llama3.1' -> ['llama', '3', '1'].+ """+ # Insert space at letter/digit boundaries+ split = re.sub(r'([a-zA-Z])(\d)', r'\1 \2', word)+ split = re.sub(r'(\d)([a-zA-Z])', r'\1 \2', split)+ # Also split on dots/hyphens between digits (3.1 -> 3 1)+ split = re.sub(r'(\d)[.\-](\d)', r'\1 \2', split)+ return split.split()+++def preprocess_query(raw: str) -> str:+ """Transform user query into FTS5 query syntax.++ - Simple words get prefix matching: 'python async' -> 'python* async*'+ - Glued alphanumeric split: 'mamba3' -> 'mamba 3', 'gpt4o' -> 'gpt 4 o'+ - Quoted phrases stay exact: '"async await"' stays as-is+ - Handles special FTS5 operators: AND, OR, NOT, NEAR+ """+ if any(op in raw.upper() for op in (" AND ", " OR ", " NOT ", " NEAR(")):+ return raw++ parts = re.split(r'(".*?")', raw)+ processed = []+ for part in parts:+ if part.startswith('"'):+ processed.append(part)+ else:+ words = part.strip().split()+ for word in words:+ if word:+ clean = re.sub(r'[*^():{}]', '', word)+ if not clean:+ continue+ # Split glued alphanumeric (mamba3 -> mamba + 3)+ subwords = _split_alphanum(clean)+ for sw in subwords:+ if sw:+ processed.append(f'"{sw}"*')+ return " ".join(processed)+++def search_fts(+ conn: sqlite3.Connection,+ query: str,+ *,+ filters: SearchFilters | None = None,+ limit: int = 20,+ offset: int = 0,+ include_index: bool = False,+ ranking: dict | None = None,+) -> list[dict]:+ """Execute a full-text search against the notes_fts table."""+ fts_query = preprocess_query(query)++ filter_clause = ""+ filter_params: list = []+ if filters:+ where, filter_params = filters.to_sql("n")+ if where != "1=1":+ filter_clause = f"AND {where}"++ # Exclude auto-generated index pages by default+ index_clause = "" if include_index else "AND n.type != 'index'"++ # BM25 column weights from config (id=unindexed=0, title, body, tags, aliases)+ w = ranking or {}+ tw = w.get("title_weight", 10.0)+ bw = w.get("body_weight", 1.0)+ tgw = w.get("tags_weight", 5.0)+ aw = w.get("aliases_weight", 3.0)++ sql = f"""+ SELECT+ n.id, n.title, n.path, n.status, n.type,+ n.created, n.updated, n.word_count, n.summary,+ snippet(notes_fts, 2, '>>>', '<<<', '...', 64) as snippet,+ bm25(notes_fts, 0.0, {tw}, {bw}, {tgw}, {aw}) as score,+ (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list+ FROM notes_fts fts+ JOIN notes n ON fts.id = n.id+ WHERE notes_fts MATCH ?+ {filter_clause}+ {index_clause}+ ORDER BY score+ LIMIT ? OFFSET ?+ """++ params = [fts_query, *filter_params, limit, offset]++ try:+ rows = conn.execute(sql, params).fetchall()+ except sqlite3.OperationalError:+ return []++ results = []+ for row in rows:+ tag_list = row["tag_list"].split(",") if row["tag_list"] else []+ results.append({+ "id": row["id"],+ "title": row["title"],+ "path": row["path"],+ "status": row["status"],+ "type": row["type"],+ "tags": tag_list,+ "created": row["created"],+ "updated": row["updated"],+ "word_count": row["word_count"],+ "summary": row["summary"],+ "score": abs(row["score"]),+ "snippet": row["snippet"] or "",+ })++ # Apply status-based ranking adjustments+ if ranking:+ boost_evergreen = ranking.get("boost_evergreen", 1.0)+ penalize_deprecated = ranking.get("penalize_deprecated", 1.0)+ penalize_stale = ranking.get("penalize_stale", 1.0)+ for r in results:+ if r["status"] == "evergreen":+ r["score"] *= boost_evergreen+ elif r["status"] == "deprecated":+ r["score"] *= penalize_deprecated+ elif r["status"] == "stale":+ r["score"] *= penalize_stale+ results.sort(key=lambda x: x["score"], reverse=True)++ return resultsdiff --git a/src/hyperresearch/serve/__init__.py b/src/hyperresearch/serve/__init__.pynew file mode 100644index 0000000..5debc08--- /dev/null+++ b/src/hyperresearch/serve/__init__.py@@ -0,0 +1 @@+"""Lightweight web UI for browsing hyperresearch vaults."""diff --git a/src/hyperresearch/serve/renderer.py b/src/hyperresearch/serve/renderer.pynew file mode 100644index 0000000..d438af2--- /dev/null+++ b/src/hyperresearch/serve/renderer.py@@ -0,0 +1,124 @@+"""Markdown to HTML renderer with [[wiki-link]] resolution."""++from __future__ import annotations++import html+import re++# Simple markdown patterns+MD_PATTERNS = [+ # Headers+ (re.compile(r"^######\s+(.+)$", re.MULTILINE), r"<h6>\1</h6>"),+ (re.compile(r"^#####\s+(.+)$", re.MULTILINE), r"<h5>\1</h5>"),+ (re.compile(r"^####\s+(.+)$", re.MULTILINE), r"<h4>\1</h4>"),+ (re.compile(r"^###\s+(.+)$", re.MULTILINE), r"<h3>\1</h3>"),+ (re.compile(r"^##\s+(.+)$", re.MULTILINE), r"<h2>\1</h2>"),+ (re.compile(r"^#\s+(.+)$", re.MULTILINE), r"<h1>\1</h1>"),+ # Bold/italic+ (re.compile(r"\*\*\*(.+?)\*\*\*"), r"<strong><em>\1</em></strong>"),+ (re.compile(r"\*\*(.+?)\*\*"), r"<strong>\1</strong>"),+ (re.compile(r"\*(.+?)\*"), r"<em>\1</em>"),+ # Code+ (re.compile(r"`([^`]+)`"), r"<code>\1</code>"),+ # Links+ (re.compile(r"\[([^\]]+)\]\(([^)]+)\)"), r'<a href="\2">\1</a>'),+ # Images+ (re.compile(r"!\[([^\]]*)\]\(([^)]+)\)"), r'<img src="\2" alt="\1">'),+ # Horizontal rule+ (re.compile(r"^---+$", re.MULTILINE), r"<hr>"),+ # Blockquotes+ (re.compile(r"^>\s*(.+)$", re.MULTILINE), r"<blockquote>\1</blockquote>"),+]+++def render_markdown(body: str) -> str:+ """Convert markdown body to HTML, resolving [[wiki-links]]."""+ # Escape HTML first+ text = html.escape(body)++ # Handle code blocks (preserve them)+ code_blocks = []+ def save_code_block(m):+ code_blocks.append(m.group(0))+ return f"\x00CODE{len(code_blocks) - 1}\x00"++ text = re.sub(r"```(\w*)\n(.*?)```", save_code_block, text, flags=re.DOTALL)++ # Apply markdown patterns+ for pattern, replacement in MD_PATTERNS:+ text = pattern.sub(replacement, text)++ # Wiki links: [[target|display]] or [[target]]+ def replace_wiki_link(m):+ full = m.group(0)+ # Unescape the brackets that html.escape would have converted+ inner = full[2:-2] # strip [[ and ]]+ if "|" in inner:+ target, display = inner.split("|", 1)+ else:+ target = display = inner+ target = target.strip()+ display = display.strip()+ return f'<a href="/note/{target}" class="wiki-link">{display}</a>'++ text = re.sub(r"\[\[([^\]]+)\]\]", replace_wiki_link, text)++ # Lists (simple)+ text = re.sub(r"^- (.+)$", r"<li>\1</li>", text, flags=re.MULTILINE)+ text = re.sub(r"(<li>.*</li>\n?)+", lambda m: f"<ul>{m.group(0)}</ul>", text)++ # Tables+ lines = text.split("\n")+ in_table = False+ table_lines = []+ result_lines = []+ for line in lines:+ if "|" in line and line.strip().startswith("|"):+ if not in_table:+ in_table = True+ table_lines = []+ table_lines.append(line)+ else:+ if in_table:+ result_lines.append(_render_table(table_lines))+ in_table = False+ table_lines = []+ result_lines.append(line)+ if in_table:+ result_lines.append(_render_table(table_lines))+ text = "\n".join(result_lines)++ # Restore code blocks+ for i, block in enumerate(code_blocks):+ html.escape(block)+ lang_match = re.match(r"```(\w+)\n", block)+ lang = lang_match.group(1) if lang_match else ""+ code_content = re.sub(r"```\w*\n|```", "", block)+ code_html = f'<pre><code class="language-{lang}">{html.escape(code_content)}</code></pre>'+ text = text.replace(f"\x00CODE{i}\x00", code_html)++ # Paragraphs: wrap standalone lines+ text = re.sub(r"\n\n+", "\n</p>\n<p>\n", text)+ if not text.startswith("<"):+ text = "<p>\n" + text+ if not text.rstrip().endswith(">"):+ text = text + "\n</p>"++ return text+++def _render_table(lines: list[str]) -> str:+ """Render a markdown table to HTML."""+ if len(lines) < 2:+ return "\n".join(lines)++ rows = []+ for i, line in enumerate(lines):+ cells = [c.strip() for c in line.strip("|").split("|")]+ if i == 1 and all(re.match(r"^[-:]+$", c.strip()) for c in cells):+ continue # Skip separator row+ tag = "th" if i == 0 else "td"+ row = "".join(f"<{tag}>{c}</{tag}>" for c in cells)+ rows.append(f"<tr>{row}</tr>")++ return f'<table class="md-table">{"".join(rows)}</table>'diff --git a/src/hyperresearch/serve/server.py b/src/hyperresearch/serve/server.pynew file mode 100644index 0000000..46b2707--- /dev/null+++ b/src/hyperresearch/serve/server.py@@ -0,0 +1,588 @@+"""Lightweight HTTP server for browsing hyperresearch vaults."""++from __future__ import annotations++import html as html_mod+import json+import urllib.parse+from http.server import BaseHTTPRequestHandler, HTTPServer++from hyperresearch.serve.renderer import render_markdown++# -- Vintage cream & dark brown theme --+CSS = """+:root {+ --nav-width: 300px;+ --bg: #fdf6ec;+ --bg-alt: #f5ead6;+ --fg: #3b2f1e;+ --fg-dim: #7a6b57;+ --accent: #8b5e3c;+ --accent-light: #c4956a;+ --link: #6b4226;+ --link-hover: #8b5e3c;+ --nav-bg: #2c1e0f;+ --nav-fg: #e8d5b8;+ --nav-link: #d4b896;+ --nav-heading: #f0e0c8;+ --border: #d4c4a8;+ --tag-bg: #e8d5b8;+ --tag-fg: #5a3e24;+ --code-bg: #efe3cf;+ --pre-bg: #2c1e0f;+ --pre-fg: #e8d5b8;+}+* { margin: 0; padding: 0; box-sizing: border-box; }+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;+ line-height: 1.6; color: var(--fg); background: var(--bg); }+a { color: var(--link); text-decoration: none; border-bottom: 1px solid transparent; }+a:hover { border-bottom-color: var(--accent); }+.wiki-link { color: var(--accent); font-weight: 600; }++.layout { display: flex; min-height: 100vh; }+nav { width: var(--nav-width); min-width: 200px; max-width: 500px;+ background: var(--nav-bg); color: var(--nav-fg); padding: 1.2rem;+ position: fixed; height: 100vh; overflow-y: auto; resize: horizontal; overflow-x: hidden;+ display: flex; flex-direction: column; }+nav .nav-top { flex: 1; overflow-y: auto; min-height: 0; }+nav .nav-bottom { flex-shrink: 0; padding-top: 0.8rem; margin-top: 0.5rem;+ border-top: 1px solid rgba(255,255,255,0.1); }+nav .nav-bottom a { font-size: 0.9rem; padding: 6px 0; }+nav a { color: var(--nav-link); display: block; padding: 3px 0; font-size: 0.82rem;+ white-space: nowrap; overflow: hidden; text-overflow: ellipsis;+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;+ border: none; }+nav a:hover { color: #fff; }+nav h3 { color: var(--nav-heading); margin: 1.2rem 0 0.4rem 0; font-size: 0.7rem;+ text-transform: uppercase; letter-spacing: 0.08em;+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }+nav .brand { font-size: 1.2rem; font-weight: bold; color: #fff;+ letter-spacing: 0.02em; }+nav .brand-sub { font-size: 0.7rem; color: var(--fg-dim); margin-top: -0.2rem; margin-bottom: 1rem;+ font-family: -apple-system, sans-serif; }+.nav-handle { width: 5px; position: fixed; left: var(--nav-width); top: 0; height: 100vh;+ cursor: col-resize; background: transparent; z-index: 10; }+.nav-handle:hover { background: var(--accent-light); }++main { margin-left: var(--nav-width); padding: 2.5rem 3rem; max-width: 860px; flex: 1; }+main h1 { margin-bottom: 0.5rem; font-weight: 700; color: var(--fg); }+main h2 { margin-top: 2rem; margin-bottom: 0.5rem; border-bottom: 1px solid var(--border);+ padding-bottom: 0.3rem; color: var(--accent); }+main h3 { margin-top: 1.2rem; color: var(--fg); }++.meta { color: var(--fg-dim); font-size: 0.82rem; margin-bottom: 1.5rem;+ font-family: -apple-system, sans-serif; }+.meta .tag { background: var(--tag-bg); color: var(--tag-fg); padding: 2px 8px; border-radius: 3px;+ font-size: 0.72rem; margin-right: 4px; }+.meta .status { background: var(--bg-alt); color: var(--accent); padding: 2px 8px; border-radius: 3px;+ font-size: 0.72rem; border: 1px solid var(--border); }+.meta .status.deprecated { background: #f0d0c0; color: #8b3a2a; }+.meta .status.draft { background: #f5e6c8; color: #7a5a2a; }++.backlinks { background: var(--bg-alt); border: 1px solid var(--border);+ border-radius: 6px; padding: 1rem; margin-top: 2rem; }+.backlinks h3 { font-size: 0.85rem; margin-bottom: 0.5rem; color: var(--accent); }+.backlinks li { font-size: 0.82rem; }++code { background: var(--code-bg); padding: 2px 6px; border-radius: 3px; font-size: 0.88em; }+pre { background: var(--pre-bg); color: var(--pre-fg); padding: 1rem; border-radius: 6px;+ overflow-x: auto; margin: 1rem 0; font-size: 0.88rem; }+pre code { background: none; padding: 0; color: inherit; }++.md-table { border-collapse: collapse; margin: 1rem 0; }+.md-table th, .md-table td { border: 1px solid var(--border); padding: 8px 12px; text-align: left; }+.md-table th { background: var(--bg-alt); font-weight: 600; }+.md-table tr:nth-child(even) { background: var(--bg-alt); }++blockquote { border-left: 3px solid var(--accent-light); padding-left: 1rem;+ color: var(--fg-dim); margin: 1rem 0; font-style: italic; }+ul { margin: 0.5rem 0 0.5rem 1.5rem; }+li { margin: 0.2rem 0; }+hr { border: none; border-top: 1px solid var(--border); margin: 1.5rem 0; }++.search-box { margin-bottom: 1rem; }+.search-box input { width: 100%; padding: 7px 10px; border: 1px solid #5a4030;+ border-radius: 4px; background: #1e1208; color: var(--nav-fg);+ font-family: -apple-system, sans-serif; font-size: 0.85rem; }+.search-box input::placeholder { color: #7a6b57; }+.results .result { margin-bottom: 1.2rem; }+.results .result .title { font-weight: 600; }+.results .result .snippet { color: var(--fg-dim); font-size: 0.82rem;+ font-family: -apple-system, sans-serif; }+mark { background: #f0d8a0; color: var(--fg); padding: 1px 2px; border-radius: 2px; }++/* Graph page */+.graph-container { position: relative; width: 100%; height: calc(100vh - 120px);+ background: var(--bg-alt); border: 1px solid var(--border); border-radius: 6px; }+.graph-fullpage { height: 100vh; border: none; border-radius: 0;+ position: fixed; top: 0; left: var(--nav-width); right: 0; bottom: 0;+ width: calc(100vw - var(--nav-width)); z-index: 1; }+.graph-container canvas { width: 100%; height: 100%; cursor: grab; }+.graph-container canvas:active { cursor: grabbing; }+.graph-search { position: absolute; top: 12px; right: 12px; z-index: 5;+ padding: 6px 10px; border: 1px solid var(--border); border-radius: 4px;+ background: var(--bg); color: var(--fg); font-size: 0.85rem; width: 200px; }+.graph-info { position: absolute; bottom: 12px; left: 12px; z-index: 5;+ background: var(--bg); border: 1px solid var(--border); border-radius: 4px;+ padding: 6px 10px; font-size: 0.78rem; color: var(--fg-dim);+ font-family: -apple-system, sans-serif; pointer-events: none; }+"""++FAVICON = (+ "data:image/svg+xml,"+ "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'>"+ "<rect x='10' y='20' width='80' height='65' rx='4' fill='%232c1e0f' stroke='%238b5e3c' stroke-width='3'/>"+ "<rect x='20' y='10' width='60' height='15' rx='3' fill='%238b5e3c'/>"+ "<line x1='25' y1='42' x2='75' y2='42' stroke='%23d4b896' stroke-width='2'/>"+ "<line x1='25' y1='52' x2='65' y2='52' stroke='%23d4b896' stroke-width='2'/>"+ "<line x1='25' y1='62' x2='70' y2='62' stroke='%23d4b896' stroke-width='2'/>"+ "<circle cx='72' cy='72' r='8' fill='%238b5e3c'/>"+ "<line x1='72' y1='67' x2='72' y2='77' stroke='%23fdf6ec' stroke-width='2'/>"+ "<line x1='67' y1='72' x2='77' y2='72' stroke='%23fdf6ec' stroke-width='2'/>"+ "</svg>"+)++DRAG_JS = """+<script>+(function() {+ var handle = document.querySelector('.nav-handle');+ var nav = document.querySelector('nav');+ var dragging = false;+ if (!handle) return;+ handle.addEventListener('mousedown', function(e) { dragging = true; e.preventDefault(); });+ document.addEventListener('mousemove', function(e) {+ if (!dragging) return;+ var w = Math.min(Math.max(e.clientX, 200), 500);+ document.documentElement.style.setProperty('--nav-width', w + 'px');+ nav.style.width = w + 'px';+ });+ document.addEventListener('mouseup', function() { dragging = false; });+})();+</script>+"""++GRAPH_JS = """+<script>+(function() {+ var canvas = document.getElementById('graph-canvas');+ var ctx = canvas.getContext('2d');+ var info = document.getElementById('graph-info');+ var searchBox = document.getElementById('graph-search');+ var nodes = [], edges = [], nodeMap = {};+ var W, H, scale = 1, panX = 0, panY = 0, dragging = false, dragX = 0, dragY = 0;+ var hoverNode = null, searchTerm = '';++ function resize() { W = canvas.width = canvas.parentElement.clientWidth; H = canvas.height = canvas.parentElement.clientHeight; }+ window.addEventListener('resize', resize);+ resize();++ fetch('/api/graph').then(r => r.json()).then(function(data) {+ nodes = data.nodes; edges = data.edges;+ // Center around origin+ nodes.forEach(function(n, i) { nodeMap[n.id] = i; n.x = (Math.random()-0.5)*800; n.y = (Math.random()-0.5)*800; n.vx = 0; n.vy = 0; });+ simulate();+ });++ function fitToScreen() {+ if (nodes.length === 0) return;+ var minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;+ nodes.forEach(function(n) {+ if (n.x < minX) minX = n.x; if (n.x > maxX) maxX = n.x;+ if (n.y < minY) minY = n.y; if (n.y > maxY) maxY = n.y;+ });+ var gw = maxX - minX + 100, gh = maxY - minY + 100;+ var cx = (minX + maxX) / 2, cy = (minY + maxY) / 2;+ scale = Math.min(W / gw, H / gh) * 0.9;+ scale = Math.min(Math.max(scale, 0.02), 3);+ panX = -cx;+ panY = -cy;+ }++ function simulate() {+ var alpha = 1.0;+ function tick() {+ if (alpha < 0.001) { fitToScreen(); draw(); return; }+ alpha *= 0.98;+ // Repulsion+ for (var i = 0; i < nodes.length; i++) {+ for (var j = i+1; j < nodes.length; j++) {+ var dx = nodes[j].x - nodes[i].x, dy = nodes[j].y - nodes[i].y;+ var d2 = dx*dx + dy*dy + 1;+ var f = 800 / d2 * alpha;+ nodes[i].vx -= dx * f; nodes[i].vy -= dy * f;+ nodes[j].vx += dx * f; nodes[j].vy += dy * f;+ }+ }+ // Attraction along edges+ edges.forEach(function(e) {+ var si = nodeMap[e[0]], ti = nodeMap[e[1]];+ if (si === undefined || ti === undefined) return;+ var dx = nodes[ti].x - nodes[si].x, dy = nodes[ti].y - nodes[si].y;+ var d = Math.sqrt(dx*dx + dy*dy) + 1;+ var f = (d - 120) * 0.005 * alpha;+ nodes[si].vx += dx/d * f; nodes[si].vy += dy/d * f;+ nodes[ti].vx -= dx/d * f; nodes[ti].vy -= dy/d * f;+ });+ // Center gravity+ nodes.forEach(function(n) {+ n.vx += (0 - n.x) * 0.0005 * alpha;+ n.vy += (0 - n.y) * 0.0005 * alpha;+ n.vx *= 0.85; n.vy *= 0.85;+ n.x += n.vx; n.y += n.vy;+ });+ draw();+ requestAnimationFrame(tick);+ }+ tick();+ }++ function toScreen(x, y) { return [(x + panX) * scale + W/2, (y + panY) * scale + H/2]; }+ function toWorld(sx, sy) { return [(sx - W/2) / scale - panX, (sy - H/2) / scale - panY]; }++ function draw() {+ ctx.clearRect(0, 0, W, H);+ ctx.save();+ ctx.translate(W/2, H/2);+ ctx.scale(scale, scale);+ ctx.translate(panX, panY);++ // Edges+ ctx.strokeStyle = 'rgba(139,94,60,0.12)';+ ctx.lineWidth = 0.5 / scale;+ edges.forEach(function(e) {+ var si = nodeMap[e[0]], ti = nodeMap[e[1]];+ if (si === undefined || ti === undefined) return;+ var s = nodes[si], t = nodes[ti];+ var highlight = hoverNode && (s.id === hoverNode.id || t.id === hoverNode.id);+ if (highlight) { ctx.strokeStyle = 'rgba(139,94,60,0.6)'; ctx.lineWidth = 1.5 / scale; }+ ctx.beginPath(); ctx.moveTo(s.x, s.y); ctx.lineTo(t.x, t.y); ctx.stroke();+ if (highlight) { ctx.strokeStyle = 'rgba(139,94,60,0.12)'; ctx.lineWidth = 0.5 / scale; }+ });++ // Nodes+ var sl = searchTerm.toLowerCase();+ nodes.forEach(function(n) {+ var r = Math.max(3, Math.min(20, 3 + Math.pow(n.inbound, 0.7) * 1.5));+ var isHover = hoverNode && n.id === hoverNode.id;+ var isConnected = hoverNode && n.connected && n.connected.has(hoverNode.id);+ var isSearch = sl && n.title.toLowerCase().includes(sl);+ var alpha = (hoverNode && !isHover && !isConnected) ? 0.15 : 1;+ if (isSearch) alpha = 1;++ ctx.globalAlpha = alpha;+ ctx.fillStyle = isSearch ? '#c4652a' : isHover ? '#6b4226' : n.status === 'evergreen' ? '#8b5e3c' : n.status === 'draft' ? '#b8a080' : '#a08060';+ ctx.beginPath(); ctx.arc(n.x, n.y, r / scale, 0, Math.PI * 2); ctx.fill();++ if ((isHover || isSearch) && scale > 0.1) {+ ctx.fillStyle = '#3b2f1e';+ ctx.font = (11 / scale) + 'px -apple-system, sans-serif';+ ctx.fillText(n.title.substring(0, 40), n.x + r/scale + 4/scale, n.y + 3/scale);+ }+ ctx.globalAlpha = 1;+ });++ ctx.restore();+ if (hoverNode) info.textContent = hoverNode.title + ' (' + hoverNode.inbound + ' inbound)';+ else info.textContent = nodes.length + ' notes, ' + edges.length + ' links';+ }++ // Build connectivity sets for hover highlighting+ function buildConnections() {+ nodes.forEach(function(n) { n.connected = new Set(); });+ edges.forEach(function(e) {+ var si = nodeMap[e[0]], ti = nodeMap[e[1]];+ if (si !== undefined && ti !== undefined) {+ nodes[si].connected.add(e[1]);+ nodes[ti].connected.add(e[0]);+ }+ });+ }+ setTimeout(buildConnections, 1000);++ // Mouse interaction+ var mouseDown = false, lastMX = 0, lastMY = 0;+ canvas.addEventListener('wheel', function(e) {+ e.preventDefault();+ var factor = e.deltaY > 0 ? 0.9 : 1.1;+ scale = Math.min(Math.max(scale * factor, 0.02), 5);+ draw();+ });+ canvas.addEventListener('mousedown', function(e) { mouseDown = true; lastMX = e.clientX; lastMY = e.clientY; });+ canvas.addEventListener('mousemove', function(e) {+ if (mouseDown) {+ panX += (e.clientX - lastMX) / scale;+ panY += (e.clientY - lastMY) / scale;+ lastMX = e.clientX; lastMY = e.clientY;+ draw();+ } else {+ // Hit test for hover+ var rect = canvas.getBoundingClientRect();+ var wp = toWorld(e.clientX - rect.left, e.clientY - rect.top);+ hoverNode = null;+ for (var i = 0; i < nodes.length; i++) {+ var dx = nodes[i].x - wp[0], dy = nodes[i].y - wp[1];+ if (dx*dx + dy*dy < 100) { hoverNode = nodes[i]; break; }+ }+ canvas.style.cursor = hoverNode ? 'pointer' : 'grab';+ draw();+ }+ });+ canvas.addEventListener('mouseup', function() { mouseDown = false; });+ canvas.addEventListener('click', function() {+ if (hoverNode) window.location.href = '/note/' + hoverNode.id;+ });++ searchBox.addEventListener('input', function() { searchTerm = this.value; draw(); });+})();+</script>+"""+++class HyperresearchHandler(BaseHTTPRequestHandler):+ vault = None+ _db = None++ @property+ def db(self):+ if self.__class__._db is None:+ import sqlite3+ self.__class__._db = sqlite3.connect(str(self.__class__.vault.db_path), check_same_thread=False)+ self.__class__._db.row_factory = sqlite3.Row+ return self.__class__._db++ def do_GET(self):+ parsed = urllib.parse.urlparse(self.path)+ path = parsed.path+ query = urllib.parse.parse_qs(parsed.query)++ if path == "/" or path == "":+ self._serve_index()+ elif path.startswith("/note/"):+ note_id = urllib.parse.unquote(path[6:])+ self._serve_note(note_id)+ elif path.startswith("/tag/"):+ tag = urllib.parse.unquote(path[5:])+ self._serve_tag(tag)+ elif path == "/tags":+ self._serve_tags()+ elif path == "/search":+ q = query.get("q", [""])[0]+ self._serve_search(q)+ elif path == "/graph":+ self._serve_graph()+ elif path == "/api/graph":+ self._serve_graph_api()+ else:+ self._send(404, "<h1>Not Found</h1>")++ def _send(self, code: int, body_html: str, title: str = "Home", extra_head: str = "", extra_body: str = ""):+ nav = self._build_nav()+ full = f"""<!DOCTYPE html><html><head>+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">+<title>{title} | LLM-Hyperresearch</title>+<link rel="icon" href="{FAVICON}">+<style>{CSS}</style>{extra_head}</head>+<body><div class="layout"><nav>{nav}</nav><div class="nav-handle"></div><main>{body_html}</main></div>{DRAG_JS}{extra_body}</body></html>"""+ self.send_response(code)+ self.send_header("Content-Type", "text/html; charset=utf-8")+ self.end_headers()+ self.wfile.write(full.encode("utf-8"))++ def _send_json(self, data):+ body = json.dumps(data)+ self.send_response(200)+ self.send_header("Content-Type", "application/json")+ self.end_headers()+ self.wfile.write(body.encode("utf-8"))++ def _build_nav(self) -> str:+ vault = self.__class__.vault+ name = vault.config.name+ lines = [+ '<div class="nav-top">',+ '<div class="brand">LLM-Hyperresearch</div>',+ f'<div class="brand-sub">{html_mod.escape(name)}</div>',+ '<form action="/search"><div class="search-box">'+ '<input type="text" name="q" placeholder="Search..."></div></form>',+ '<a href="/">Home</a>',+ '<a href="/tags">Tags</a>',+ '<h3>Recent</h3>',+ ]+ rows = self.db.execute(+ "SELECT id, title FROM notes WHERE type NOT IN ('index') "+ "ORDER BY COALESCE(updated, created) DESC LIMIT 15"+ ).fetchall()+ for r in rows:+ lines.append(f'<a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a>')+ lines.append('</div>')+ lines.append(+ '<div class="nav-bottom">'+ '<a href="/graph" title="Knowledge Graph" style="display:flex;align-items:center;gap:6px">'+ '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'+ '<circle cx="5" cy="6" r="2.5"/><circle cx="19" cy="6" r="2.5"/>'+ '<circle cx="12" cy="18" r="2.5"/><circle cx="5" cy="18" r="2.5"/>'+ '<circle cx="19" cy="18" r="2.5"/><circle cx="12" cy="10" r="2.5"/>'+ '<line x1="7" y1="7" x2="10" y2="9"/><line x1="17" y1="7" x2="14" y2="9"/>'+ '<line x1="12" y1="12.5" x2="12" y2="15.5"/>'+ '<line x1="7" y1="17" x2="10" y2="16"/><line x1="17" y1="17" x2="14" y2="16"/>'+ '</svg>Graph</a></div>'+ )+ return "\n".join(lines)++ def _serve_index(self):+ rows = self.db.execute(+ "SELECT id, title, status, summary, word_count FROM notes "+ "WHERE type NOT IN ('index') ORDER BY title"+ ).fetchall()+ body = "<h1>All Notes</h1>\n<ul>\n"+ for r in rows:+ summary = f' <span style="color:var(--fg-dim);font-size:0.85rem">-- {html_mod.escape(r["summary"] or "")}</span>' if r["summary"] else ""+ body += f'<li><a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a>{summary}</li>\n'+ body += "</ul>"+ self._send(200, body, "Home")++ def _serve_note(self, note_id: str):+ row = self.db.execute(+ "SELECT n.*, nc.body FROM notes n "+ "JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?",+ (note_id,),+ ).fetchone()+ if not row:+ self._send(404, f"<h1>Note not found: {html_mod.escape(note_id)}</h1>")+ return++ tags = [r["tag"] for r in self.db.execute("SELECT tag FROM tags WHERE note_id = ?", (note_id,))]+ backlinks = self.db.execute(+ "SELECT l.source_id, n.title FROM links l "+ "JOIN notes n ON l.source_id = n.id WHERE l.target_id = ? ORDER BY n.title",+ (note_id,),+ ).fetchall()++ html_body = render_markdown(row["body"])+ tags_html = " ".join(f'<a href="/tag/{html_mod.escape(t)}" class="tag">{html_mod.escape(t)}</a>' for t in tags)+ status_class = row["status"]+ meta = (+ f'<div class="meta">'+ f'<span class="status {status_class}">{html_mod.escape(row["status"])}</span> '+ f'{tags_html} '+ f'<span>{row["word_count"]} words</span>'+ f'</div>'+ )+ bl_html = ""+ if backlinks:+ bl_items = "\n".join(+ f'<li><a href="/note/{html_mod.escape(r["source_id"])}">{html_mod.escape(r["title"])}</a></li>' for r in backlinks+ )+ bl_html = f'<div class="backlinks"><h3>Backlinks</h3><ul>{bl_items}</ul></div>'+ self._send(200, f"{meta}\n{html_body}\n{bl_html}", html_mod.escape(row["title"]))++ def _serve_tag(self, tag: str):+ rows = self.db.execute(+ "SELECT n.id, n.title, n.status, n.summary FROM notes n "+ "JOIN tags t ON n.id = t.note_id WHERE t.tag = ? ORDER BY n.title",+ (tag,),+ ).fetchall()+ safe_tag = html_mod.escape(tag)+ body = f"<h1>Tag: {safe_tag}</h1>\n<p>{len(rows)} notes</p>\n<ul>\n"+ for r in rows:+ summary = f' <span style="color:var(--fg-dim);font-size:0.85rem">-- {html_mod.escape(r["summary"] or "")}</span>' if r["summary"] else ""+ body += f'<li><a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a>{summary}</li>\n'+ body += "</ul>"+ self._send(200, body, f"Tag: {safe_tag}")++ def _serve_tags(self):+ rows = self.db.execute(+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC"+ ).fetchall()+ body = "<h1>All Tags</h1>\n<ul>\n"+ for r in rows:+ body += f'<li><a href="/tag/{html_mod.escape(r["tag"])}">{html_mod.escape(r["tag"])}</a> ({r["c"]})</li>\n'+ body += "</ul>"+ self._send(200, body, "Tags")++ def _serve_search(self, query: str):+ safe_q = html_mod.escape(query)+ body = f'<h1>Search: {safe_q}</h1>\n'+ if not query:+ body += "<p>Enter a search term.</p>"+ self._send(200, body, "Search")+ return++ from hyperresearch.search.fts import search_fts+ results = search_fts(self.db, query, limit=50)+ body += f"<p>{len(results)} results</p>\n<div class='results'>\n"+ for r in results:+ snippet = r["snippet"].replace(">>>", "<mark>").replace("<<<", "</mark>")+ body += (+ f'<div class="result"><div class="title">'+ f'<a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a></div>'+ f'<div class="snippet">{snippet}</div></div>\n'+ )+ body += "</div>"+ self._send(200, body, f"Search: {safe_q}")++ def _serve_graph(self):+ body = (+ '<div class="graph-container graph-fullpage">'+ '<canvas id="graph-canvas"></canvas>'+ '<input type="text" class="graph-search" id="graph-search" placeholder="Filter nodes...">'+ '<div class="graph-info" id="graph-info">Loading...</div>'+ '</div>'+ )+ self._send(200, body, "Graph", extra_body=GRAPH_JS)++ def _serve_graph_api(self):+ nodes_rows = self.db.execute(+ "SELECT n.id, n.title, n.status, n.word_count FROM notes n WHERE n.type NOT IN ('index')"+ ).fetchall()+ inbound_counts = {}+ for r in self.db.execute(+ "SELECT target_id, COUNT(*) as c FROM links WHERE target_id IS NOT NULL GROUP BY target_id"+ ):+ inbound_counts[r["target_id"]] = r["c"]++ nodes = [+ {"id": r["id"], "title": r["title"], "status": r["status"],+ "words": r["word_count"], "inbound": inbound_counts.get(r["id"], 0)}+ for r in nodes_rows+ ]+ edges_rows = self.db.execute(+ "SELECT DISTINCT source_id, target_id FROM links WHERE target_id IS NOT NULL"+ ).fetchall()+ edges = [[r["source_id"], r["target_id"]] for r in edges_rows]++ self._send_json({"nodes": nodes, "edges": edges})++ def log_message(self, format, *args):+ pass+++def run_server(vault, port: int = 8080, open_browser: bool = False):+ import signal+ import sys++ HyperresearchHandler.vault = vault+ server = HTTPServer(("127.0.0.1", port), HyperresearchHandler)+ server.timeout = 0.5 # Check for Ctrl+C every 500ms+ url = f"http://127.0.0.1:{port}"+ print(f"Serving at {url}")+ print("Press Ctrl+C to stop.\n")++ if open_browser:+ import webbrowser+ webbrowser.open(url)++ running = True++ def _shutdown(sig, frame):+ nonlocal running+ running = False++ signal.signal(signal.SIGINT, _shutdown)++ while running:+ server.handle_request()++ print("\nStopped.")+ server.server_close()+ sys.exit(0)diff --git a/tests/__init__.py b/tests/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/conftest.py b/tests/conftest.pynew file mode 100644index 0000000..505fc87--- /dev/null+++ b/tests/conftest.py@@ -0,0 +1,83 @@+"""Shared test fixtures."""++from __future__ import annotations++from pathlib import Path++import pytest++from hyperresearch.core.vault import Vault+++def tmp_vault(tmp_path: Path) -> Vault:+ """Create a temporary vault for testing."""+ vault = Vault.init(tmp_path / "test-vault", name="Test Vault")+ return vault+++def seeded_vault(tmp_vault: Vault) -> Vault:+ """A vault with sample notes pre-populated."""+ from hyperresearch.core.note import write_note++ # Create interconnected notes+ write_note(+ tmp_vault.notes_dir,+ "Python Async Patterns",+ body=(+ "# Python Async Patterns\n\n"+ "Python's async/await syntax enables concurrent I/O.\n\n"+ "See also [[concurrency]] and [[rust-ownership]].\n"+ ),+ tags=["python", "async", "concurrency"],+ status="evergreen",+ parent="python",+ summary="Guide to async/await in Python",+ )++ write_note(+ tmp_vault.notes_dir,+ "Rust Ownership",+ body=(+ "# Rust Ownership\n\n"+ "Rust's ownership model ensures memory safety without GC.\n\n"+ "Related: [[python-async-patterns]] and [[concurrency]].\n"+ ),+ tags=["rust", "memory", "concurrency"],+ status="evergreen",+ parent="rust",+ summary="Rust's ownership and borrowing system",+ )++ write_note(+ tmp_vault.notes_dir,+ "Concurrency",+ body=(+ "# Concurrency\n\n"+ "Fundamental patterns for concurrent programming.\n\n"+ "- [[python-async-patterns]]\n"+ "- [[rust-ownership]]\n"+ "- [[nonexistent-topic]]\n"+ ),+ tags=["concurrency", "concepts"],+ status="evergreen",+ note_type="moc",+ summary="Map of content for concurrency topics",+ )++ write_note(+ tmp_vault.notes_dir,+ "Orphan Note",+ body="# Orphan\n\nThis note links to nothing and nothing links to it.\n",+ tags=["test"],+ status="draft",+ )++ # Sync to populate DB+ from hyperresearch.core.sync import compute_sync_plan, execute_sync++ plan = compute_sync_plan(tmp_vault, force=True)+ execute_sync(tmp_vault, plan)++ return tmp_vaultdiff --git a/tests/test_cli/__init__.py b/tests/test_cli/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/test_cli/test_commands.py b/tests/test_cli/test_commands.pynew file mode 100644index 0000000..ad2af9b--- /dev/null+++ b/tests/test_cli/test_commands.py@@ -0,0 +1,176 @@+"""CLI integration tests using typer.testing.CliRunner."""++from __future__ import annotations++import json+import os+from pathlib import Path++import pytest+from typer.testing import CliRunner++from hyperresearch.cli import app++runner = CliRunner()+++def vault_dir(tmp_path: Path) -> Path:+ """Init a vault and return its path."""+ result = runner.invoke(app, ["init", str(tmp_path / "kb"), "--name", "CLI Test"])+ assert result.exit_code == 0+ return tmp_path / "kb"+++def test_init(tmp_path: Path):+ result = runner.invoke(app, ["init", str(tmp_path / "new-kb")])+ assert result.exit_code == 0+ assert "Initialized" in result.output+++def test_init_json(tmp_path: Path):+ result = runner.invoke(app, ["init", str(tmp_path / "json-kb"), "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["ok"] is True+ assert "vault_path" in data["data"]+++def test_init_double(tmp_path: Path):+ runner.invoke(app, ["init", str(tmp_path / "dup")])+ result = runner.invoke(app, ["init", str(tmp_path / "dup")])+ assert result.exit_code == 1+++def test_version():+ result = runner.invoke(app, ["--version"])+ assert result.exit_code == 0+ assert "hyperresearch v" in result.output+++def test_status(vault_dir: Path):+ os.chdir(vault_dir)+ result = runner.invoke(app, ["status"])+ assert result.exit_code == 0+ assert "CLI Test" in result.output+++def test_status_json(vault_dir: Path):+ os.chdir(vault_dir)+ result = runner.invoke(app, ["status", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["ok"] is True+ assert data["data"]["vault_name"] == "CLI Test"+++def test_note_new_and_list(vault_dir: Path):+ os.chdir(vault_dir)+ result = runner.invoke(app, ["note", "new", "Test Note", "--tag", "test"])+ assert result.exit_code == 0+ assert "Created" in result.output++ result = runner.invoke(app, ["sync"])+ assert result.exit_code == 0++ result = runner.invoke(app, ["note", "list", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["ok"] is True+ assert data["count"] >= 1+++def test_note_show(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Show Me", "--tag", "demo"])+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["note", "show", "show-me", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["data"]["title"] == "Show Me"+++def test_note_tags(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "A", "--tag", "alpha"])+ runner.invoke(app, ["note", "new", "B", "--tag", "beta"])+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["tags", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ tags = {t["tag"] for t in data["data"]}+ assert "alpha" in tags+ assert "beta" in tags+++def test_search_text(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Python Guide", "--tag", "python"])+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["search", "python", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["data"]["total"] >= 1+++def test_graph_broken(vault_dir: Path):+ os.chdir(vault_dir)+ # Create a note with a broken link+ (vault_dir / "research" / "notes" / "linker.md").write_text(+ "---\ntitle: Linker\nid: linker\nstatus: draft\ntype: note\n---\n\nSee [[nowhere]]\n",+ encoding="utf-8",+ )+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["graph", "broken", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["count"] >= 1+++def test_lint(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Lint Test"])+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["lint", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert "issues" in data["data"]+ assert "summary" in data["data"]+++def test_sync_dry_run(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Dry Run"])++ result = runner.invoke(app, ["sync", "--dry-run", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert "to_add" in data["data"]+++def test_index_build(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Indexed Note", "--tag", "idx"])+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["index", "build"])+ assert result.exit_code == 0+ assert "Built" in result.output++ result = runner.invoke(app, ["index", "list"])+ assert result.exit_code == 0+++def test_export_json(vault_dir: Path):+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Export Me"])+ runner.invoke(app, ["sync"])++ result = runner.invoke(app, ["export", "json", "--output", "exports/test.json"])+ assert result.exit_code == 0+ assert (vault_dir / "exports" / "test.json").exists()diff --git a/tests/test_cli/test_note_ops.py b/tests/test_cli/test_note_ops.pynew file mode 100644index 0000000..bc1be8f--- /dev/null+++ b/tests/test_cli/test_note_ops.py@@ -0,0 +1,70 @@+"""Tests for note mv, edit, rm CLI operations."""++from __future__ import annotations++import json+import os+from pathlib import Path++import pytest+from typer.testing import CliRunner++from hyperresearch.cli import app++runner = CliRunner()+++def vault_with_notes(tmp_path: Path) -> Path:+ vault_dir = tmp_path / "kb"+ runner.invoke(app, ["init", str(vault_dir)])+ os.chdir(vault_dir)+ runner.invoke(app, ["note", "new", "Alpha Note", "--tag", "test"])+ runner.invoke(app, ["note", "new", "Beta Note", "--tag", "test"])+ runner.invoke(app, ["sync"])+ return vault_dir+++def test_note_rm_json(vault_with_notes):+ result = runner.invoke(app, ["note", "rm", "alpha-note", "--force", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["ok"] is True+ assert data["data"]["deleted"] == "alpha-note"+++def test_note_rm_nonexistent(vault_with_notes):+ result = runner.invoke(app, ["note", "rm", "nonexistent", "--force", "--json"])+ assert result.exit_code == 1+++def test_note_mv(vault_with_notes):+ result = runner.invoke(+ app, ["note", "mv", "beta-note", "notes/moved/beta-note.md", "--json"]+ )+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["data"]["new_path"] == "notes/moved/beta-note.md"+ assert (vault_with_notes / "notes" / "moved" / "beta-note.md").exists()+++def test_note_show_raw(vault_with_notes):+ result = runner.invoke(app, ["note", "show", "alpha-note", "--raw"])+ assert result.exit_code == 0+ assert "---" in result.output+ assert "Alpha Note" in result.output+++def test_note_list_with_filters(vault_with_notes):+ result = runner.invoke(app, ["note", "list", "--tag", "test", "--json"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["count"] >= 2++ result = runner.invoke(app, ["note", "list", "--status", "draft", "--json"])+ data = json.loads(result.output)+ assert data["count"] >= 2++ result = runner.invoke(app, ["note", "list", "--sort", "title", "--limit", "1", "--json"])+ data = json.loads(result.output)+ assert data["count"] == 1diff --git a/tests/test_core/__init__.py b/tests/test_core/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/test_core/test_frontmatter.py b/tests/test_core/test_frontmatter.pynew file mode 100644index 0000000..9fd3510--- /dev/null+++ b/tests/test_core/test_frontmatter.py@@ -0,0 +1,72 @@+"""Tests for frontmatter parsing and serialization."""++from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter, render_note+from hyperresearch.models.note import NoteMeta+++def test_parse_basic_frontmatter():+ content = '---\ntitle: "Hello World"\nid: hello-world\ntags: [python, test]\nstatus: draft\ntype: note\n---\n\n# Hello\n'+ meta, body = parse_frontmatter(content)+ assert meta.title == "Hello World"+ assert meta.id == "hello-world"+ assert meta.tags == ["python", "test"]+ assert "# Hello" in body+++def test_parse_missing_frontmatter():+ content = "# Just markdown\n\nNo frontmatter here."+ meta, body = parse_frontmatter(content)+ assert meta.title == "Untitled"+ assert body == content+++def test_parse_empty_frontmatter():+ content = "---\n---\n\nBody here."+ meta, body = parse_frontmatter(content)+ assert meta.title == "Untitled"+++def test_serialize_roundtrip():+ meta = NoteMeta(+ title="Test Note",+ id="test-note",+ tags=["python", "test"],+ status="draft",+ type="note",+ )+ serialized = serialize_frontmatter(meta)+ assert "title: Test Note" in serialized+ assert "---" in serialized++ # Parse it back+ parsed, _ = parse_frontmatter(serialized + "\nBody text")+ assert parsed.title == "Test Note"+ assert parsed.id == "test-note"+ assert parsed.tags == ["python", "test"]+++def test_render_note():+ meta = NoteMeta(title="My Note", id="my-note")+ rendered = render_note(meta, "# Content\n\nHello!")+ assert rendered.startswith("---\n")+ assert "title: My Note" in rendered+ assert "# Content" in rendered+++def test_tags_lowercased():+ content = '---\ntitle: Test\ntags: [Python, ASYNC, Test]\n---\n\nBody'+ meta, _ = parse_frontmatter(content)+ assert meta.tags == ["python", "async", "test"]+++def test_windows_path_in_source():+ """Ensure Windows paths with backslashes are handled correctly."""+ meta = NoteMeta(+ title="Test",+ id="test",+ source=r"C:\Users\Jordan\file.md",+ )+ serialized = serialize_frontmatter(meta)+ # Should be valid YAML+ parsed, _ = parse_frontmatter(serialized + "\nBody")+ assert "Jordan" in (parsed.source or "")diff --git a/tests/test_core/test_note.py b/tests/test_core/test_note.pynew file mode 100644index 0000000..7cf1c0a--- /dev/null+++ b/tests/test_core/test_note.py@@ -0,0 +1,105 @@+"""Tests for note read/write operations."""++from pathlib import Path++from hyperresearch.core.note import read_note, write_note, strip_markdown+from hyperresearch.models.note import slugify+++def test_slugify_basic():+ assert slugify("Hello World") == "hello-world"+ assert slugify("Python 3.12 Features!") == "python-312-features"+ assert slugify(" spaces ") == "spaces"+ assert slugify("CamelCase") == "camelcase"+ assert slugify("dashes--double") == "dashes-double"+++def test_write_and_read_roundtrip(tmp_vault):+ path = write_note(+ tmp_vault.notes_dir,+ "Roundtrip Test",+ body="# Content\n\nSome text here.\n",+ tags=["test", "roundtrip"],+ status="evergreen",+ )+ assert path.exists()++ note = read_note(path, tmp_vault.root)+ assert note.meta.title == "Roundtrip Test"+ assert note.meta.id == "roundtrip-test"+ assert note.meta.tags == ["test", "roundtrip"]+ assert note.meta.status == "evergreen"+ assert "# Content" in note.body+ assert note.word_count > 0+++def test_write_avoids_collision(tmp_vault):+ p1 = write_note(tmp_vault.notes_dir, "Same Title")+ p2 = write_note(tmp_vault.notes_dir, "Same Title")+ assert p1 != p2+ assert p1.exists()+ assert p2.exists()+++def test_write_with_parent(tmp_vault):+ path = write_note(+ tmp_vault.notes_dir,+ "Child Note",+ parent="parent-topic",+ )+ assert "parent-topic" in str(path)+++def test_read_extracts_links(tmp_vault):+ path = write_note(+ tmp_vault.notes_dir,+ "Linking Note",+ body="See [[note-a]] and [[note-b|display text]].\n",+ )+ note = read_note(path, tmp_vault.root)+ assert "note-a" in note.outgoing_links+ assert "note-b" in note.outgoing_links+++def test_read_ignores_code_links(tmp_vault):+ path = write_note(+ tmp_vault.notes_dir,+ "Code Note",+ body="Real: [[real-link]]\n\n```python\nfake: [[fake-link]]\n```\n\nAlso `[[inline-fake]]`\n",+ )+ note = read_note(path, tmp_vault.root)+ assert "real-link" in note.outgoing_links+ assert "fake-link" not in note.outgoing_links+ assert "inline-fake" not in note.outgoing_links+++def test_strip_markdown():+ md = "# Header\n\n**Bold** and *italic*. See [[link|display]] and [url](http://example.com).\n\n```python\ncode\n```\n"+ plain = strip_markdown(md)+ assert "Header" in plain+ assert "Bold" in plain+ assert "display" in plain+ assert "url" in plain+ assert "```" not in plain+ assert "**" not in plain+ assert "[[" not in plain+++def test_read_utf8_content(tmp_vault):+ path = write_note(+ tmp_vault.notes_dir,+ "Unicode Note",+ body="# Umlaute: Aaou. CJK: . Emoji: .\n",+ )+ note = read_note(path, tmp_vault.root)+ assert "Aaou" in note.body+++def test_read_empty_body(tmp_vault):+ path = tmp_vault.notes_dir / "empty.md"+ path.parent.mkdir(exist_ok=True)+ path.write_text("---\ntitle: Empty\nid: empty\nstatus: draft\ntype: note\n---\n", encoding="utf-8")++ note = read_note(path, tmp_vault.root)+ assert note.meta.title == "Empty"+ assert note.body.strip() == ""diff --git a/tests/test_core/test_sync.py b/tests/test_core/test_sync.pynew file mode 100644index 0000000..a77c416--- /dev/null+++ b/tests/test_core/test_sync.py@@ -0,0 +1,98 @@+"""Tests for the sync engine."""++from hyperresearch.core.sync import compute_sync_plan, execute_sync+++def test_sync_adds_new_files(tmp_vault):+ from hyperresearch.core.note import write_note++ write_note(tmp_vault.notes_dir, "Note A", body="# A\n\nContent.", tags=["test"])+ write_note(tmp_vault.notes_dir, "Note B", body="# B\n\nMore content.", tags=["test"])++ plan = compute_sync_plan(tmp_vault)+ assert len(plan.to_add) == 2+ assert len(plan.to_delete) == 0++ result = execute_sync(tmp_vault, plan)+ assert result.added == 2+ assert result.errors == []++ # Verify in DB+ count = tmp_vault.db.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]+ assert count == 2+++def test_sync_detects_updates(tmp_vault):+ from hyperresearch.core.note import write_note++ path = write_note(tmp_vault.notes_dir, "Updatable", body="# V1\n\nOriginal.")+ plan = compute_sync_plan(tmp_vault)+ execute_sync(tmp_vault, plan)++ # Modify the file+ import time+ time.sleep(0.1)+ path.write_text(path.read_text().replace("Original", "Updated"), encoding="utf-8")++ plan2 = compute_sync_plan(tmp_vault)+ assert len(plan2.to_update) == 1+++def test_sync_detects_deletes(tmp_vault):+ from hyperresearch.core.note import write_note++ path = write_note(tmp_vault.notes_dir, "Deletable", body="# Delete me")+ plan = compute_sync_plan(tmp_vault)+ execute_sync(tmp_vault, plan)++ # Delete the file+ path.unlink()++ plan2 = compute_sync_plan(tmp_vault)+ assert len(plan2.to_delete) == 1++ result = execute_sync(tmp_vault, plan2)+ assert result.deleted == 1++ count = tmp_vault.db.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]+ assert count == 0+++def test_sync_populates_fts(seeded_vault):+ rows = seeded_vault.db.execute(+ "SELECT id FROM notes_fts WHERE notes_fts MATCH 'python'"+ ).fetchall()+ assert len(rows) > 0+++def test_sync_populates_tags(seeded_vault):+ rows = seeded_vault.db.execute(+ "SELECT DISTINCT tag FROM tags ORDER BY tag"+ ).fetchall()+ tags = [r["tag"] for r in rows]+ assert "python" in tags+ assert "rust" in tags+ assert "concurrency" in tags+++def test_sync_populates_links(seeded_vault):+ rows = seeded_vault.db.execute(+ "SELECT source_id, target_ref, target_id FROM links"+ ).fetchall()+ assert len(rows) > 0++ # Check that existing notes are resolved+ resolved = [r for r in rows if r["target_id"] is not None]+ assert len(resolved) > 0++ # Check that nonexistent-topic is unresolved+ broken = [r for r in rows if r["target_ref"] == "nonexistent-topic"]+ assert len(broken) == 1+ assert broken[0]["target_id"] is None+++def test_sync_excludes_hyperresearch_dir(tmp_vault):+ """Files in .hyperresearch/ should never be synced."""+ (tmp_vault.root / ".hyperresearch" / "test.md").write_text("---\ntitle: Bad\n---\nShould not sync")+ plan = compute_sync_plan(tmp_vault)+ assert all(".hyperresearch" not in str(p) for p in plan.to_add)diff --git a/tests/test_core/test_vault.py b/tests/test_core/test_vault.pynew file mode 100644index 0000000..9f80aa8--- /dev/null+++ b/tests/test_core/test_vault.py@@ -0,0 +1,67 @@+"""Tests for vault initialization and discovery."""++from pathlib import Path++import pytest++from hyperresearch.core.vault import Vault, VaultError+++def test_init_creates_structure(tmp_path: Path):+ vault = Vault.init(tmp_path / "kb", name="My KB")+ assert vault.is_initialized+ assert (vault.root / ".hyperresearch").is_dir()+ assert (vault.root / ".hyperresearch" / "config.toml").exists()+ assert (vault.root / ".hyperresearch" / "hyperresearch.db").exists()+ assert (vault.root / ".hyperresearch" / "templates").is_dir()+ assert (vault.root / ".hyperresearch" / "exports").is_dir()+ # One visible directory+ assert vault.research_dir.is_dir()+ assert vault.notes_dir.is_dir()+ assert vault.index_dir.is_dir()+++def test_init_custom_dir(tmp_path: Path):+ vault = Vault.init(tmp_path / "kb", name="Custom", research_dir="docs/wiki")+ assert (vault.root / "docs" / "wiki" / "notes").is_dir()+ assert vault.config.research_dir == "docs/wiki"+++def test_init_double_init_raises(tmp_path: Path):+ Vault.init(tmp_path / "kb")+ with pytest.raises(VaultError, match="already initialized"):+ Vault.init(tmp_path / "kb")+++def test_discover_finds_vault(tmp_path: Path):+ vault = Vault.init(tmp_path / "kb")+ # Discover from a subdirectory+ sub = vault.notes_dir / "deep"+ sub.mkdir(parents=True)+ found = Vault.discover(start=sub)+ assert found.root == vault.root+++def test_discover_raises_when_no_vault(tmp_path: Path):+ with pytest.raises(VaultError, match="No hyperresearch vault"):+ Vault.discover(start=tmp_path)+++def test_config_loaded(tmp_vault: Vault):+ assert tmp_vault.config.name == "Test Vault"+ assert tmp_vault.config.auto_sync is True+++def test_agent_docs_created(tmp_path: Path):+ vault = Vault.init(tmp_path / "kb")+ assert (vault.root / "CLAUDE.md").exists()+ content = (vault.root / "CLAUDE.md").read_text()+ assert "hyperresearch" in content+++def test_agent_docs_all(tmp_path: Path):+ vault = Vault.init(tmp_path / "kb-all", agents=["claude", "agents", "gemini", "copilot"])+ assert (vault.root / "CLAUDE.md").exists()+ assert (vault.root / "AGENTS.md").exists()+ assert (vault.root / "GEMINI.md").exists()+ assert (vault.root / ".github" / "copilot-instructions.md").exists()diff --git a/tests/test_graph/__init__.py b/tests/test_graph/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/test_graph/test_links.py b/tests/test_graph/test_links.pynew file mode 100644index 0000000..dc67713--- /dev/null+++ b/tests/test_graph/test_links.py@@ -0,0 +1,77 @@+"""Tests for link parsing and graph operations."""++from hyperresearch.core.note import WIKI_LINK_RE, CODE_BLOCK_RE, INLINE_CODE_RE+++def test_wiki_link_regex_simple():+ matches = WIKI_LINK_RE.findall("See [[python-async]] for details.")+ assert len(matches) == 1+ assert matches[0] == "python-async"+++def test_wiki_link_regex_with_display():+ text = "Check [[python-async|Python Async Guide]] here."+ matches = WIKI_LINK_RE.findall(text)+ assert len(matches) == 1+ # Group 1 is the target+ assert "python-async" in matches[0]+++def test_wiki_link_regex_multiple():+ text = "See [[note-a]], [[note-b]], and [[note-c|Note C]]."+ matches = WIKI_LINK_RE.findall(text)+ assert len(matches) == 3+++def test_wiki_link_not_in_code_block():+ text = "```python\n[[not-a-link]]\n```\n\n[[real-link]]"+ cleaned = CODE_BLOCK_RE.sub("", text)+ matches = WIKI_LINK_RE.findall(cleaned)+ assert len(matches) == 1+ assert "real-link" in matches[0]+++def test_wiki_link_not_in_inline_code():+ text = "Use `[[not-a-link]]` but also [[real-link]]"+ cleaned = INLINE_CODE_RE.sub("", text)+ matches = WIKI_LINK_RE.findall(cleaned)+ assert len(matches) == 1+ assert "real-link" in matches[0]+++def test_backlinks_populated(seeded_vault):+ """Concurrency links to python-async-patterns, so python-async-patterns should have a backlink."""+ rows = seeded_vault.db.execute(+ "SELECT source_id FROM links WHERE target_id = 'python-async-patterns'"+ ).fetchall()+ source_ids = [r["source_id"] for r in rows]+ assert "concurrency" in source_ids+++def test_broken_links_detected(seeded_vault):+ """The concurrency note links to nonexistent-topic which should be broken."""+ rows = seeded_vault.db.execute(+ "SELECT target_ref FROM links WHERE target_id IS NULL"+ ).fetchall()+ broken_refs = [r["target_ref"] for r in rows]+ assert "nonexistent-topic" in broken_refs+++def test_orphan_detection(seeded_vault):+ """The orphan note should have no links in or out."""+ rows = seeded_vault.db.execute("""+ SELECT n.id FROM notes n+ WHERE n.type NOT IN ('index', 'raw')+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)+ """).fetchall()+ orphan_ids = [r["id"] for r in rows]+ assert "orphan-note" in orphan_ids+++def test_hub_detection(seeded_vault):+ """python-async-patterns should be a hub (linked from multiple notes)."""+ row = seeded_vault.db.execute(+ "SELECT COUNT(*) as c FROM links WHERE target_id = 'python-async-patterns'"+ ).fetchone()+ assert row["c"] >= 2diff --git a/tests/test_search/__init__.py b/tests/test_search/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/test_search/test_fts.py b/tests/test_search/test_fts.pynew file mode 100644index 0000000..68869fb--- /dev/null+++ b/tests/test_search/test_fts.py@@ -0,0 +1,58 @@+"""Tests for full-text search."""++from hyperresearch.search.fts import search_fts, preprocess_query+from hyperresearch.search.filters import SearchFilters+++def test_preprocess_simple_query():+ assert '"python"*' in preprocess_query("python")+++def test_preprocess_quoted_phrase():+ result = preprocess_query('"async await"')+ assert '"async await"' in result+++def test_preprocess_passthrough_operators():+ query = "python AND async"+ assert preprocess_query(query) == query+++def test_search_returns_results(seeded_vault):+ results = search_fts(seeded_vault.db, "python")+ assert len(results) > 0+ assert any(r["id"] == "python-async-patterns" for r in results)+++def test_search_with_tag_filter(seeded_vault):+ filters = SearchFilters(tags=["rust"])+ results = search_fts(seeded_vault.db, "memory", filters=filters)+ assert all("rust" in r["tags"] for r in results)+++def test_search_with_status_filter(seeded_vault):+ filters = SearchFilters(status="draft")+ results = search_fts(seeded_vault.db, "orphan", filters=filters)+ assert all(r["status"] == "draft" for r in results)+++def test_search_no_results(seeded_vault):+ results = search_fts(seeded_vault.db, "zzzznonexistenttermzzzz")+ assert len(results) == 0+++def test_search_limit(seeded_vault):+ results = search_fts(seeded_vault.db, "concurrency", limit=1)+ assert len(results) <= 1+++def test_filter_by_date(seeded_vault):+ filters = SearchFilters(after="2020-01-01")+ results = search_fts(seeded_vault.db, "python", filters=filters)+ assert len(results) > 0+++def test_filter_by_path_glob(seeded_vault):+ filters = SearchFilters(path_glob="notes/python/*")+ results = search_fts(seeded_vault.db, "python", filters=filters)+ assert all("python" in r["path"] for r in results)