confluence-knowledge 0.3.1__tar.gz → 0.4.1__tar.gz

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluence-knowledge
-Version: 0.3.1
+Version: 0.4.1
 Summary: Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service
 License: MIT
 Project-URL: Repository, https://github.com/nkunal1992/agents
@@ -21,6 +21,11 @@ Requires-Dist: pip-system-certs>=5.0
 Provides-Extra: models
 Requires-Dist: sentence-transformers<4.0,>=3.0; extra == "models"
 Requires-Dist: huggingface-hub>=0.26; extra == "models"
+Provides-Extra: files
+Requires-Dist: python-docx>=1.1; extra == "files"
+Requires-Dist: pypdf>=4.0; extra == "files"
+Requires-Dist: python-pptx>=1.0; extra == "files"
+Requires-Dist: openpyxl>=3.1; extra == "files"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "confluence-knowledge"
-version = "0.3.1"
+version = "0.4.1"
 description = "Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -34,6 +34,12 @@ models = [
     "sentence-transformers>=3.0,<4.0",
     "huggingface-hub>=0.26",
 ]
+files = [
+    "python-docx>=1.1",
+    "pypdf>=4.0",
+    "python-pptx>=1.0",
+    "openpyxl>=3.1",
+]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge/auth.py

@@ -18,36 +18,38 @@ ENV_TOKEN = "CONF_KNOWLEDGE_TOKEN"
 ENV_EMAIL = "CONF_KNOWLEDGE_EMAIL"
 
 
-def _keyring_store(ref: str, secret: str) -> bool:
+def _keyring_store(ref: str, secret: str, service: str = SERVICE) -> bool:
     try:
         import keyring
         from keyring.backends.fail import Keyring as FailBackend
         if isinstance(keyring.get_keyring(), FailBackend):
             return False
-        keyring.set_password(SERVICE, ref, secret)
+        keyring.set_password(service, ref, secret)
         return True
     except Exception:  # noqa: BLE001 — keyring backends fail in many ways; fallback is intentional
         return False
 
 
-def _keyring_get(ref: str) -> str | None:
+def _keyring_get(ref: str, service: str = SERVICE) -> str | None:
     try:
         import keyring
-        return keyring.get_password(SERVICE, ref)
+        return keyring.get_password(service, ref)
     except Exception:  # noqa: BLE001 — unavailable keyring → try next provider
         return None
 
 
-def store_credential(workdir: Path, home: Path, ref: str, token: str) -> str:
+def store_credential(workdir: Path, home: Path, ref: str, token: str,
+                     service: str = SERVICE, auth_file: str = AUTH_FILE_NAME,
+                     index_dir: str = ".conf_knowledge_index") -> str:
     """Persist token: keyring preferred, protected file as explicit fallback.
 
     Returns a human description of where it went (never the token).
     """
-    if _keyring_store(ref, token):
+    if _keyring_store(ref, token, service):
         return "OS credential store"
     # file fallback — gitignore BEFORE writing
-    ensure_gitignore(workdir, [AUTH_FILE_NAME, ".conf_knowledge_index/"])
-    p = reject_unsafe_path(workdir / AUTH_FILE_NAME)
+    ensure_gitignore(workdir, [auth_file, index_dir + "/"])
+    p = reject_unsafe_path(workdir / auth_file)
     data = json.loads(p.read_text()) if p.exists() else {}
     data[ref] = token
     tmp = p.with_suffix(".tmp")
@@ -58,19 +60,21 @@ def store_credential(workdir: Path, home: Path, ref: str, token: str) -> str:
     return f"protected file {p} (chmod 600)"
 
 
-def get_credential(workdir: Path, ref: str) -> str | None:
+def get_credential(workdir: Path, ref: str, env: str = ENV_TOKEN,
+                   service: str = SERVICE, auth_file: str = AUTH_FILE_NAME,
+                   home_dir: str = ".confluence-knowledge") -> str | None:
     """Lookup order: env var (CI/scripts) → keyring → protected file."""
-    t = os.environ.get(ENV_TOKEN)
+    t = os.environ.get(env)
     if t:
         return t
