open-knowledge-studio 0.2.2__tar.gz → 0.2.4__tar.gz

{open_knowledge_studio-0.2.2/open_knowledge_studio.egg-info → open_knowledge_studio-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-knowledge-studio
-Version: 0.2.2
+Version: 0.2.4
 Summary: File-based knowledge engineering CLI for Claude Code
 Author: open-agent-power
 License: MIT
@@ -42,16 +42,23 @@ a file-based knowledge base that turns raw material into a recallable, self-deca
 ## Install
 
 ```bash
-pip install open-knowledge-studio
+pipx install open-knowledge-studio && pipx ensurepath
 ```
 
+We recommend pipx because modern Linux (Ubuntu 24.04+) and macOS Homebrew Pythons are
+PEP 668 externally-managed, so a bare `pip install` fails. If your mirror lags behind
+PyPI, add `--pip-args="-i https://pypi.org/simple"`.
+
 Optional multimodal ingest (PDF / audio / video / formula extraction) lives in a
 separate, heavier package that you can pull in on demand:
 
 ```bash
-pip install "open-knowledge-studio[connector]"
+pipx inject open-knowledge-studio oks-connector
 ```
 
+(pipx apps share one venv without a standalone pip executable — `pipx inject` is how
+you add extras. In a plain venv, use `pip install "open-knowledge-studio[connector]"`.)
+
 ## What you get
 
 - **6+1-factor recall engine** — token overlap, substring, topic trace, type boost,
@@ -67,7 +74,7 @@ orchestrate the pipeline around it.
 ## Quick start
 
 ```bash
-pip install open-knowledge-studio   # 1. install the CLI
+pipx install open-knowledge-studio && pipx ensurepath   # 1. install the CLI
 oks init my-knowledge-base          # 2. scaffold an instance (skills + buckets)
 cd my-knowledge-base
 oks status                          # 3. use it

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/README.md

@@ -8,16 +8,23 @@ a file-based knowledge base that turns raw material into a recallable, self-deca
 ## Install
 
 ```bash
-pip install open-knowledge-studio
+pipx install open-knowledge-studio && pipx ensurepath
 ```
 
+We recommend pipx because modern Linux (Ubuntu 24.04+) and macOS Homebrew Pythons are
+PEP 668 externally-managed, so a bare `pip install` fails. If your mirror lags behind
+PyPI, add `--pip-args="-i https://pypi.org/simple"`.
+
 Optional multimodal ingest (PDF / audio / video / formula extraction) lives in a
 separate, heavier package that you can pull in on demand:
 
 ```bash
-pip install "open-knowledge-studio[connector]"
+pipx inject open-knowledge-studio oks-connector
 ```
 
+(pipx apps share one venv without a standalone pip executable — `pipx inject` is how
+you add extras. In a plain venv, use `pip install "open-knowledge-studio[connector]"`.)
+
 ## What you get
 
 - **6+1-factor recall engine** — token overlap, substring, topic trace, type boost,
@@ -33,7 +40,7 @@ orchestrate the pipeline around it.
 ## Quick start
 
 ```bash
-pip install open-knowledge-studio   # 1. install the CLI
+pipx install open-knowledge-studio && pipx ensurepath   # 1. install the CLI
 oks init my-knowledge-base          # 2. scaffold an instance (skills + buckets)
 cd my-knowledge-base
 oks status                          # 3. use it

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/_assets/claude/hooks/pre-compact.sh

@@ -4,7 +4,17 @@
 
 set -euo pipefail
 
-REPO_ROOT="${OKS_ROOT:-$(pwd)}"
+REPO_ROOT="${OKS_ROOT:-}"
+if [ -z "$REPO_ROOT" ]; then
+    REPO_ROOT="$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.oks/config.json'))).get('knowledge_base_path',''))" 2>/dev/null || true)"
+fi
+if [ -z "$REPO_ROOT" ]; then
+    REPO_ROOT="$(pwd)"
+fi
+
+# Only snapshot inside a real knowledge base — never litter other dirs.
+[ -d "$REPO_ROOT/wiki" ] || exit 0
+
 SNAPSHOT_DIR="$REPO_ROOT/.oks/snapshots"
 mkdir -p "$SNAPSHOT_DIR"
 

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/_assets/claude/hooks/session-start.sh

@@ -4,7 +4,13 @@
 
 set -euo pipefail
 
-REPO_ROOT="${OKS_ROOT:-$(pwd)}"
+REPO_ROOT="${OKS_ROOT:-}"
+if [ -z "$REPO_ROOT" ]; then
+    REPO_ROOT="$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.oks/config.json'))).get('knowledge_base_path',''))" 2>/dev/null || true)"
+fi
+if [ -z "$REPO_ROOT" ]; then
+    REPO_ROOT="$(pwd)"
+fi
 
 if [ ! -d "$REPO_ROOT/wiki" ]; then
     exit 0

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/_assets/claude/hooks/user-prompt-recall.sh

