jsonpit 4.4.3__tar.gz → 4.4.4__tar.gz

{jsonpit-4.4.3 → jsonpit-4.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 4.4.3
+Version: 4.4.4
 Summary: Daemon-free distributed storage over Cloud Drives for developers and AI agents — multi-process, immutable history, zero dependencies.
 Author: Dr. Rainer Burkhardt
 License-Expression: Apache-2.0
@@ -31,14 +31,14 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
-## Cross-Tool & Cross-Language Version Alignment (`v4.4.3`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.4`)
 
-`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.3`** in direct lockstep with C# `JsonPit` and `pits 4.4.3` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.4`** in direct lockstep with C# `JsonPit` and `pits 4.4.4` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
 
 ### Why Harmonized Versioning is Essential:
 - **Instant Compatibility Clarity:** Operators, DevOps pipelines, and autonomous AI agents immediately know whether `jpit` and `pits` share the exact same distributed protocol revision. If both tools report `4.4.x`, they guarantee identical master leasing rules, receipt mechanisms, 7-digit UTC timestamp parsing, and CR041 clean change file conventions.
 - **Elimination of Multi-Language Matrix Confusion:** In heterogeneous environments (e.g. C# backend daemons paired with Python agent orchestrators and data science tooling), unified SemVer tags eliminate complex cross-compatibility lookup tables.
-- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules and CR041 clean change file formatting) are certified across both languages under the exact same version milestone before release.
+- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules, CR041 clean change file formatting, and CR044 missing configuration diagnostics) are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -54,6 +54,69 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
+## Installation & Upgrade
+
+### As a Global CLI Tool (`jpit`) via `pipx` (Recommended)
+To run the `jpit` command-line companion anywhere across your machine in an isolated environment without polluting system packages:
+
+```bash
+# Install globally
+pipx install jsonpit
+# (or via companion alias)
+pipx install jpit
+
+# Upgrade to the latest lockstep release (v4.4.4)
+pipx upgrade jsonpit
+# (or)
+pipx upgrade jpit
+```
+
+### In a Project / Virtual Environment via `pip`
+To embed `jsonpit` into your Python applications, data science workflows, or agentic runtimes:
+
+```bash
+# Install
+pip install jsonpit
+
+# Upgrade to the latest release
+pip install --upgrade jsonpit
+```
+
+### Upgrading with Multi-Python / `pyenv` Environments
+If you maintain multiple Python versions on your machine (e.g. 3.12, 3.13, 3.14):
+
+1. **Always anchor `pip` to your active Python interpreter:**
+   ```bash
+   python -m pip install --upgrade jpit
+   ```
+   *(Avoid bare `pip install`: invoking `pip` directly may resolve to an older Python version in `$PATH`, installing the package into the wrong runtime).*
+
+2. **If using `pyenv`, regenerate shims:**
+   ```bash
+   pyenv rehash
+   ```
+   *This ensures `which jpit` resolves to `~/.pyenv/shims/jpit`, which dynamically routes to whichever Python version is currently active in your shell.*
+
+3. **Verify the active executable:**
+   ```bash
+   which jpit
+   jpit --version
+   ```
+
+> [!TIP]
+> **Encountering `error: externally-managed-environment` (Homebrew Python or modern Linux / PEP 668)?**  
+> Modern Homebrew and Linux package managers protect their system Python prefix by default. You have two clean options:
+> - **Option A (Isolated CLI via `pipx`):** Run `brew install pipx && pipx ensurepath`, then `pipx install jpit`.
+> - **Option B (Direct install into Homebrew Python):** Pass `--break-system-packages`:
+>   ```bash
+>   python -m pip install --upgrade --break-system-packages jpit
+>   ```
+>   *(Completely safe: `jsonpit` has zero runtime dependencies and cannot break system packages).*
+
+*(Both the `jsonpit` library package and the `jpit` companion package provide both `jpit` and `jsonpit` command-line executables).*
+
+---
+
 ## Quickstart
 
 ### 1. Cloud-First Triad (The Standard Pattern)