-    t = _keyring_get(ref)
+    t = _keyring_get(ref, service)
     if t:
         return t
-    p = workdir / AUTH_FILE_NAME
+    p = workdir / auth_file
     if p.exists():
         data = json.loads(p.read_text())
         return data.get(ref)
-    p2 = Path.home() / ".confluence-knowledge" / AUTH_FILE_NAME
+    p2 = Path.home() / home_dir / auth_file
     if p2.exists():
         return json.loads(p2.read_text()).get(ref)
     return None

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge/cli.py

@@ -94,9 +94,21 @@ def _wizard() -> int:
 
 def _doctor() -> int:
     from .server import status
+    from .update import check
     try:
         s = status()
         print(json.dumps(s, indent=2))
+        upd = check("confluence-knowledge")
+        if upd["installed"]:
+            line = f"version: {upd['installed']}"
+            if upd["latest"]:
+                line += f" (latest: {upd['latest']})"
+            elif upd["latest"] is None:
+                line += " (latest: unchecked — offline or internal mirror)"
+            print(line)
+        if upd["update_available"]:
+            print("update available: run `confluence-knowledge update` "
+                  "(or pip install -U confluence-knowledge[models])")
         if s.get("configured"):
             from .server import _client_for  # internal but fine in CLI
             profile = SiteProfile.load(default_home())
@@ -122,6 +134,7 @@ def main() -> None:
     sub.add_parser("setup", help="guided credential + config setup")
     sub.add_parser("doctor", help="verify config, credentials, models")
     sub.add_parser("prepare-models", help="download the pinned local models")
+    sub.add_parser("update", help="upgrade this package via pip -U")
     reg = sub.add_parser(
         "register",
         help="write this server into the IDE's MCP config (no manual paste)")
@@ -145,6 +158,22 @@ def main() -> None:
         for line in prepare_models(default_home()):
             print(line)
         return
+    if args.cmd == "update":
+        import subprocess
+        cmd = [sys.executable, "-m", "pip", "install", "-U",
+               "confluence-knowledge[models]"]
+        if os.name == "nt":
+            # this exe is the running process on Windows — pip can't replace
+            # a file that's in use; hand the user the equivalent python -m
+            # pip command instead (same mechanism `pip install -U pip` uses)
+            print("on Windows, upgrade via the venv python directly:\n  "
+                  + " ".join(f'"{c}"' if " " in c else c for c in cmd))
+            return
+        r = subprocess.run(cmd, check=False)
+        if r.returncode == 0:
+            print("\nupdated — models are pinned and unchanged; "
+                  "run `confluence-knowledge doctor` to confirm")
+        sys.exit(r.returncode)
     if args.cmd == "register":
         from .registration import register
         try:

confluence_knowledge-0.4.1/src/confluence_knowledge/extract_files.py