@@ -3,4 +3,6 @@
 # Passes the original stdin (editor JSON payload) through to the Python hook,
 # and drops jieba's stderr chatter so only the clean <recalled-memory> block
 # reaches stdout. Fails open (exit 0) so a prompt is never blocked.
-exec python3 "$(dirname "$0")/user-prompt-recall.py" 2>/dev/null
+# OKS_PYTHON is baked in by `oks hook install` to point at the interpreter
+# that can import knowledge_studio (pipx/venv safe); falls back to python3.
+exec "${OKS_PYTHON:-python3}" "$(dirname "$0")/user-prompt-recall.py" 2>/dev/null

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/cli.py

@@ -24,6 +24,27 @@ app = typer.Typer(
 )
 console = Console()
 
+
+def _version_callback(value: bool):
+    if value:
+        from importlib.metadata import version, PackageNotFoundError
+        try:
+            console.print(f"oks {version('open-knowledge-studio')}")
+        except PackageNotFoundError:
+            console.print("oks (development, not installed as a package)")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(
+        False, "--version", "-V", callback=_version_callback, is_eager=True,
+        help="Show the oks version and exit.",
+    ),
+):
+    pass
+
+
 wiki_app = typer.Typer(help="Wiki page management.")
 drafts_app = typer.Typer(help="Draft proposal management.")
 config_app = typer.Typer(help="Global configuration (~/.oks/config.json).")
