filekeeper-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filekeeper-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: Safe, predictable filesystem operations for humans and AI agents, with atomic writes and workspace confinement.
 Keywords: filesystem,atomic-write,cli,agents,mcp
 Author: sangingeum
@@ -150,6 +150,12 @@ home directory instead. The trade-off: history survives deleting the checkout, b
 per-project attribution and pruning become harder, and undo history no longer
 travels with the tree.
 
+If the workspace root cannot host `.filekeeper/` — a read-only checkout, or a root
+at `/` — Filekeeper falls back to the global store and says so in the response.
+`keeper init` writes the setting only as a commented example, so that fallback
+stays available; uncomment the key to pin the choice, and a project-local choice
+then fails loudly instead of being redirected.
+
 If the workspace is a git repository, Filekeeper adds `.filekeeper/` to
 `.gitignore` when it creates the state directory. Outside a repository it writes
 nothing.

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/README.md

@@ -129,6 +129,12 @@ home directory instead. The trade-off: history survives deleting the checkout, b
 per-project attribution and pruning become harder, and undo history no longer
 travels with the tree.
 
+If the workspace root cannot host `.filekeeper/` — a read-only checkout, or a root
+at `/` — Filekeeper falls back to the global store and says so in the response.
+`keeper init` writes the setting only as a commented example, so that fallback
+stays available; uncomment the key to pin the choice, and a project-local choice
+then fails loudly instead of being redirected.
+
 If the workspace is a git repository, Filekeeper adds `.filekeeper/` to
 `.gitignore` when it creates the state directory. Outside a repository it writes
 nothing.

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "Safe, predictable filesystem operations for humans and AI agents, with atomic writes and workspace confinement."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "Safe, predictable filesystem operations for humans and AI agents, with atomic writes and workspace confinement."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/src/filekeeper/__init__.py

@@ -21,7 +21,7 @@ from .core import (
     Workspace,
 )
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = [
     "Config",

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/src/filekeeper/core/config.py

@@ -11,7 +11,9 @@ Two kinds of state exist, and they live in different places on purpose:
 
 ``config.toml`` in the home directory holds tunable limits. It is read on every
 invocation; writing it is left to the user (``keeper init`` creates it with the
-defaults spelled out).
+defaults spelled out). ``state_location`` is written only as a commented example:
+a generated file must not turn a default into an explicit operator decision,
+because an explicit decision refuses the global fallback.
 """
 
 from __future__ import annotations
@@ -133,7 +135,15 @@ max_history_blob_bytes = 4194304
 # parent directory before reporting success.
 fsync = true
 
-# "project" keeps per-workspace state in <workspace>/.filekeeper/ (default).
-# "global" keeps one shared store under this home directory instead.
-state_location = "project"
+# Per-workspace state lives in <workspace>/.filekeeper/ by default. When the
+# workspace root cannot host that directory (a read-only checkout, or a root at
+# /), Filekeeper falls back to the global store under this home directory and
+# says so in the response.
+#
+# Uncommenting the next line pins the choice instead of leaving it at the
+# built-in default. "project" then fails loudly when the root cannot host the
+# directory instead of being redirected; "global" always uses the shared store.
+# An uncommented key is an operator decision, so keep it commented unless you
+# mean it.
+# state_location = "project"
 """

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/src/filekeeper/core/database.py

@@ -135,15 +135,20 @@ def uuid_token() -> str:
     return uuid.uuid4().hex[:16]
 
 
-def connect(path: Path) -> sqlite3.Connection:
-    """Open a SQLite database with durable, foreign-key-enforcing settings."""
+def connect(path: Path, *, display: str = "the Filekeeper state store") -> sqlite3.Connection:
+    """Open a SQLite database with durable, foreign-key-enforcing settings.
+
+    ``display`` is the caller-facing name of the directory holding the database.
+    A public error envelope never carries the resolved host path; the reason
+    phrase is all the message needs.
+    """
 
     try:
         path.parent.mkdir(parents=True, exist_ok=True)
     except OSError as exc:
         raise StorageError(
             f"cannot create state directory: {exc.strerror or type(exc).__name__}",
-            details={"state_dir": str(path.parent)},
+            details={"state_dir": display},
         ) from exc
     try:
         os.chmod(path.parent, stat.S_IRWXU)
@@ -152,7 +157,7 @@ def connect(path: Path) -> sqlite3.Connection:
     try:
         connection = sqlite3.connect(path, timeout=10.0)
     except sqlite3.Error as exc:
-        raise StorageError(f"cannot open database: {exc}", details={"path": str(path)}) from exc
+        raise StorageError(f"cannot open database: {exc}", details={"path": display}) from exc
     connection.row_factory = sqlite3.Row
     connection.execute("PRAGMA journal_mode = WAL")
     # Full synchronous mode: a committed record survives an OS crash, which the
@@ -216,14 +221,18 @@ def migrate_workspace(connection: sqlite3.Connection) -> int:
     return migrate(connection, _WORKSPACE_MIGRATIONS, label="workspace")
 
 