{jsonpit-4.4.3 → jsonpit-4.4.4}/README.md

@@ -9,14 +9,14 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
-## Cross-Tool & Cross-Language Version Alignment (`v4.4.3`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.4`)
 
-`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.3`** in direct lockstep with C# `JsonPit` and `pits 4.4.3` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.4`** in direct lockstep with C# `JsonPit` and `pits 4.4.4` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
 
 ### Why Harmonized Versioning is Essential:
 - **Instant Compatibility Clarity:** Operators, DevOps pipelines, and autonomous AI agents immediately know whether `jpit` and `pits` share the exact same distributed protocol revision. If both tools report `4.4.x`, they guarantee identical master leasing rules, receipt mechanisms, 7-digit UTC timestamp parsing, and CR041 clean change file conventions.
 - **Elimination of Multi-Language Matrix Confusion:** In heterogeneous environments (e.g. C# backend daemons paired with Python agent orchestrators and data science tooling), unified SemVer tags eliminate complex cross-compatibility lookup tables.
-- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules and CR041 clean change file formatting) are certified across both languages under the exact same version milestone before release.
+- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules, CR041 clean change file formatting, and CR044 missing configuration diagnostics) are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -32,6 +32,69 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
+## Installation & Upgrade
+
+### As a Global CLI Tool (`jpit`) via `pipx` (Recommended)
+To run the `jpit` command-line companion anywhere across your machine in an isolated environment without polluting system packages:
+
+```bash
+# Install globally
+pipx install jsonpit
+# (or via companion alias)
+pipx install jpit
+
+# Upgrade to the latest lockstep release (v4.4.4)
+pipx upgrade jsonpit
+# (or)
+pipx upgrade jpit
+```
+
+### In a Project / Virtual Environment via `pip`
+To embed `jsonpit` into your Python applications, data science workflows, or agentic runtimes:
+
+```bash
+# Install
+pip install jsonpit
+
+# Upgrade to the latest release
+pip install --upgrade jsonpit
+```
+
+### Upgrading with Multi-Python / `pyenv` Environments
+If you maintain multiple Python versions on your machine (e.g. 3.12, 3.13, 3.14):
+
+1. **Always anchor `pip` to your active Python interpreter:**
+   ```bash
+   python -m pip install --upgrade jpit
+   ```
+   *(Avoid bare `pip install`: invoking `pip` directly may resolve to an older Python version in `$PATH`, installing the package into the wrong runtime).*
+
+2. **If using `pyenv`, regenerate shims:**
+   ```bash
+   pyenv rehash
+   ```
+   *This ensures `which jpit` resolves to `~/.pyenv/shims/jpit`, which dynamically routes to whichever Python version is currently active in your shell.*
+
+3. **Verify the active executable:**
+   ```bash
+   which jpit
+   jpit --version
+   ```
+
+> [!TIP]
+> **Encountering `error: externally-managed-environment` (Homebrew Python or modern Linux / PEP 668)?**  
+> Modern Homebrew and Linux package managers protect their system Python prefix by default. You have two clean options:
+> - **Option A (Isolated CLI via `pipx`):** Run `brew install pipx && pipx ensurepath`, then `pipx install jpit`.
+> - **Option B (Direct install into Homebrew Python):** Pass `--break-system-packages`:
+>   ```bash
+>   python -m pip install --upgrade --break-system-packages jpit
+>   ```
+>   *(Completely safe: `jsonpit` has zero runtime dependencies and cannot break system packages).*
+
+*(Both the `jsonpit` library package and the `jpit` companion package provide both `jpit` and `jsonpit` command-line executables).*
+
+---
+
 ## Quickstart
 
 ### 1. Cloud-First Triad (The Standard Pattern)

{jsonpit-4.4.3 → jsonpit-4.4.4}/jsonpit/__init__.py

@@ -12,7 +12,7 @@ from .exceptions import (
 	ProtectedAttributeError,
 	TombstoneError,
 )