@@ -0,0 +1,227 @@
+"""Bytes → chunks for office/text file formats.
+
+Shared by the local-files and SharePoint connectors — both end up with the
+same Chunk objects the index and retriever already understand. Office/PDF
+parsers are imported lazily so this module costs nothing when a file type
+isn't used. Unsupported/binary files produce a warning, never a crash.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import zipfile
+
+from .extract import Chunk, extract_chunks
+from .settings import SetupError
+
+MAX_FILE_WORDS = 200_000   # ~1MB of text — beyond that, index metadata only
+
+SUPPORTED = {".txt", ".md", ".markdown", ".csv", ".html", ".htm",
+             ".docx", ".pptx", ".xlsx", ".pdf"}
+
+# Names that look like credentials/secrets — excluded by default and
+# disclosed in coverage warnings.
+SECRET_NAMES = {".env", ".envrc", "id_rsa", "id_dsa", "id_ed25519", "id_ecdsa",
+                "credentials", "credentials.json", ".netrc", ".pgpass"}
+SECRET_SUFFIXES = {".pem", ".key", ".p12", ".pfx", ".keystore", ".jks"}
+
+
+def is_secret_name(filename: str) -> bool:
+    """True when the filename strongly suggests a credential/secret file."""
+    from pathlib import Path as P
+    name = P(filename).name.lower()
+    return (name in SECRET_NAMES
+            or name.startswith(".env.") or name.endswith(".env")
+            or P(name).suffix in SECRET_SUFFIXES)
+
+
+def _need(pkg: str, fmt: str):
+    raise SetupError(
+        f"'{pkg}' isn't installed — install the file extra: "
+        f"`pip install confluence-knowledge[files]` (needed for {fmt})")
+
+
+def _decode_text(data: bytes) -> str:
+    for enc in ("utf-8", "utf-16", "latin-1"):
+        try:
+            return data.decode(enc)
+        except UnicodeDecodeError:
+            continue
+    return data.decode("utf-8", errors="replace")
+
+
+def _text_chunks(text: str, heading: str, kind: str = "text") -> list[Chunk]:
+    """Split plain text into word-bounded chunks (same shape as extract.py)."""
+    words = text.split()
+    out: list[Chunk] = []
+    step = 280 - 40
+    for i in range(0, len(words), step):
+        seg = " ".join(words[i:i + 280])
+        if seg.strip():
+            out.append(Chunk(seg, heading, kind, len(out)))
+    return out
+
+
+def _docx_chunks(data: bytes) -> list[Chunk]:
+    try:
+        import docx  # python-docx
+    except ImportError:
+        _need("python-docx", ".docx")
+    doc = docx.Document(io.BytesIO(data))
+    chunks: list[Chunk] = []
+    heading: list[str] = []
+    buf: list[str] = []
+
+    def flush():
+        text = "\n".join(buf).strip()
+        buf.clear()
+        if text:
+            chunks.extend(_text_chunks(text, " > ".join(heading)))
+
+    for el in doc.element.body.iter():
+        tag = el.tag.split("}")[-1]
+        if tag == "p":
+            # find the paragraph object text via docx API per element
+            texts = [n.text for n in el.iter() if n.tag.split("}")[-1] == "t" and n.text]
+            line = "".join(texts).strip()
+            if not line:
+                continue
+            style = el.find("{*}pPr/{*}pStyle")
+            sty = style.get("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val", "") if style is not None else ""
+            if sty.lower().startswith("heading"):
+                flush()
+                level = int(sty[7] or 1) if len(sty) > 7 else 1
+                heading = heading[: level - 1]
+                while len(heading) < level - 1:
+                    heading.append("")
+                heading.append(line)
+            buf.append(line)
+        elif tag == "tbl":
+            flush()
+            rows = []
+            for tr in el.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}tr"):
+                cells = []
+                for tc in tr.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}tc"):
+                    cells.append("".join(t.text or "" for t in tc.iter(
+                        "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t")).strip())
+                if any(cells):
+                    rows.append(" | ".join(cells))
+            if rows:
+                header, *body = rows
+                t = "\n".join([f"Table — columns: {header}"]
+                              + [f"row {i}: {r}" for i, r in enumerate(body, 1)])
+                chunks.extend(_text_chunks(t, " > ".join(heading), "table"))
+    flush()
+    return chunks
+
+
+def _pptx_chunks(data: bytes) -> list[Chunk]:
+    try:
+        from pptx import Presentation
+    except ImportError:
+        _need("python-pptx", ".pptx")
+    prs = Presentation(io.BytesIO(data))
+    chunks: list[Chunk] = []
+    for i, slide in enumerate(prs.slides, 1):
+        texts = []
+        for shape in slide.shapes:
+            if shape.has_text_frame:
+                texts.extend(p.text for p in shape.text_frame.paragraphs)
+            if shape.has_table:
+                for row in shape.table.rows:
+                    texts.append(" | ".join(c.text for c in row.cells))
+        if slide.has_notes_slide and slide.notes_slide.notes_text_frame.text.strip():
+            texts.append("Notes: " + slide.notes_slide.notes_text_frame.text)
+        text = "\n".join(t for t in texts if t and t.strip())
+        if text.strip():
+            chunks.extend(_text_chunks(text, f"Slide {i}"))
+    return chunks
+
+
+def _xlsx_chunks(data: bytes) -> list[Chunk]:
+    try:
+        import openpyxl
+    except ImportError:
+        _need("openpyxl", ".xlsx")
+    wb = openpyxl.load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+    chunks: list[Chunk] = []
+    for ws in wb.worksheets:
+        rows = []
+        for row in ws.iter_rows(values_only=True):
+            vals = [str(c) if c is not None else "" for c in row]
+            if any(v.strip() for v in vals):
+                rows.append(" | ".join(vals))
+        if not rows:
+            continue
+        header, *body = rows
+        text = "\n".join([f"Table — columns: {header}"]
+                         + [f"row {i}: {r}" for i, r in enumerate(body, 1)])
+        chunks.extend(_text_chunks(text, f"Sheet: {ws.title}", "table"))
+    wb.close()
+    return chunks
+
+
+def _pdf_chunks(data: bytes) -> tuple[list[Chunk], list[str]]:
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        _need("pypdf", ".pdf")
+    chunks: list[Chunk] = []
+    warns: list[str] = []
+    reader = PdfReader(io.BytesIO(data))
+    for i, page in enumerate(reader.pages, 1):
+        try:
+            text = page.extract_text() or ""
+        except Exception:  # noqa: BLE001 — a bad page shouldn't kill the file
+            warns.append(f"page {i}: no extractable text (scanned/image?)")
+            continue
+        if text.strip():
+            chunks.extend(_text_chunks(text, f"Page {i}"))
+    if not chunks and not warns:
+        warns.append("no extractable text — likely a scanned document (OCR not supported)")
+    return chunks, warns
+
+
+def _csv_chunks(data: bytes) -> list[Chunk]:
+    text = _decode_text(data)
+    rows = [r for r in csv.reader(io.StringIO(text)) if any(c.strip() for c in r)]
+    if not rows:
+        return []
+    header, *body = rows
+    out = "\n".join([f"Table — columns: {' | '.join(header)}"]
+                    + [f"row {i}: {' | '.join(r)}" for i, r in enumerate(body, 1)])
+    return _text_chunks(out, "", "table")
+
+
+def extract_file_chunks(filename: str, data: bytes) -> tuple[list[Chunk], list[str]]:
+    """Dispatch on extension → (chunks, warnings). Never guesses at binaries."""
+    from pathlib import Path as P
+    ext = P(filename).suffix.lower()
+    if ext not in SUPPORTED:
+        return [], [f"unsupported type '{ext or filename}' — skipped"]
+
+    words = len(data) // 6  # rough guard against absurd inputs
+    if words > MAX_FILE_WORDS * 6:  # bytes→words estimate too big
+        return [], [f"file too large ({len(data)} bytes) — skipped"]
+
+    try:
+        if ext in (".txt", ".md", ".markdown"):
+            return _text_chunks(_decode_text(data), ""), []
+        if ext in (".html", ".htm"):
+            return extract_chunks(_decode_text(data))
+        if ext == ".csv":
+            return _csv_chunks(data), []
+        if ext == ".docx":
+            return _docx_chunks(data), []
+        if ext == ".pptx":
+            return _pptx_chunks(data), []
+        if ext == ".xlsx":
+            return _xlsx_chunks(data), []
+        if ext == ".pdf":
+            return _pdf_chunks(data)
+    except zipfile.BadZipFile:
+        return [], ["corrupt office file (not a valid zip) — skipped"]
+    except Exception as e:  # noqa: BLE001 — one bad file must not kill a crawl
+        return [], [f"parse error: {type(e).__name__}: {e}"]
+    return [], [f"unsupported type '{ext}' — skipped"]

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge/registration.py

@@ -16,15 +16,17 @@ from pathlib import Path
 from .settings import SetupError
 
 SERVER_ID = "confluence-knowledge"
+SERVER_MODULE = "confluence_knowledge.server"
+WORKDIR_ENV = "CONF_KNOWLEDGE_WORKDIR"
 
 
-def _server_entry(workdir: Path | None) -> dict:
+def _server_entry(workdir: Path | None, module: str, env_var: str) -> dict:
     entry = {
         "command": sys.executable,  # the venv python — no PATH guessing
-        "args": ["-m", "confluence_knowledge.server"],
+        "args": ["-m", module],
     }
     if workdir is not None:
-        entry["env"] = {"CONF_KNOWLEDGE_WORKDIR": str(workdir)}
+        entry["env"] = {env_var: str(workdir)}
     return entry
 
 
@@ -78,8 +80,8 @@ def targets(ide: str = "auto", workspace: Path | None = None) -> list[Path]:
     return dedup
 
 
-def _merge(path: Path, entry: dict | None) -> str:
-    """Write `entry` under servers[SERVER_ID], or remove it when None.
+def _merge(path: Path, entry: dict | None, server_id: str = SERVER_ID) -> str:
+    """Write `entry` under servers[server_id], or remove it when None.
 
     Merges with existing JSON; backs up before overwriting. A file that isn't
     parseable (JSONC comments etc.) is backed up and replaced — the agent
@@ -97,10 +99,10 @@ def _merge(path: Path, entry: dict | None) -> str:
         shutil.copy2(path, path.with_suffix(path.suffix + ".bak"))
     servers = data.setdefault("servers", {})
     if entry is None:
-        servers.pop(SERVER_ID, None)
+        servers.pop(server_id, None)
         action = "removed"
     else:
-        servers[SERVER_ID] = entry
+        servers[server_id] = entry
         action = "backup-replaced" if replaced else "written"
     tmp = path.with_suffix(".tmp")
     tmp.write_text(json.dumps(data, indent=2) + "\n")
@@ -109,7 +111,9 @@ def _merge(path: Path, entry: dict | None) -> str:
 
 
 def register(ide: str = "auto", workspace: Path | None = None,
-             workdir: Path | None = None, remove: bool = False) -> list[tuple[Path, str]]:
+             workdir: Path | None = None, remove: bool = False,
+             server_id: str = SERVER_ID, module: str = SERVER_MODULE,
+             env_var: str = WORKDIR_ENV) -> list[tuple[Path, str]]:
     """Write/remove our server entry in each target. Returns (path, action)."""
     if ide not in ("auto", "all", "vscode", "jetbrains"):
         raise SetupError(f"unknown --ide '{ide}' (auto|all|vscode|jetbrains)")
@@ -117,11 +121,11 @@ def register(ide: str = "auto", workspace: Path | None = None,
     if not files:
         raise SetupError("no IDE config locations found — no Copilot/JetBrains "
                          "or VS Code profile detected")
-    entry = None if remove else _server_entry(workdir)
-    return [(f, _merge(f, entry)) for f in files]
+    entry = None if remove else _server_entry(workdir, module, env_var)
+    return [(f, _merge(f, entry, server_id)) for f in files]
 
 
-def registered_paths() -> list[Path]:
+def registered_paths(server_id: str = SERVER_ID) -> list[Path]:
     """Existing config files that already contain our server — for doctor."""
     out = []
     for p in targets("all"):
@@ -129,6 +133,6 @@ def registered_paths() -> list[Path]:
             servers = json.loads(p.read_text()).get("servers", {})
         except (OSError, json.JSONDecodeError, UnicodeDecodeError):
             continue
-        if p.exists() and SERVER_ID in servers:
+        if p.exists() and server_id in servers:
             out.append(p)
     return out

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge/retrieval.py

@@ -27,20 +27,20 @@ def _models_dir(home: Path) -> Path:
     return home / "models"
 
 
-def _load_sentence_transformer(model_key: str, home: Path):
+def _load_sentence_transformer(model_key: str, home: Path,
+                               cli: str = "confluence-knowledge"):
     """Local-only model load — fails closed if artifacts aren't prepared."""
     try:
         from sentence_transformers import SentenceTransformer
     except ImportError as e:
         raise SetupError(
-            "sentence-transformers isn't installed — run "
-            "`confluence-knowledge prepare-models` (see docs/confluence-knowledge.md)"
+            f"sentence-transformers isn't installed — run `{cli} prepare-models`"
         ) from e
     local = _models_dir(home) / model_key.split("/")[-1]
     if not local.exists():
         raise SetupError(
             f"local model '{model_key}' not prepared — run "
-            "`confluence-knowledge prepare-models`. Cloud embeddings are never used."
+            f"`{cli} prepare-models`. Cloud embeddings are never used."
         )
     os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
     os.environ.setdefault("HF_HUB_OFFLINE", "1")