-def open_registry_database(path: Path) -> sqlite3.Connection:
-    connection = connect(path)
+def open_registry_database(
+    path: Path, *, display: str = "the Filekeeper home directory"
+) -> sqlite3.Connection:
+    connection = connect(path, display=display)
     migrate_registry(connection)
     return connection
 
 
-def open_workspace_database(path: Path) -> sqlite3.Connection:
-    connection = connect(path)
+def open_workspace_database(
+    path: Path, *, display: str = "the workspace state directory"
+) -> sqlite3.Connection:
+    connection = connect(path, display=display)
     migrate_workspace(connection)
     try:
         os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/src/filekeeper/core/service.py

@@ -219,21 +219,24 @@ class FilekeeperService:
         if self.registered and self.handle.workspace_id is not None:
             workspace = self.owner.registry.get(self.handle.name)
             return self.owner.registry.ensure_state_dir(workspace)
-        return ensure_state_directory(self.handle.state_dir, root=self.root)
+        return ensure_state_directory(
+            self.handle.state_dir, root=self.root, home=self.owner.home
+        )
 
     def blob_store(self) -> BlobStore:
         return BlobStore(self.state_database_path().parent / "blobs", fsync=self.config.fsync)
 
     def _journal_for(self, dry_run: bool) -> OperationJournal | None:
-        """The journal a mutation will record into, or a verified ``None``.
+        """The journal a mutation will record into, or ``None`` for a dry run.
 
-        A dry run writes no history, but it still proves that the journal can be
-        opened: a preview must never report success for a call the real
-        operation could not perform.
+        A dry run has nothing to journal, so it touches no state at all: it does
+        not create the state directory, open the database or write a blob. That
+        makes a preview readable even where the real operation would be refused —
+        which is the point of a preview, and why a preview that failed on state
+        creation was not a preview.
         """
 
         if dry_run:
-            self.state_database_path()
             return None
         return self.history
 

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.4}/src/filekeeper/core/workspace.py

@@ -69,6 +69,30 @@ def global_workspace_state_dir(workspace_id: str, home: Path) -> Path:
     return Path(home) / "workspaces" / workspace_id
 
 
+def display_state_location(
+    state_dir: Path, *, root: Path | None, home: Path | None
+) -> str:
+    """Render a state directory without naming an absolute host path.
+
+    A public error envelope is read by a caller confined to the workspace, so a
+    resolved host path there tells them nothing they can use and describes the
+    host tree. The workspace-relative form is preferred; a global store outside
+    the workspace is rendered relative to the home directory; anything else falls
+    back to prose. The value stays meaningful, which is what the operator needs
+    in order to fix the deployment.
+    """
+
+    for base in (root, home):
+        if base is None:
+            continue
+        try:
+            relative = Path(state_dir).relative_to(Path(base)).as_posix()
+        except ValueError:
+            continue
+        return relative or "."
+    return "the global Filekeeper state store"
+
+
 def _directory_usable(directory: Path) -> bool:
     """Whether ``directory`` exists and is writable, or can be created."""
 
@@ -157,27 +181,31 @@ def handle_for(workspace: Workspace, config: Config, home: Path) -> WorkspaceHan
     )
 
 
-def ensure_state_directory(state_dir: Path, *, root: Path | None = None) -> Path:
+def ensure_state_directory(
+    state_dir: Path, *, root: Path | None = None, home: Path | None = None
+) -> Path:
     """Create the state directory and its migrated database; return the DB path.
 
     Every filesystem failure here is a :class:`StorageError` naming the state
-    directory the operator chose. It is never an ``INTERNAL_ERROR``, and the
-    message carries only the reason phrase, never a resolved host path.
+    directory the operator chose. It is never an ``INTERNAL_ERROR``, and neither
+    the message nor the details carry a resolved host path: the location is
+    rendered workspace-relative (or home-relative for the global store).
     """
 
+    display = display_state_location(state_dir, root=root, home=home)
     try:
         state_dir.mkdir(parents=True, exist_ok=True)
         state_dir.chmod(stat.S_IRWXU)
     except OSError as exc:
         raise StorageError(
             f"cannot create state directory: {exc.strerror or type(exc).__name__}",
-            details={"state_dir": str(state_dir)},
+            details={"state_dir": display},
         ) from exc
     if root is not None and state_dir.parent == root:
         # Only a project-local directory belongs in the tree's ignore rules.
         ensure_gitignore_entry(root)
     database_path = state_dir / STATE_DATABASE_NAME
-    connection = database.open_workspace_database(database_path)
+    connection = database.open_workspace_database(database_path, display=display)
     connection.close()
     return database_path
 
@@ -228,7 +256,7 @@ class WorkspaceRegistry:
             raise StorageError(
                 f"cannot create the Filekeeper home directory: "
                 f"{exc.strerror or type(exc).__name__}",
-                details={"state_dir": str(self.home)},
+                details={"state_dir": "the Filekeeper home directory"},
             ) from exc
         try:
             self.home.chmod(stat.S_IRWXU)
@@ -399,7 +427,9 @@ class WorkspaceRegistry:
         """
 
         return ensure_state_directory(
-            self.state_dir_for(workspace), root=Path(workspace.root_path)
+            self.state_dir_for(workspace),
+            root=Path(workspace.root_path),
+            home=self.home,
         )