-from .fs import OsConfig
+from .config import DEFAULT_CONFIG_FILE_LOCATION, OsConfig, missing_configuration_diagnostic
 from .history import PitItems
 from .icons import Icons
 from .item import PitItem
@@ -22,7 +22,7 @@ try:
 	import importlib.metadata
 	__version__ = importlib.metadata.version("jsonpit")
 except Exception:
-	__version__ = "4.4.3"
+	__version__ = "4.4.4"
 
 __all__ = [
 	"Pit",
@@ -31,6 +31,8 @@ __all__ = [
 	"PitItem",
 	"PitItems",
 	"OsConfig",
+	"DEFAULT_CONFIG_FILE_LOCATION",
+	"missing_configuration_diagnostic",
 	"Icons",
 	"JsonPitError",
 	"PitNotFoundError",

{jsonpit-4.4.3 → jsonpit-4.4.4}/jsonpit/cli.py

@@ -19,7 +19,7 @@ import sys
 from typing import Any
 
 from .canonical import canonical_json, format_iso_timestamp, parse_iso_timestamp, utcnow
-from .config import OsConfig, loads_json5
+from .config import OsConfig, loads_json5, missing_configuration_diagnostic
 from .exceptions import JsonPitError, PitNotFoundError, ProtectedAttributeError
 from .fs import resolve_pit_target
 from .item import PitItem
@@ -70,21 +70,39 @@ def discover_pits(
 			return discovered_cwd
 
 	# Check if target is a single pit or an explicit directory
-	try:
-		p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
-		if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
-			return [(p_dir, p_name)]
-	except Exception:
-		pass
-
-	# Check if target is a tenant/root folder containing multiple pit directories
+	raw_str = str(target).strip()
+	is_explicit_path = (
+		raw_str.startswith(("/", "~", ".", "\\"))
+		or ("/" in raw_str and not raw_str.startswith("-"))
+		or ("\\" in raw_str)
+		or Path(raw_str).exists()
+	)
+	if is_explicit_path:
+		try:
+			p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
+			if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
+				return [(p_dir, p_name)]
+		except Exception:
+			pass
+		if Path(target).is_dir():
+			discovered = []
+			for child in sorted(Path(target).iterdir()):
+				if child.is_dir():
+					pit_file = child / f"{child.name}.pit"
+					if pit_file.is_file():
+						discovered.append((child, child.name))
+			if discovered:
+				return discovered
+
+	# Target requires cloud resolution
 	cfg = OsConfig.load()
+	if not cfg.is_config_loaded and not is_explicit_path:
+		raise PitNotFoundError(missing_configuration_diagnostic())
+
 	cloud_root = cfg.get_cloud_root(cloud)
 	candidates: list[Path] = []
 	if cloud_root and (cloud_root / target).is_dir():
 		candidates.append(cloud_root / target)
-	if Path(target).is_dir():
-		candidates.append(Path(target))
 
 	discovered: list[tuple[Path, str]] = []
 	for candidate_root in candidates:
@@ -97,13 +115,10 @@ def discover_pits(
 	if discovered:
 		return discovered
 
-	# Fallback single pit target (only return if it physically exists)
-	try:
-		p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
-		if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
-			return [(p_dir, p_name)]
-	except Exception:
-		pass
+	# Fallback single pit target
+	p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
+	if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
+		return [(p_dir, p_name)]
 	return []
 
 
@@ -111,17 +126,16 @@ def discover_root_pits(root: str | None, cloud: str | None = "OneDrive") -> list
 	"""Discovers all pit names under a resolved tenant root directory."""
 	if not root:
 		return []
-	cfg = OsConfig.load()
-	cloud_root = cfg.get_cloud_root(cloud or "OneDrive")
-	candidate: Path | None = None
-	if cloud_root and (cloud_root / root).is_dir():
-		candidate = cloud_root / root
+	raw_str = str(root).strip()
+	p = Path(os.path.expanduser(raw_str))
+	if p.is_dir():
+		candidate: Path | None = p
 	else:
-		p = Path(os.path.expanduser(root))
-		if p.is_dir():
-			candidate = p
-		elif cloud_root:
-			candidate = cloud_root / root
+		cfg = OsConfig.load()
+		if not cfg.is_config_loaded:
+			raise PitNotFoundError(missing_configuration_diagnostic())
+		cloud_root = cfg.get_cloud_root(cloud or "OneDrive")
+		candidate = cloud_root / root if cloud_root else None
 
 	if not candidate or not candidate.is_dir():
 		return []
@@ -735,7 +749,10 @@ def print_top_help(
 	# Dynamic Pits Discovery line
 	pits_title = color(f"{Icons.INFO} PitNames", C_CYAN, use_color)
 	if root:
-		discovered = discover_root_pits(root, cloud)
+		try:
+			discovered = discover_root_pits(root, cloud)
+		except Exception:
+			discovered = []
 		if discovered:
 			formatted_pits = []
 			for idx, p in enumerate(discovered):

{jsonpit-4.4.3 → jsonpit-4.4.4}/jsonpit/config.py

@@ -217,6 +217,20 @@ def loads_json5(text: str) -> Any:
 	return parse_value()
 
 
+DEFAULT_CONFIG_FILE_LOCATION: str = "~/.config/RAIkeep.json5"
+
+
+def missing_configuration_diagnostic() -> str:
+	"""
+	CR044 §7.4: Standardized diagnostic when RAIkeep configuration is not found.
+	Directs the operator to 'amafu init'.
+	"""
+	return (
+		f"RAIkeep configuration was not found at '{DEFAULT_CONFIG_FILE_LOCATION}'. "
+		"Run 'amafu init' to detect cloud providers and create it."
+	)
+
+
 class OsConfig:
 	"""
 	System configuration derived from ~/.config/RAIkeep.json5 or fallback files.
@@ -253,6 +267,16 @@ class OsConfig:
 				if path_str:
 					self.clouds[name] = self._normalize_path(str(path_str))
 
+	@property
+	def is_config_loaded(self) -> bool:
+		"""Returns True if configuration was loaded from a file or explicit dictionary."""
+		return self._config_path is not None or bool(self.clouds)
+
+	@classmethod
+	def reset(cls) -> None:
+		"""Resets the singleton instance (used in tests)."""
+		cls._instance = None
+
 	@staticmethod
 	def _normalize_path(p: str) -> Path:
 		expanded = os.path.expanduser(p.strip())

{jsonpit-4.4.3 → jsonpit-4.4.4}/jsonpit/fs.py

@@ -11,7 +11,7 @@ import shutil
 from pathlib import Path
 from typing import Any
 
-from .config import OsConfig
+from .config import DEFAULT_CONFIG_FILE_LOCATION, OsConfig, missing_configuration_diagnostic
 from .exceptions import PitNotFoundError
 
 
@@ -52,12 +52,16 @@ def resolve_pit_target(
 			pit_name = resolved.name
 		return pit_dir, pit_name
 
+	# CR044 §7.4: If attempting cloud triad resolution and no configuration file exists
+	if not cfg.is_config_loaded:
+		raise PitNotFoundError(missing_configuration_diagnostic())
+
 	# Cloud triad resolution (e.g. name="Person", cloud="OneDrive", root="AfricaStage")
 	cloud_root = cfg.get_cloud_root(cloud)
 	if cloud_root is None:
 		raise PitNotFoundError(
 			f"Could not resolve cloud storage root for cloud '{cloud or 'default'}'. "
-			"Ensure ~/.config/RAIkeep.json5 or ~/.config/jsonpit.json5 is configured."
+			f"Ensure {DEFAULT_CONFIG_FILE_LOCATION} or ~/.config/jsonpit.json5 is configured."
 		)
 
 	pit_name = raw_str

{jsonpit-4.4.3 → jsonpit-4.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jsonpit"
-version = "4.4.3"
+version = "4.4.4"
 description = "Daemon-free distributed storage over Cloud Drives for developers and AI agents — multi-process, immutable history, zero dependencies."
 readme = "README.md"
 requires-python = ">=3.12"