lorewiki 0.2.1__py3-none-any.whl

lorewiki/__init__.py

@@ -0,0 +1,4 @@
+"""LoreWiki - Local-first knowledge base for LLM-assisted coding."""
+
+__version__ = "0.2.1"
+__all__ = ["__version__"]

lorewiki/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI via ``python -m lorewiki``."""
+
+from lorewiki.cli import app
+
+if __name__ == "__main__":  # pragma: no cover - exercised by subprocess tests
+    app()

lorewiki/cli/__init__.py

@@ -0,0 +1,25 @@
+"""Top-level CLI package.
+
+Importing this package side-effect-imports every command module so
+that all ``@app.command()`` / ``@config_app.command()`` /
+``@topic_app.command()`` decorators fire. The single ``app`` symbol
+exposed here is what the ``lorewiki`` console-script entry point
+binds to.
+"""
+
+from __future__ import annotations
+
+# Order matters: ``apps`` first because every other module imports the
+# Typer instances / console from it. ``helpers`` is dependency-free.
+from lorewiki.cli import (
+    add,  # noqa: F401  (registers `lorewiki add`)
+    apps,  # noqa: F401  (side-effect: import decorators register)
+    commands,  # noqa: F401  (registers init / index / …)
+    config_cmds,  # noqa: F401  (registers config list / get / set)
+    helpers,  # noqa: F401  (side-effect: re-export symbols)
+    topic_cmds,  # noqa: F401  (registers topic …)
+)
+from lorewiki.cli.apps import app  # re-exported for the entry point
+from lorewiki.cli.helpers import print_phase_status  # re-exported for tests
+
+__all__ = ["app", "print_phase_status"]

lorewiki/cli/add.py

@@ -0,0 +1,324 @@
+"""``lorewiki add`` — author a single knowledge note from the CLI.
+
+The command takes a title (required) plus optional body/file/stdin
+content, module, and tags, and writes a Markdown file with a YAML
+frontmatter block into the active wiki. The index is re-built
+afterwards so the new doc is immediately retrievable.
+
+Path-traversal safety: the resolved target path is asserted to
+live inside the wiki root before any write. Title and module are
+slugified via the same rules used elsewhere (ascii / digits /
+hyphens; no path separators).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Any
+
+import frontmatter
+import typer
+from rich.panel import Panel
+
+from lorewiki.cli.apps import app, console, log
+from lorewiki.cli.helpers import resolve_config
+from lorewiki.indexer import build_index
+
+# ---------------------------------------------------------------------------
+# Slug + path safety helpers
+# ---------------------------------------------------------------------------
+
+_SLUG_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(text: str, *, max_len: int = 64) -> str:
+    """Turn ``"My Note!"`` into ``"my-note"``.
+
+    The slug is used as a filename inside the topic. Rules:
+    * Lowercase, ASCII alphanumerics + ``-`` only.
+    * Collapse runs of non-alphanumerics into a single ``-``.
+    * Trim leading / trailing ``-``.
+    * Cap at ``max_len`` chars (default 64) so we don't bust the
+      path component limit on Windows.
+    """
+    text = _SLUG_NON_ALNUM.sub("-", text.lower()).strip("-")
+    return text[:max_len] or "untitled"
+
+
+def _resolve_wiki_root(path_arg: str | None) -> Path:
+    """Return the absolute path of the wiki root the add should land in."""
+    cfg = resolve_config(path_arg)
+    return cfg.wiki_path.resolve()
+
+
+def _is_safe_target(wiki_root: Path, target: Path) -> bool:
+    """True iff ``target`` lives under ``wiki_root`` after resolution.
+
+    Blocks path-traversal attempts like ``--module ../../etc`` — the
+    slugified module may still end up containing ``..`` if the
+    caller asked for it literally, so we resolve both sides and
+    walk the ``Path.parents`` chain.
+    """
+    try:
+        target_resolved = target.resolve(strict=False)
+    except OSError:
+        return False
+    try:
+        root_resolved = wiki_root.resolve(strict=True)
+    except OSError:
+        return False
+    if target_resolved == root_resolved:
+        return False  # never write *at* the root itself
+    return root_resolved in target_resolved.parents
+
+
+# ---------------------------------------------------------------------------
+# Body acquisition
+# ---------------------------------------------------------------------------
+
+
+def _read_body(body: str | None, file: Path | None) -> str:
+    """Read the doc body from the first non-empty source.
+
+    Priority: ``--body`` → ``--file`` → ``sys.stdin`` (if not a TTY).
+    Returns the body text with a single trailing newline so the
+    frontmatter/body separator renders cleanly.
+    """
+    if body is not None and body.strip():
+        return body.rstrip() + "\n"
+    if file is not None:
+        return file.read_text(encoding="utf-8").rstrip() + "\n"
+    if not sys.stdin.isatty():
+        data = sys.stdin.read()
+        if data.strip():
+            return data.rstrip() + "\n"
+    msg = (
+        "no content provided: pass --body, --file, or pipe data on stdin "
+        "(stdin is only read when not a TTY)"
+    )
+    raise typer.BadParameter(msg)
+
+
+# ---------------------------------------------------------------------------
+# Title inference
+# ---------------------------------------------------------------------------
+
+H1_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+
+
+def _extract_h1(body: str) -> str | None:
+    """Return the first ``#`` heading of ``body``, or ``None``."""
+    match = H1_RE.search(body)
+    return match.group(1).strip() if match else None
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter construction
+# ---------------------------------------------------------------------------
+
+
+def _build_frontmatter(
+    *,
+    title: str,
+    module: str,
+    tags: Iterable[str],
+) -> dict[str, Any]:
+    """Return a dict suitable for ``frontmatter.dumps``.
+
+    The CLI always sets ``title`` and ``module``; ``tags`` is a
+    list and serialises as a YAML list. ``created_at`` and
+    ``last_review`` are pinned to the current UTC date so the
+    note has a usable staleness anchor out of the box.
+    """
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return {
+        "title": title,
+        "module": module,
+        "tags": list(tags),
+        "created_at": today,
+        "last_review": today,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def add(
+    title: Annotated[
+        str,
+        typer.Option(
+            "--title",
+            "-t",
+            help="Document title. (Required, but can be auto-derived from "
+            "the first H1 of the body when not given.)",
+        ),
+    ] = "",
+    body: Annotated[
+        str | None,
+        typer.Option(
+            "--body",
+            "-b",
+            help="Inline Markdown body. Mutually exclusive with --file / stdin.",
+        ),
+    ] = None,
+    file: Annotated[
+        Path | None,
+        typer.Option(
+            "--file",
+            "-f",
+            help="Path to a local file to import as the body.",
+        ),
+    ] = None,
+    module: Annotated[
+        str,
+        typer.Option(
+            "--module",
+            "-m",
+            help="Module / category directory (default: 'root').",
+        ),
+    ] = "root",
+    tag: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--tag",
+            help="Tag to attach (may be passed multiple times, e.g. "
+            "--tag python --tag design).",
+        ),
+    ] = None,
+    path: Annotated[
+        str | None,
+        typer.Option(
+            "--path",
+            "-p",
+            help="Project / wiki path. Defaults to the active topic.",
+        ),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Overwrite an existing file at the target path.",
+        ),
+    ] = False,
+    raw: Annotated[
+        bool,
+        typer.Option(
+            "--raw",
+            help="Emit a machine-readable JSON object on success.",
+        ),
+    ] = False,
+) -> None:
+    """Author a single knowledge note and re-index the wiki.
+
+    The body comes from one of (in priority order): ``--body``,
+    ``--file``, then ``sys.stdin`` if it is not a TTY. The
+    destination path is ``<wiki>/<module>/<slug>.md``; if that file
+    already exists the command refuses unless ``--force`` is set.
+
+    After a successful write, an incremental ``build_index`` runs so
+    the new doc is immediately retrievable via ``lorewiki search``.
+    """
+    # ---- 1. body & title ----------------------------------------------------
+    raw_body = _read_body(body, file)
+    final_title = title.strip() or _extract_h1(raw_body) or slugify(raw_body[:64])
+
+    # ---- 2. resolve paths ---------------------------------------------------
+    wiki_root = _resolve_wiki_root(path)
+    if not wiki_root.is_dir():
+        console.print(f"[red]wiki path not found:[/red] {wiki_root}")
+        raise typer.Exit(code=2)
+
+    module_slug = slugify(module) if module != "root" else "root"
+    title_slug = slugify(final_title)
+    target_dir = wiki_root / module_slug
+    target_path = target_dir / f"{title_slug}.md"
+
+    # ---- 3. path-traversal safety net -------------------------------------
+    if not _is_safe_target(wiki_root, target_path):
+        console.print(
+            Panel(
+                f"[red]Refusing to write outside the wiki root:[/red]\n"
+                f"  target:  {target_path}\n"
+                f"  wiki:    {wiki_root}\n"
+                f"Pass a safe --module / --title.",
+                title="path-traversal blocked",
+                border_style="red",
+            )
+        )
+        raise typer.Exit(code=3)
+
+    # ---- 4. conflict detection ---------------------------------------------
+    if target_path.exists() and not force:
+        console.print(
+            Panel(
+                f"[red]File already exists:[/red] {target_path}\n"
+                f"Pass [cyan]--force[/cyan] to overwrite.",
+                title="add: target exists",
+                border_style="red",
+            )
+        )
+        raise typer.Exit(code=4)
+
+    # ---- 5. write -----------------------------------------------------------
+    tags = list(tag) if tag else []
+    metadata = _build_frontmatter(title=final_title, module=module_slug, tags=tags)
+    post = frontmatter.Post(raw_body, **metadata)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        target_path.write_text(frontmatter.dumps(post) + "\n", encoding="utf-8")
+    except OSError as exc:
+        log.error("write failed {}: {}", target_path, exc)
+        console.print(f"[red]write failed:[/red] {exc}")
+        raise typer.Exit(code=5) from exc
+
+    # ---- 6. re-index --------------------------------------------------------
+    try:
+        cfg = resolve_config(path)
+        build_index(cfg, rebuild=False)
+    except Exception as exc:
+        # bug to swallow a successful write. Surface the warning and let the
+        # user re-run ``lorewiki index`` later.
+        log.warning("post-write reindex failed: {}", exc)
+        console.print(
+            f"[yellow]warning: reindex failed[/yellow] (the file is on disk, "
+            f"but you may want to run `lorewiki index`): {exc}"
+        )
+
+    # ---- 7. output ---------------------------------------------------------
+    if raw:
+        typer.echo(
+            json.dumps(
+                {
+                    "ok": True,
+                    "title": final_title,
+                    "module": module_slug,
+                    "path": str(target_path),
+                    "tags": tags,
+                },
+                ensure_ascii=False,
+            )
+        )
+        return
+
+    console.print(
+        Panel(
+            f"[green]wrote[/green] [bold]{target_path}[/bold]\n"
+            f"  title : {final_title}\n"
+            f"  module: {module_slug}\n"
+            f"  tags  : {', '.join(tags) if tags else '[dim](none)[/dim]'}\n\n"
+            f"Try: [cyan]lorewiki search \"{final_title}\"[/cyan]",
+            title="lorewiki add",
+            border_style="green",
+        )
+    )
+
+
+__all__ = ["add", "slugify"]