@@ -191,8 +212,18 @@ def wiki_create(
     if not content and not sys.stdin.isatty():
         content = sys.stdin.read()
 
-    type_map = {"concept": "concepts", "strategy": "strategies", "anti-pattern": "anti-patterns"}
-    wiki_type = type_map.get(page_type, "concepts")
+    type_map = {
+        "concept": "concepts", "concepts": "concepts",
+        "strategy": "strategies", "strategies": "strategies",
+        "anti-pattern": "anti-patterns", "anti-patterns": "anti-patterns",
+    }
+    wiki_type = type_map.get(page_type)
+    if wiki_type is None:
+        console.print(
+            f"[yellow]Unknown --type '{page_type}' — using 'concept'. "
+            f"Valid: concept, strategy, anti-pattern.[/yellow]"
+        )
+        wiki_type = "concepts"
 
     path = store.write_wiki_page(
         title=title,
@@ -444,7 +475,11 @@ def config_init(
     """Initialize global config at ~/.oks/config.json."""
     from knowledge_studio.config import init_config
 
-    path = init_config(kb_path)
+    try:
+        path = init_config(kb_path)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
     console.print(f"[green]Config created:[/green] {path}")
 
     from knowledge_studio.config import load_config
@@ -495,7 +530,15 @@ def config_set(
             target[k] = {}
         target = target[k]
 
-    if value.lower() in ("true", "false"):
+    if key == "knowledge_base_path":
+        resolved = Path(value).expanduser().resolve()
+        if not resolved.is_dir():
+            console.print(
+                f"[yellow]Warning:[/yellow] directory does not exist: {resolved}"
+            )
+        value = str(resolved)
+        target[keys[-1]] = value
+    elif value.lower() in ("true", "false"):
         target[keys[-1]] = value.lower() == "true"
     elif value.isdigit():
         target[keys[-1]] = int(value)
@@ -576,18 +619,17 @@ def _materialize_assets(root: Path, base: Path, is_packaged: bool, overwrite: bo
         if not src.is_dir():
             continue
         dest = root / dest_name
-        if dest.exists():
-            if not overwrite:
-                continue
-            shutil.rmtree(dest)
-        shutil.copytree(src, dest)
+        if dest.exists() and not overwrite:
+            continue
+        # Merge-copy: refresh bundled files in place, keep user-owned files.
+        shutil.copytree(src, dest, dirs_exist_ok=True)
         done.append(dest_name)
     return done
 
 
 @app.command()
 def init(
-    path: str = typer.Argument(".", help="Target directory for the new knowledge instance"),
+    path: str = typer.Argument(..., help="Target directory for the new knowledge instance"),
     set_default: bool = typer.Option(
         True, "--set-default/--no-set-default",
         help="Register this folder as the active KB in ~/.oks/config.json",
@@ -599,6 +641,10 @@ def init(
         False, "--upgrade",
         help="Re-copy bundled assets (skills/templates/_meta/settings), overwriting them; your memory (wiki/drafts/profiles) is untouched",
     ),
+    force: bool = typer.Option(
+        False, "--force",
+        help="Scaffold into a non-empty directory that is not already a knowledge base",
+    ),
 ):
     """Scaffold a new knowledge INSTANCE folder (e.g. your personal artboy-knowledge-studio).
 
@@ -608,6 +654,26 @@ def init(
     from anywhere.
     """
     root = Path(path).expanduser().resolve()
+
+    # Refuse to scaffold into an existing non-empty directory that is not
+    # already a KB (missing wiki/) — protects arbitrary folders from being
+    # hijacked. Re-running on an existing KB is idempotent and allowed.
+    if (
+        root.is_dir()
+        and any(root.iterdir())
+        and not (root / "wiki").is_dir()
+        and not force
+    ):
+        console.print(
+            f"[red]Refusing to scaffold into non-empty directory:[/red] {root}\n"
+            f"It does not look like a knowledge base (no wiki/). Init would create:\n"
+            + "\n".join(f"  - {d}/" for d in _INSTANCE_DIRS)
+            + "\n  - .claude/ templates/ _meta/ settings/ (bundled assets)"
+            + "\n  - .gitignore"
+            + "\n\nRe-run with [bold]--force[/bold] to proceed anyway."
+        )
+        raise typer.Exit(1)
+
     root.mkdir(parents=True, exist_ok=True)
 
     for d in _INSTANCE_DIRS:
@@ -617,7 +683,11 @@ def init(
 
     base, is_packaged = _asset_source()
     if base is None:
-        console.print("[yellow]No bundled assets found — skills/templates not materialized.[/yellow]")
+        console.print(
+            "[yellow]No bundled assets found — skills/templates not materialized.[/yellow]\n"
+            "  Source installs lack the asset bundle. Fix: pip install open-knowledge-studio,\n"
+            "  or run python cli/scripts/bundle_assets.py in the repo before installing."
+        )
     else:
         copied = _materialize_assets(root, base, is_packaged, overwrite=upgrade)
         if copied:
@@ -658,7 +728,10 @@ def init(
 
 # ── Optional editor hooks (opt-in auto-recall) ───────────────────
 
-_RECALL_HOOK_CMD = ".claude/hooks/user-prompt-recall.sh"
+# Hook commands are written as absolute paths (see hook_install). Old
+# installs wired the relative path below; matching is done by script name
+# so both forms are recognized.
+_RECALL_HOOK_SCRIPT_NAME = "user-prompt-recall.sh"
 _RECALL_HOOK_SCRIPTS = ("user-prompt-recall.py", "user-prompt-recall.sh")
 _HOOK_EDITORS = {
     "claude": ".claude/settings.json",
@@ -674,9 +747,16 @@ def _instance_root(path: str | None) -> Path:
 
 
 def _ensure_recall_scripts(root: Path) -> list[str]:
-    """Copy the recall hook scripts into <root>/.claude/hooks/ if missing."""
+    """Copy/refresh the recall hook scripts in <root>/.claude/hooks/.
+
+    The .sh wrapper gets the current interpreter baked into its OKS_PYTHON
+    fallback. If an existing .sh lacks the current bake (fresh copy still on
+    `python3`, or baked against a stale interpreter), it is re-copied from
+    the asset source and re-baked. The .py engine is only copied if missing.
+    """
     import shutil
     import stat
+    import sys
 
     hooks_dir = root / ".claude" / "hooks"
     hooks_dir.mkdir(parents=True, exist_ok=True)
@@ -686,23 +766,40 @@ def _ensure_recall_scripts(root: Path) -> list[str]:
     if base is not None:
         src_dir = base / ("claude/hooks" if is_packaged else ".claude/hooks")
 
+    baked = f'"${{OKS_PYTHON:-{sys.executable}}}"'
     created: list[str] = []
     for name in _RECALL_HOOK_SCRIPTS:
         dest = hooks_dir / name
         if dest.exists():
-            continue
+            if not name.endswith(".sh"):
+                continue
+            try:
+                if baked in dest.read_text(encoding="utf-8"):
+                    continue
+            except OSError:
+                pass
+            # Stale interpreter bake — fall through to re-copy + re-bake.
         if src_dir is None or not (src_dir / name).is_file():
             raise FileNotFoundError(
                 f"bundled hook script not found: {name} (asset source: {src_dir})"
             )
         shutil.copy2(src_dir / name, dest)
+        if name.endswith(".sh"):
+            text = dest.read_text(encoding="utf-8").replace(
+                '"${OKS_PYTHON:-python3}"', baked
+            )
+            dest.write_text(text, encoding="utf-8")
         dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
         created.append(name)
     return created
 
 
 def _wire_userpromptsubmit(settings_path: Path, command: str) -> str:
-    """Idempotently add a UserPromptSubmit command hook. Returns 'wired'|'exists'."""
+    """Idempotently add a UserPromptSubmit command hook. Returns 'wired'|'exists'.
+
+    Recognizes previously wired entries (old relative or stale absolute
+    paths) by script name and rewrites them in place instead of duplicating.
+    """
     data: dict = {}
     if settings_path.exists():
         try:
@@ -711,11 +808,18 @@ def _wire_userpromptsubmit(settings_path: Path, command: str) -> str:
             raise ValueError(f"{settings_path} is not valid JSON: {e}") from e
     hooks = data.setdefault("hooks", {})
     ups = hooks.setdefault("UserPromptSubmit", [])
+    stale: dict | None = None
     for group in ups:
         for h in group.get("hooks", []):
-            if h.get("command") == command:
+            cmd = h.get("command", "")
+            if cmd == command:
                 return "exists"
-    ups.append({"hooks": [{"type": "command", "command": command}]})
+            if cmd.endswith(_RECALL_HOOK_SCRIPT_NAME):
+                stale = h
+    if stale is not None:
+        stale["command"] = command
+    else:
+        ups.append({"hooks": [{"type": "command", "command": command}]})
     settings_path.parent.mkdir(parents=True, exist_ok=True)
     settings_path.write_text(
         json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
@@ -723,7 +827,7 @@ def _wire_userpromptsubmit(settings_path: Path, command: str) -> str:
     return "wired"
 
 
-def _hook_is_wired(settings_path: Path, command: str) -> bool:
+def _hook_is_wired(settings_path: Path) -> bool:
     if not settings_path.exists():
         return False
     try:
@@ -732,7 +836,7 @@ def _hook_is_wired(settings_path: Path, command: str) -> bool:
         return False
     for group in data.get("hooks", {}).get("UserPromptSubmit", []):
         for h in group.get("hooks", []):
-            if h.get("command") == command:
+            if h.get("command", "").endswith(_RECALL_HOOK_SCRIPT_NAME):
                 return True
     return False
 
@@ -757,19 +861,37 @@ def hook_install(
         console.print("[red]--editor must be one of: claude, qoder, both[/red]")
         raise typer.Exit(1)
 
+    import platform
+    if platform.system() == "Windows":
+        console.print(
+            "[yellow]Warning: hooks are bash scripts and will not run on native Windows.[/yellow]\n"
+            "  Use WSL (or Git Bash configured as the hook shell) for auto-recall to work."
+        )
+
     root = _instance_root(path)
     if not root.is_dir():
         console.print(f"[red]Instance root not found:[/red] {root}")
         raise typer.Exit(1)
 
-    created = _ensure_recall_scripts(root)
+    try:
+        created = _ensure_recall_scripts(root)
+    except FileNotFoundError as e:
+        console.print(
+            f"[red]Cannot install hook — bundled assets missing.[/red]\n"
+            f"  {e}\n"
+            f"  This happens when oks was installed from source without the asset bundle.\n"
+            f"  Fix: [bold]pip install open-knowledge-studio[/bold] (PyPI wheel includes assets),\n"
+            f"  or run [bold]python cli/scripts/bundle_assets.py[/bold] in the repo before installing."
+        )
+        raise typer.Exit(1)
     if created:
         console.print(f"[green]Installed hook script:[/green] {', '.join(created)}")
 
+    hook_cmd = (root / ".claude" / "hooks" / _RECALL_HOOK_SCRIPT_NAME).resolve().as_posix()
     editors = ("claude", "qoder") if editor == "both" else (editor,)
     for name in editors:
         settings_path = root / _HOOK_EDITORS[name]
-        result = _wire_userpromptsubmit(settings_path, _RECALL_HOOK_CMD)
+        result = _wire_userpromptsubmit(settings_path, hook_cmd)
         label = "[green]wired[/green]" if result == "wired" else "[dim]already wired[/dim]"
         console.print(f"  {name}: {label} → {settings_path}")
 
@@ -788,9 +910,26 @@ def hook_status(
     script = root / ".claude" / "hooks" / "user-prompt-recall.sh"
     console.print(f"[bold]Instance:[/bold] {root}")
     console.print(f"  script: {'present' if script.is_file() else 'missing'} ({script})")
+    if script.is_file():
+        import os
+        import re
+        import subprocess
+        m = re.search(r"\$\{OKS_PYTHON:-([^}]+)\}", script.read_text(encoding="utf-8"))
+        py = os.environ.get("OKS_PYTHON") or (m.group(1) if m else "python3")
+        try:
+            ok = subprocess.run(
+                [py, "-c", "import knowledge_studio"],
+                capture_output=True, timeout=15,
+            ).returncode == 0
+        except (OSError, subprocess.TimeoutExpired):
+            ok = False
+        state = ("[green]importable[/green]" if ok
+                 else "[red]hook script has stale interpreter — "
+                      "run `oks hook install` to re-bake[/red]")
+        console.print(f"  engine: {state} (python: {py})")
     for name, rel in _HOOK_EDITORS.items():
         settings_path = root / rel
-        wired = _hook_is_wired(settings_path, _RECALL_HOOK_CMD)
+        wired = _hook_is_wired(settings_path)
         state = "[green]wired[/green]" if wired else "[dim]not wired[/dim]"
         console.print(f"  {name}: {state}")
 

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/config.py

@@ -61,8 +61,14 @@ def load_config() -> dict[str, Any]:
     path = config_path()
     if not path.exists():
         return dict(DEFAULT_CONFIG)
-    with open(path) as f:
-        return json.load(f)
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        raise ValueError(
+            f"{path} is corrupt ({e}). Fix the JSON manually, or delete it and "
+            f"re-run `oks config init` / `oks init <path>`."
+        ) from e
 
 
 def save_config(config: dict[str, Any]) -> None:
@@ -70,6 +76,7 @@ def save_config(config: dict[str, Any]) -> None:
     path = config_path()
     path.parent.mkdir(parents=True, exist_ok=True)
 
+    import contextlib
     import tempfile
     fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
     try:
@@ -77,42 +84,81 @@ def save_config(config: dict[str, Any]) -> None:
             json.dump(config, f, indent=2, ensure_ascii=False)
         os.replace(tmp, path)
     except Exception:
-        os.unlink(tmp)
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
         raise
 
 
 def init_config(kb_path: str | None = None) -> Path:
-    """Initialize global config. Returns the config path."""
+    """Initialize global config. Returns the config path.
+
+    Raises ValueError when no kb_path is given and the existing config has
+    no knowledge_base_path — we never silently default to cwd.
+    """
     config = load_config()
 
     if kb_path:
-        config["knowledge_base_path"] = kb_path
+        config["knowledge_base_path"] = str(Path(kb_path).expanduser().resolve())
     elif not config.get("knowledge_base_path"):
-        try:
-            from knowledge_studio.store import repo_root
-            config["knowledge_base_path"] = str(repo_root())
-        except Exception:
-            config["knowledge_base_path"] = str(Path.cwd())
+        raise ValueError(
+            "knowledge_base_path required: pass --kb-path or run `oks init <path>`"
+        )
 
     save_config(config)
     return config_path()
 
 
+# Warn at most once per process when the configured root lacks wiki/.
+_warned_missing_wiki = False
+
+
+def _warn_if_not_kb(root: Path) -> None:
+    global _warned_missing_wiki
+    if _warned_missing_wiki:
+        return
+    if not (root / "wiki").is_dir():
+        _warned_missing_wiki = True
+        import sys
+        print(
+            f"oks: warning: configured KB path {root} does not look like a "
+            f"knowledge base (missing wiki/); run `oks init <path>` or "
+            f"`oks config set knowledge_base_path <path>`",
+            file=sys.stderr,
+        )
+
+
 def get_kb_root() -> Path:
-    """Get the knowledge base root path.
+    """Get the knowledge base root path (single source of truth).
 
     Priority:
     1. OKS_ROOT env var
     2. ~/.oks/config.json → knowledge_base_path
     3. Current working directory
+
+    A corrupt config warns on stderr and falls back to cwd instead of
+    raising, matching the historical store.repo_root() behavior.
     """
     env_root = os.environ.get("OKS_ROOT")
     if env_root:
-        return Path(env_root)
+        root = Path(env_root).expanduser().resolve()
+        _warn_if_not_kb(root)
+        return root
+
+    try:
+        config = load_config()
+    except Exception as e:
+        import sys
+        print(
+            f"oks: warning: could not read {config_path()} ({e}); "
+            f"falling back to current directory as KB root",
+            file=sys.stderr,
+        )
+        return Path.cwd()
 
-    config = load_config()
     kb_path = config.get("knowledge_base_path")
     if kb_path:
-        return Path(kb_path)
+        root = Path(kb_path).expanduser().resolve()
+        _warn_if_not_kb(root)
+        return root
 
     return Path.cwd()

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/metrics.py

@@ -5,7 +5,7 @@ Removed KnowledgeStore dependency. Uses store functions.
 """
 from __future__ import annotations
 
-from datetime import UTC, datetime, timedelta
+from datetime import UTC, date, datetime, timedelta
 
 from knowledge_studio.store import list_wiki_pages, repo_root, wiki_dir
 
@@ -86,11 +86,15 @@ def _compute_credibility(pages: list[dict], ninety_days_ago: datetime) -> dict:
     }
 
 
-def _parse_date(value: str | None) -> datetime:
+def _parse_date(value) -> datetime:
     if not value:
         return datetime.min.replace(tzinfo=UTC)
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=UTC)
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day, tzinfo=UTC)
     try:
-        dt = datetime.fromisoformat(value)
+        dt = datetime.fromisoformat(str(value))
         if dt.tzinfo is None:
             dt = dt.replace(tzinfo=UTC)
         return dt

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/recall.py

@@ -221,6 +221,8 @@ def _tokenize(text: str) -> set[str]:
     try:
         import jieba
 
+        import logging as _logging
+        jieba.setLogLevel(_logging.WARNING)  # silence "Building prefix dict" chatter
         raw_words = list(jieba.cut_for_search(text))
     except Exception:
         raw_words = text.split()

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/knowledge_studio/store.py

@@ -13,7 +13,7 @@ import math
 import os
 import re
 import tempfile
-from datetime import UTC, datetime
+from datetime import UTC, date, datetime
 from pathlib import Path
 
 import yaml
@@ -35,18 +35,10 @@ DEFAULT_CONFIG: dict = {
 
 
 def repo_root() -> Path:
-    env_root = os.environ.get("OKS_ROOT")
-    if env_root:
-        return Path(env_root)
-    try:
-        from knowledge_studio.config import load_config
+    """Thin delegate — config.get_kb_root() is the single root resolver."""
+    from knowledge_studio.config import get_kb_root
 
-        kb_path = load_config().get("knowledge_base_path")
-        if kb_path:
-            return Path(kb_path)
-    except Exception:
-        pass
-    return Path(os.getcwd())
+    return get_kb_root()
 
 
 def wiki_dir() -> Path:
@@ -103,9 +95,9 @@ def load_active_goals() -> list[dict]:
 
 
 def _access_log_path() -> Path:
-    log_dir = repo_root() / ".oks"
-    log_dir.mkdir(parents=True, exist_ok=True)
-    return log_dir / "access.json"
+    # Read-only: no mkdir here. Writers go through _atomic_write, which
+    # creates the parent directory.
+    return repo_root() / ".oks" / "access.json"
 
 
 def _load_access_counts() -> dict[str, int]:
@@ -187,11 +179,16 @@ def compute_score(meta: dict, access_count: int = 0, config: dict | None = None)
     if archived or status == "dropped":
         return 0.0
 
-    created_str = meta.get("created", "")
-    try:
-        created = datetime.fromisoformat(created_str)
-    except (ValueError, TypeError):
-        created = datetime.now(UTC)
+    created_raw = meta.get("created", "")
+    if isinstance(created_raw, datetime):
+        created = created_raw
+    elif isinstance(created_raw, date):
+        created = datetime(created_raw.year, created_raw.month, created_raw.day)
+    else:
+        try:
+            created = datetime.fromisoformat(str(created_raw))
+        except (ValueError, TypeError):
+            created = datetime.now(UTC)
 
     tz = UTC if not created.tzinfo else created.tzinfo
     days_old = max(0, (datetime.now(UTC) - created.replace(tzinfo=tz)).days)
@@ -245,9 +242,9 @@ def _fingerprint(content: str) -> str:
 
 
 def _fingerprint_index_path() -> Path:
-    d = repo_root() / ".oks"
-    d.mkdir(parents=True, exist_ok=True)
-    return d / "fingerprints.json"
+    # Read-only: no mkdir here. Writers go through _atomic_write, which
+    # creates the parent directory.
+    return repo_root() / ".oks" / "fingerprints.json"
 
 
 def _load_fingerprint_index() -> dict[str, str]:
@@ -274,18 +271,19 @@ def _find_file_by_slug(slug: str) -> Path | None:
     return None
 
 
-def _update_frontmatter_field(file_path: Path, field: str, value) -> None:
+def _update_frontmatter_field(file_path: Path, field: str, value) -> bool:
     text = file_path.read_text(encoding="utf-8")
     parts = text.split("---", 2)
     if len(parts) < 3:
-        return
+        return False
     try:
         meta = yaml.safe_load(parts[1].strip()) or {}
     except yaml.YAMLError:
-        return
+        return False
     meta[field] = value
     new_fm = yaml.dump(meta, default_flow_style=False, allow_unicode=True, sort_keys=False)
     _atomic_write(file_path, f"---\n{new_fm}---\n{parts[2]}")
+    return True
 
 
 def _reinforce_confidence(slug: str) -> None:
@@ -493,17 +491,16 @@ def pin_page(slug: str) -> bool:
     f = _find_file_by_slug(slug)
     if not f:
         return False
-    _update_frontmatter_field(f, "pinned", True)
-    return True
+    return _update_frontmatter_field(f, "pinned", True)
 
 
 def archive_page(slug: str) -> bool:
     f = _find_file_by_slug(slug)
     if not f:
         return False
-    _update_frontmatter_field(f, "status", "dropped")
-    _update_frontmatter_field(f, "archived", True)
-    return True
+    dropped = _update_frontmatter_field(f, "status", "dropped")
+    archived = _update_frontmatter_field(f, "archived", True)
+    return dropped and archived
 
 
 def list_drafts() -> list[dict]:
@@ -547,7 +544,12 @@ def promote_draft(
     body = meta.get("body", "")
 
     final_title = title or meta.get("title", slug)
-    final_type = (wiki_type or meta.get("draft_type", "concepts")).rstrip("s") + "s"
+    _type_dirs = {
+        "concept": "concepts", "concepts": "concepts",
+        "strategy": "strategies", "strategies": "strategies",
+        "anti-pattern": "anti-patterns", "anti-patterns": "anti-patterns",
+    }
+    final_type = _type_dirs.get(wiki_type or meta.get("draft_type", "concept"), "concepts")
     final_area = area or meta.get("draft_area", "computing")
     human_note = meta.get("source_note") or None
 

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4/open_knowledge_studio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-knowledge-studio
-Version: 0.2.2
+Version: 0.2.4
 Summary: File-based knowledge engineering CLI for Claude Code
 Author: open-agent-power
 License: MIT
@@ -42,16 +42,23 @@ a file-based knowledge base that turns raw material into a recallable, self-deca
 ## Install
 
 ```bash
-pip install open-knowledge-studio
+pipx install open-knowledge-studio && pipx ensurepath
 ```
 
+We recommend pipx because modern Linux (Ubuntu 24.04+) and macOS Homebrew Pythons are
+PEP 668 externally-managed, so a bare `pip install` fails. If your mirror lags behind
+PyPI, add `--pip-args="-i https://pypi.org/simple"`.
+
 Optional multimodal ingest (PDF / audio / video / formula extraction) lives in a
 separate, heavier package that you can pull in on demand:
 
 ```bash
-pip install "open-knowledge-studio[connector]"
+pipx inject open-knowledge-studio oks-connector
 ```
 
+(pipx apps share one venv without a standalone pip executable — `pipx inject` is how
+you add extras. In a plain venv, use `pip install "open-knowledge-studio[connector]"`.)
+
 ## What you get
 
 - **6+1-factor recall engine** — token overlap, substring, topic trace, type boost,
@@ -67,7 +74,7 @@ orchestrate the pipeline around it.
 ## Quick start
 
 ```bash
-pip install open-knowledge-studio   # 1. install the CLI
+pipx install open-knowledge-studio && pipx ensurepath   # 1. install the CLI
 oks init my-knowledge-base          # 2. scaffold an instance (skills + buckets)
 cd my-knowledge-base
 oks status                          # 3. use it

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/open_knowledge_studio.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
+setup.py
 knowledge_studio/__init__.py
 knowledge_studio/cli.py
 knowledge_studio/config.py

{open_knowledge_studio-0.2.2 → open_knowledge_studio-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "open-knowledge-studio"
-version = "0.2.2"
+version = "0.2.4"
 description = "File-based knowledge engineering CLI for Claude Code"
 readme = "README.md"
 license = {text = "MIT"}

open_knowledge_studio-0.2.4/setup.py

@@ -0,0 +1,42 @@
+"""Build hook: bundle the shareable asset layer during any source build.
+
+The repo root is the single source of truth for `.claude/`, `templates/`,
+`_meta/`, `settings/`. When building from a git checkout (pip install ./cli,
+pip install git+...#subdirectory=cli, python -m build), copy them into
+`knowledge_studio/_assets/` before build_py runs, so source installs are
+identical to PyPI wheels. When building from an sdist the repo root is
+absent and `_assets/` is already included via MANIFEST.in — skip silently.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+
+_MAP = [
+    (".claude", "claude"),
+    ("templates", "templates"),
+    ("_meta", "_meta"),
+    ("settings", "settings"),
+]
+
+
+class build_py_with_assets(build_py):
+    def run(self):
+        cli_dir = Path(__file__).resolve().parent
+        repo_root = cli_dir.parent
+        if (repo_root / ".claude").is_dir() and (repo_root / "templates").is_dir():
+            dest_root = cli_dir / "knowledge_studio" / "_assets"
+            if dest_root.exists():
+                shutil.rmtree(dest_root)
+            dest_root.mkdir(parents=True)
+            for src_name, dest_name in _MAP:
+                src = repo_root / src_name
+                if src.is_dir():
+                    shutil.copytree(src, dest_root / dest_name)
+        super().run()
+
+
+setup(cmdclass={"build_py": build_py_with_assets})

open_knowledge_studio-0.2.4/tests/test_init.py

@@ -0,0 +1,90 @@
+"""Tests for `oks init` — instance scaffolding + shareable-asset materialization."""
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from knowledge_studio.cli import app
+
+runner = CliRunner()
+
+
+def test_init_scaffolds_buckets_and_data_gitignore(tmp_path):
+    target = tmp_path / "kb"
+    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+    assert result.exit_code == 0, result.output
+
+    for d in ["wiki", "drafts", "raw", "profiles/goals", "settings", "_meta", "templates"]:
+        assert (target / d).is_dir(), f"missing bucket {d}"
+
+    gi = (target / ".gitignore").read_text(encoding="utf-8")
+    # instance gitignore ignores only per-machine state, and TRACKS memory
+    assert ".oks/" in gi
+    assert "wiki/**/*.md" not in gi
+    assert "drafts/*.md" not in gi
+
+
+def test_init_materializes_shareable_assets(tmp_path):
+    target = tmp_path / "kb"
+    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+    assert result.exit_code == 0, result.output
+
+    # skills + templates arrive so the Claude Code experience works out of the box
+    assert (target / ".claude" / "skills" / "ingest").is_dir()
+    assert (target / ".claude" / "settings.json").is_file()
+    assert (target / "templates").is_dir()
+
+
+def test_init_upgrade_refreshes_assets_but_keeps_user_files(tmp_path):
+    target = tmp_path / "kb"
+    runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+
+    marker = target / ".claude" / "MARKER.txt"
+    marker.write_text("local edit", encoding="utf-8")
+
+    bundled = target / ".claude" / "settings.json"
+    original = bundled.read_text(encoding="utf-8")
+    bundled.write_text("{}", encoding="utf-8")
+
+    # re-init without --upgrade keeps existing assets untouched
+    runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+    assert marker.exists()
+    assert bundled.read_text(encoding="utf-8") == "{}"
+
+    # --upgrade merge-copies bundled assets: bundled files refreshed,
+    # user-owned files (marker) survive — no more whole-tree deletion
+    runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default", "--upgrade"])
+    assert marker.exists()
+    assert bundled.read_text(encoding="utf-8") == original
+
+
+def test_init_requires_path_argument():
+    result = runner.invoke(app, ["init"])
+    assert result.exit_code != 0
+
+
+def test_init_aborts_on_nonempty_non_kb_dir(tmp_path):
+    target = tmp_path / "documents"
+    target.mkdir()
+    (target / "important.txt").write_text("do not touch", encoding="utf-8")
+
+    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+    assert result.exit_code == 1
+    assert not (target / "wiki").exists()
+
+    # --force overrides the guard
+    result = runner.invoke(
+        app, ["init", str(target), "--no-git", "--no-set-default", "--force"]
+    )
+    assert result.exit_code == 0, result.output
+    assert (target / "wiki").is_dir()
+    assert (target / "important.txt").exists()
+
+
+def test_init_rerun_on_existing_kb_is_idempotent(tmp_path):
+    target = tmp_path / "kb"
+    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+    assert result.exit_code == 0, result.output
+
+    # target now contains wiki/ → treated as an existing KB, no --force needed
+    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
+    assert result.exit_code == 0, result.output

open_knowledge_studio-0.2.2/tests/test_init.py

@@ -1,50 +0,0 @@
-"""Tests for `oks init` — instance scaffolding + shareable-asset materialization."""
-from pathlib import Path
-
-from typer.testing import CliRunner
-
-from knowledge_studio.cli import app
-
-runner = CliRunner()
-
-
-def test_init_scaffolds_buckets_and_data_gitignore(tmp_path):
-    target = tmp_path / "kb"
-    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
-    assert result.exit_code == 0, result.output
-
-    for d in ["wiki", "drafts", "raw", "profiles/goals", "settings", "_meta", "templates"]:
-        assert (target / d).is_dir(), f"missing bucket {d}"
-
-    gi = (target / ".gitignore").read_text(encoding="utf-8")
-    # instance gitignore ignores only per-machine state, and TRACKS memory
-    assert ".oks/" in gi
-    assert "wiki/**/*.md" not in gi
-    assert "drafts/*.md" not in gi
-
-
-def test_init_materializes_shareable_assets(tmp_path):
-    target = tmp_path / "kb"
-    result = runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
-    assert result.exit_code == 0, result.output
-
-    # skills + templates arrive so the Claude Code experience works out of the box
-    assert (target / ".claude" / "skills" / "ingest").is_dir()
-    assert (target / ".claude" / "settings.json").is_file()
-    assert (target / "templates").is_dir()
-
-
-def test_init_upgrade_refreshes_assets(tmp_path):
-    target = tmp_path / "kb"
-    runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
-
-    marker = target / ".claude" / "MARKER.txt"
-    marker.write_text("local edit", encoding="utf-8")
-
-    # re-init without --upgrade keeps existing assets (marker survives)
-    runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default"])
-    assert marker.exists()
-
-    # --upgrade re-copies bundled assets, dropping the local marker
-    runner.invoke(app, ["init", str(target), "--no-git", "--no-set-default", "--upgrade"])
-    assert not marker.exists()