@@ -51,8 +51,8 @@ def _load_sentence_transformer(model_key: str, home: Path):
 
 
 class LocalEmbedder:
-    def __init__(self, home: Path):
-        self._m = _load_sentence_transformer(EMBED_MODEL, home)
+    def __init__(self, home: Path, cli: str = "confluence-knowledge"):
+        self._m = _load_sentence_transformer(EMBED_MODEL, home, cli)
 
     def embed(self, texts: list[str]) -> np.ndarray:
         v = self._m.encode(texts, convert_to_numpy=True, normalize_embeddings=True,
@@ -61,19 +61,18 @@ class LocalEmbedder:
 
 
 class LocalReranker:
-    def __init__(self, home: Path):
+    def __init__(self, home: Path, cli: str = "confluence-knowledge"):
         try:
             from sentence_transformers import CrossEncoder
         except ImportError as e:
             raise SetupError(
-                "sentence-transformers isn't installed — run "
-                "`confluence-knowledge prepare-models`"
+                f"sentence-transformers isn't installed — run `{cli} prepare-models`"
             ) from e
         local = _models_dir(home) / RERANK_MODEL.split("/")[-1]
         if not local.exists():
             raise SetupError(
                 f"local reranker '{RERANK_MODEL}' not prepared — run "
-                "`confluence-knowledge prepare-models`.")
+                f"`{cli} prepare-models`.")
         self._m = CrossEncoder(str(local), device="cpu",
                                trust_remote_code=False)
 

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge/settings.py