lorewiki/cli/apps.py

@@ -0,0 +1,181 @@
+"""Typer app instances, Rich console, and the ASCII banner.
+
+The :class:`Typer` instances live here (not in :mod:`lorewiki.cli.__init__`)
+so that the command modules can import them without dragging in
+the subcommand decorators, which would defeat Typer's lazy
+registration. ``__init__.py`` then imports the ``app`` symbol so the
+existing ``lorewiki.cli:app`` console-script entry point keeps working.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from typing import Annotated
+
+import click as _click
+import typer
+from rich.console import Console
+
+from lorewiki import __version__
+from lorewiki.utils.logger import get_logger
+
+console = Console()
+log = get_logger(__name__)
+
+
+def _force_utf8_streams() -> None:
+    """Force UTF-8 on stdout/stderr at import time.
+
+    Without this, ``--raw`` JSON containing CJK characters becomes
+    mojibake on Windows shells whose default code page is GBK
+    (cp936). Python 3.7+ exposes ``TextIOWrapper.reconfigure``; we
+    guard with ``hasattr`` so that non-standard stdouts captured by
+    tests don't crash the CLI.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            with contextlib.suppress(OSError, ValueError):
+                stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+
+
+_force_utf8_streams()
+
+
+# ---------------------------------------------------------------------------
+# ASCII banner
+# ---------------------------------------------------------------------------
+#
+# Hand-laid block-character logo, designed to render cleanly on Windows
+# Terminal / PowerShell 7+ / macOS Terminal. Six lines high, ~56 cols wide.
+_BANNER_LINES = (
+    " ██╗      ██████╗ ██████╗ ███████╗██╗    ██╗██╗██╗  ██╗██╗",
+    " ██║     ██╔═══██╗██╔══██╗██╔════╝██║    ██║██║██║ ██╔╝██║",
+    " ██║     ██║   ██║██████╔╝█████╗  ██║ █╗ ██║██║█████╔╝ ██║",
+    " ██║     ██║   ██║██╔══██╗██╔══╝  ██║███╗██║██║██╔═██╗ ██║",
+    " ███████╗╚██████╔╝██║  ██║███████╗╚███╔███╔╝██║██║  ██╗██║",
+    " ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚══╝╚══╝ ╚═╝╚═╝  ╚═╝╚═╝",
+)
+_BANNER_HELP = "\n".join(_BANNER_LINES) + "\n"
+
+
+def print_banner() -> None:
+    """Print the LOREWIKI block-character banner in cyan + bold."""
+    console.print(_BANNER_HELP.rstrip(), style="bold cyan", highlight=False)
+    console.print(
+        f"  [dim]local-first knowledge base \u00b7 v{__version__}[/dim]",
+        highlight=False,
+    )
+    console.print()
+
+
+app = typer.Typer(
+    name="lorewiki",
+    help="Local-first knowledge base for LLM-assisted coding.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+config_app = typer.Typer(
+    name="config",
+    help="View and edit LoreWiki configuration.",
+    no_args_is_help=True,
+)
+app.add_typer(config_app, name="config")
+
+topic_app = typer.Typer(
+    name="topic",
+    help=(
+        "Manage knowledge topics (your 'second-brain' vaults). "
+        "Each topic is an isolated index under ~/lorewiki/topics/<name>/."
+    ),
+    no_args_is_help=True,
+)
+app.add_typer(topic_app, name="topic")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print_banner()
+        raise typer.Exit()
+
+
+def _help_callback(ctx: typer.Context, value: bool) -> None:
+    """Top-level ``--help`` / ``-h`` shortcut that prepends the banner.
+
+    typer 0.9+ auto-generates ``--help`` *before* user code runs, so the
+    banner injection via :func:`_get_help_with_banner` never fires. We
+    therefore define an explicit ``--help`` option with ``is_eager=True``;
+    typer defers to the user-defined callback whenever an option with
+    that name exists. The standard typer-rendered help text is then
+    fetched via :meth:`typer.Context.get_help` so all subcommand /
+    option metadata still flows through the normal path.
+    """
+    if not value:
+        return
+    print_banner()
+    # typer's Context exposes ``get_help`` which delegates to click's
+    # ``Context.get_help`` on the bound click.Command, so the output
+    # matches what the auto-generated help would have shown.
+    console.print(ctx.get_help(), highlight=False)
+    raise typer.Exit(0)
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show LoreWiki version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+    help_: Annotated[
+        bool,
+        typer.Option(
+            "--help",
+            "-h",
+            help="Show this message and exit.",
+            callback=_help_callback,
+            is_eager=True,
+        ),
+    ] = False,
+    topic: Annotated[
+        str | None,
+        typer.Option(
+            "--topic",
+            "-t",
+            help=(
+                "Active knowledge topic for this invocation. Overrides "
+                "LOREWIKI_TOPIC env and ~/lorewiki/current. Use `lorewiki "
+                "topic list` to see available topics."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """LoreWiki CLI entrypoint."""
+    import os  # noqa: PLC0415
+
+    # Plumb the topic into the process environment so :func:`load_config`
+    # picks it up uniformly across CLI subcommands. We only set it
+    # when non-empty, so a bare ``--topic ""`` is a no-op rather than
+    # an explicit reset.
+    if topic:
+        os.environ["LOREWIKI_TOPIC"] = topic
+
+
+def _get_help_with_banner(self: typer.Typer, ctx: typer.Context) -> str:  # type: ignore[override]
+    return _BANNER_HELP + _click.Group.get_help(self, ctx)
+
+
+# Prepend the ASCII banner to every `--help` output. typer wraps each
+# :class:`Typer` in a click.Group at first dispatch, so the `get_help`
+# method only materialises on the instance — we rebind it here.
+app.get_help = _get_help_with_banner  # type: ignore[method-assign]
+
+
+__all__ = ["app", "config_app", "console", "log", "print_banner", "topic_app"]