@@ -23,25 +23,28 @@ class SetupError(RuntimeError):
     """A problem the user can fix via setup instructions."""
 
 
-def default_home() -> Path:
-    env = os.environ.get("CONF_KNOWLEDGE_HOME")
+def default_home(env_var: str = "CONF_KNOWLEDGE_HOME",
+                 dir_name: str = ".confluence-knowledge") -> Path:
+    env = os.environ.get(env_var)
     if env:
         return Path(env).expanduser().resolve()
-    return (Path.home() / ".confluence-knowledge").resolve()
+    return (Path.home() / dir_name).resolve()
 
 
-def resolve_workdir() -> Path:
+def resolve_workdir(env_var: str = "CONF_KNOWLEDGE_WORKDIR",
+                    home_env: str = "CONF_KNOWLEDGE_HOME",
+                    home_dir: str = ".confluence-knowledge") -> Path:
     """Folder for the index and the file-fallback credential, shared by the CLI
-    and the server. CONF_KNOWLEDGE_WORKDIR wins; otherwise a per-user folder,
-    never the process cwd (IDEs start servers from read-only install dirs)."""
-    env = os.environ.get("CONF_KNOWLEDGE_WORKDIR")
+    and the server. The env var wins; otherwise a per-user folder, never the
+    process cwd (IDEs start servers from read-only install dirs)."""
+    env = os.environ.get(env_var)
     if env:
         return Path(env).expanduser().resolve()
-    return default_home() / "work"
+    return default_home(home_env, home_dir) / "work"
 
 
-def workspace_index_root(workdir: Path) -> Path:
-    return workdir / INDEX_DIR_NAME
+def workspace_index_root(workdir: Path, index_dir: str = INDEX_DIR_NAME) -> Path:
+    return workdir / index_dir
 
 
 def _is_windows() -> bool:
@@ -63,7 +66,9 @@ def reject_unsafe_path(path: Path) -> Path:
     return resolved
 
 
-def ensure_gitignore(path: Path, entries: list[str]) -> None:
+def ensure_gitignore(path: Path, entries: list[str],
+                     protected: tuple[str, ...] = (AUTH_FILE_NAME,
+                                                 INDEX_DIR_NAME)) -> None:
     """Append ignore entries before any secret/cache write. Idempotent.
 
     Raises SetupError if a protected path is already tracked by git.
@@ -76,13 +81,13 @@ def ensure_gitignore(path: Path, entries: list[str]) -> None:
             for e in missing:
                 f.write(("\n" if existing else "") + e + "\n")
             existing.update(missing)
-    _assert_not_tracked(path)
+    _assert_not_tracked(path, protected)
 
 
-def _assert_not_tracked(workdir: Path) -> None:
+def _assert_not_tracked(workdir: Path, protected: tuple[str, ...]) -> None:
     import subprocess
 
-    for rel in (AUTH_FILE_NAME, INDEX_DIR_NAME):
+    for rel in protected:
         try:
             r = subprocess.run(
                 ["git", "-C", str(workdir), "ls-files", "--error-unmatch", rel],

confluence_knowledge-0.4.1/src/confluence_knowledge/update.py

@@ -0,0 +1,55 @@
+"""Self-update check — installed vs latest published version.
+
+One GET to the package index (PyPI or an internal mirror set via
+KNOWLEDGE_UPDATE_INDEX) — fails silent to ``latest: None`` when offline or
+proxied, and never blocks doctor.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from importlib.metadata import PackageNotFoundError, version
+
+INDEX = "https://pypi.org/pypi/{dist}/json"
+ENV_INDEX = "KNOWLEDGE_UPDATE_INDEX"
+TIMEOUT = 5
+
+
+def installed_version(dist: str) -> str | None:
+    try:
+        return version(dist)
+    except PackageNotFoundError:
+        return None
+
+
+def latest_version(dist: str, timeout: float = TIMEOUT) -> str | None:
+    """Latest version on the index — None when it can't be checked (offline,
+    internal mirror without the package, network policy). Never raises."""
+    url = os.environ.get(ENV_INDEX, INDEX).format(dist=dist)
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as r:
+            return json.loads(r.read())["info"]["version"]
+    except Exception:  # noqa: BLE001 — every failure mode means "couldn't check"
+        return None
+
+
+def check(dist: str) -> dict:
+    """{installed, latest, update_available} — the dict doctor reports."""
+    inst = installed_version(dist)
+    latest = latest_version(dist)
+    return {
+        "installed": inst,
+        "latest": latest,
+        "update_available": bool(
+            inst and latest and _version_tuple(latest) > _version_tuple(inst)),
+    }
+
+
+def _version_tuple(v: str) -> tuple:
+    out = []
+    for part in v.split("."):
+        num = "".join(c for c in part if c.isdigit())
+        out.append(int(num) if num else 0)
+    return tuple(out)

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluence-knowledge
-Version: 0.3.1
+Version: 0.4.1
 Summary: Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service
 License: MIT
 Project-URL: Repository, https://github.com/nkunal1992/agents
@@ -21,6 +21,11 @@ Requires-Dist: pip-system-certs>=5.0
 Provides-Extra: models
 Requires-Dist: sentence-transformers<4.0,>=3.0; extra == "models"
 Requires-Dist: huggingface-hub>=0.26; extra == "models"
+Provides-Extra: files
+Requires-Dist: python-docx>=1.1; extra == "files"
+Requires-Dist: pypdf>=4.0; extra == "files"
+Requires-Dist: python-pptx>=1.0; extra == "files"
+Requires-Dist: openpyxl>=3.1; extra == "files"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge.egg-info/SOURCES.txt

@@ -6,12 +6,14 @@ src/confluence_knowledge/cli.py
 src/confluence_knowledge/client.py
 src/confluence_knowledge/crawl.py
 src/confluence_knowledge/extract.py
+src/confluence_knowledge/extract_files.py
 src/confluence_knowledge/index.py
 src/confluence_knowledge/models.lock.json
 src/confluence_knowledge/registration.py
 src/confluence_knowledge/retrieval.py
 src/confluence_knowledge/server.py
 src/confluence_knowledge/settings.py
+src/confluence_knowledge/update.py
 src/confluence_knowledge.egg-info/PKG-INFO
 src/confluence_knowledge.egg-info/SOURCES.txt
 src/confluence_knowledge.egg-info/dependency_links.txt
@@ -27,4 +29,5 @@ tests/test_prepare_models.py
 tests/test_registration.py
 tests/test_retrieval.py
 tests/test_secrets.py
-tests/test_server_flow.py
+tests/test_server_flow.py
+tests/test_update.py

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/src/confluence_knowledge.egg-info/requires.txt

@@ -10,6 +10,12 @@ pytest>=8.0
 pytest-cov>=5.0
 ruff>=0.6
 
+[files]
+python-docx>=1.1
+pypdf>=4.0
+python-pptx>=1.0
+openpyxl>=3.1
+
 [models]
 sentence-transformers<4.0,>=3.0
 huggingface-hub>=0.26

{confluence_knowledge-0.3.1 → confluence_knowledge-0.4.1}/tests/test_secrets.py

@@ -9,7 +9,7 @@ from confluence_knowledge.settings import AUTH_FILE_NAME
 
 def test_gitignore_written_before_secret(tmp_path, monkeypatch):
     from confluence_knowledge import auth
-    monkeypatch.setattr(auth, "_keyring_store", lambda r, s: False)
+    monkeypatch.setattr(auth, "_keyring_store", lambda r, s, service=None: False)
     where = store_credential(tmp_path, tmp_path / "home", "ref1", "tok_ABC123")
     gi = (tmp_path / ".gitignore").read_text()
     assert AUTH_FILE_NAME in gi and ".conf_knowledge_index/" in gi
@@ -19,7 +19,7 @@ def test_gitignore_written_before_secret(tmp_path, monkeypatch):
 def test_secret_file_permissions(tmp_path, monkeypatch):
     # force file fallback: make keyring unusable
     from confluence_knowledge import auth
-    monkeypatch.setattr(auth, "_keyring_store", lambda r, s: False)
+    monkeypatch.setattr(auth, "_keyring_store", lambda r, s, service=None: False)
     store_credential(tmp_path, tmp_path / "home", "ref1", "tok_ABC123")
     if os.name != "nt":
         mode = (tmp_path / AUTH_FILE_NAME).stat().st_mode

confluence_knowledge-0.4.1/tests/test_update.py

@@ -0,0 +1,40 @@
+"""Self-update check — mocked index, offline path, version compare."""
+from __future__ import annotations
+
+from confluence_knowledge import update
+
+
+def test_installed_version():
+    v = update.installed_version("confluence-knowledge")
+    assert v and v[0].isdigit()
+
+
+def test_latest_offline_returns_none(monkeypatch):
+    monkeypatch.setattr(update, "INDEX", "https://invalid.invalid/{dist}")
+    monkeypatch.delenv("KNOWLEDGE_UPDATE_INDEX", raising=False)
+    # urllib will fail to resolve — must return None, not raise
+    assert update.latest_version("confluence-knowledge", timeout=1) is None
+
+
+def test_check_update_available(monkeypatch):
+    monkeypatch.setattr(update, "latest_version", lambda d, **k: "99.0.0")
+    r = update.check("confluence-knowledge")
+    assert r["update_available"] is True and r["latest"] == "99.0.0"
+
+
+def test_check_up_to_date(monkeypatch):
+    inst = update.installed_version("confluence-knowledge")
+    monkeypatch.setattr(update, "latest_version", lambda d, **k: inst)
+    r = update.check("confluence-knowledge")
+    assert r["update_available"] is False
+
+
+def test_check_cannot_check(monkeypatch):
+    monkeypatch.setattr(update, "latest_version", lambda d, **k: None)
+    r = update.check("confluence-knowledge")
+    assert r["update_available"] is False and r["latest"] is None
+
+
+def test_version_tuple():
+    assert update._version_tuple("1.2.10") > update._version_tuple("1.2.9")
+    assert update._version_tuple("0.4.1") == update._version_tuple("0.4.1")