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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filekeeper-cli
-Version: 0.1.2
+Version: 0.1.3
 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

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

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.2"
+version = "0.1.3"
 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.2 → filekeeper_cli-0.1.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.2"
+version = "0.1.3"
 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.2 → filekeeper_cli-0.1.3}/src/filekeeper/__init__.py

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

{filekeeper_cli-0.1.2 → filekeeper_cli-0.1.3}/src/filekeeper/cli/app.py

@@ -408,11 +408,30 @@ class _Context:
             )
         return self._service
 
+    def state_warnings(self) -> tuple[str, ...]:
+        """Warnings that explain where durable state went for this workspace."""
+
+        if self._service is None:
+            return ()
+        warning = self._service.handle.state_warning
+        return () if warning is None else (warning,)
+
     def emit(self, payload: dict[str, object], text: str) -> None:
+        warnings = self.state_warnings()
+        if warnings:
+            existing = payload.get("warnings")
+            merged = list(existing) if isinstance(existing, list) else []
+            for warning in warnings:
+                if warning not in merged:
+                    merged.append(warning)
+            payload = {**payload, "warnings": merged}
         if self.as_json:
             output.print_json(payload)
-        elif text:
+            return
+        if text:
             sys.stdout.write(text if text.endswith("\n") else text + "\n")
+        for warning in warnings:
+            sys.stderr.write(f"warning: {warning}\n")
 
 
 def _content_from_args(args: argparse.Namespace) -> str:

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

@@ -40,6 +40,11 @@ class Config:
     max_history_blob_bytes: int = 4 * 1024 * 1024
     fsync: bool = True
     state_location: str = "project"
+    # True only when the configuration file named ``state_location`` explicitly.
+    # A workspace whose root cannot host its state directory may fall back to the
+    # global store when the setting was left at the default, but an explicit
+    # operator choice is honoured and fails loudly instead of being redirected.
+    state_location_explicit: bool = False
 
     def __post_init__(self) -> None:
         if self.state_location not in {"project", "global"}:
@@ -93,13 +98,14 @@ def load_config(home: Path) -> Config:
     if not isinstance(section, dict):
         raise StorageError("configuration file must contain a table", details={"path": str(path)})
 
-    known = {field_info.name for field_info in fields(Config)}
+    known = {field_info.name for field_info in fields(Config)} - {"state_location_explicit"}
     values: dict[str, object] = {}
     for key, value in section.items():
         if key in known:
             values[key] = value
     try:
-        return Config(**values)  # type: ignore[arg-type]
+        explicit = "state_location" in section
+        return Config(**values, state_location_explicit=explicit)  # type: ignore[arg-type]
     except TypeError as exc:
         raise StorageError(
             f"invalid configuration value: {exc}", details={"path": str(path)}

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

@@ -138,7 +138,13 @@ def uuid_token() -> str:
 def connect(path: Path) -> sqlite3.Connection:
     """Open a SQLite database with durable, foreign-key-enforcing settings."""
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    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)},
+        ) from exc
     try:
         os.chmod(path.parent, stat.S_IRWXU)
     except OSError:  # pragma: no cover - restricted filesystems

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

@@ -14,6 +14,7 @@ values inside results, never their fields.
 
 from __future__ import annotations
 
+import hashlib
 from pathlib import Path
 
 from . import database, operations
@@ -50,9 +51,26 @@ from .workspace import (
     STATE_DATABASE_NAME,
     WorkspaceHandle,
     WorkspaceRegistry,
+    ensure_state_directory,
     handle_for,
 )
 
+TRANSIENT_ID_PREFIX = "ws-transient-"
+TRANSIENT_ID_LENGTH = 16
+
+
+def transient_workspace_id(root: str | Path) -> str:
+    """A stable id for the transient workspace rooted at ``root``.
+
+    Durable state is keyed by workspace id, so the id must survive a process
+    restart: it is derived from the canonical absolute root rather than drawn
+    at random.
+    """
+
+    canonical = str(Path(root).expanduser().resolve())
+    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return f"{TRANSIENT_ID_PREFIX}{digest[:TRANSIENT_ID_LENGTH]}"
+
 
 def init_home(home: Path | None = None) -> Path:
     """Create the home directory, default configuration and registry database."""
@@ -135,7 +153,7 @@ class Filekeeper:
             if registered is not None:
                 return FilekeeperService(handle_for(registered, self.config, self.home), self)
             transient = Workspace(
-                id=f"ws-transient-{database.uuid_token()}",
+                id=transient_workspace_id(candidate),
                 name=candidate.name or "workspace",
                 root_path=str(candidate),
                 created_at=database.utc_now(),
@@ -201,16 +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)
-        state_dir = self.handle.state_dir
-        state_dir.mkdir(parents=True, exist_ok=True)
-        target = state_dir / STATE_DATABASE_NAME
-        connection = database.open_workspace_database(target)
-        connection.close()
-        return target
+        return ensure_state_directory(self.handle.state_dir, root=self.root)
 
     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``.
+
+        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.
+        """
+
+        if dry_run:
+            self.state_database_path()
+            return None
+        return self.history
+
     # -- history ------------------------------------------------------------
     def _open_journal(self, *, create: bool) -> OperationJournal | None:
         """Return the journal, reconciling pending work once per service instance.
@@ -413,7 +439,7 @@ class FilekeeperService:
             encoding=encoding,
             allow_sensitive_write=allow_sensitive_write,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -438,7 +464,7 @@ class FilekeeperService:
             encoding=encoding,
             allow_sensitive_write=allow_sensitive_write,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -461,7 +487,7 @@ class FilekeeperService:
             expected_destination_hash=expected_destination_hash,
             allow_sensitive_write=allow_sensitive_write,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -484,7 +510,7 @@ class FilekeeperService:
             overwrite=overwrite,
             allow_sensitive_write=allow_sensitive_write,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -503,7 +529,7 @@ class FilekeeperService:
             path,
             expected_hash=expected_hash,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -535,7 +561,7 @@ class FilekeeperService:
             expected_match_count=expected_match_count,
             allow_sensitive_write=allow_sensitive_write,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -562,7 +588,7 @@ class FilekeeperService:
             expected_content=expected_content,
             expected_hash=expected_hash,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -589,7 +615,7 @@ class FilekeeperService:
             expected_content=expected_content,
             expected_hash=expected_hash,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -614,7 +640,7 @@ class FilekeeperService:
             expected_content=expected_content,
             expected_hash=expected_hash,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -633,7 +659,7 @@ class FilekeeperService:
             patch_text,
             allow_sensitive_write=allow_sensitive_write,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -652,7 +678,7 @@ class FilekeeperService:
             path,
             parents=parents,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -671,7 +697,7 @@ class FilekeeperService:
             source,
             destination,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )
@@ -692,7 +718,7 @@ class FilekeeperService:
             recursive=recursive,
             confirm_recursive=confirm_recursive,
             dry_run=dry_run,
-            journal=None if dry_run else self.history,
+            journal=self._journal_for(dry_run),
             actor=actor,
             task_id=task_id,
         )

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

@@ -3,10 +3,16 @@
 A workspace is a registered directory that bounds every operation. Registration
 lives in the home database; the workspace's own state directory lives in the tree
 by default so that history and blobs travel with the checkout.
+
+When the tree cannot host that directory — a read-only checkout, or a workspace
+root at ``/`` — the deployment still works: the state directory falls back to the
+global store and the response says so. An operator who named ``state_location``
+explicitly gets the failure instead, because that choice is theirs to make.
 """
 
 from __future__ import annotations
 
+import os
 import re
 import sqlite3
 import stat
@@ -29,6 +35,13 @@ DEFAULT_WORKSPACE_KEY: Final = "default_workspace"
 STATE_DATABASE_NAME: Final = "state.sqlite3"
 GITIGNORE_ENTRY: Final = f"{STATE_DIR_NAME}/"
 
+# Names the fallback without naming a host path: the message is rendered to
+# callers who are confined to the workspace.
+GLOBAL_FALLBACK_WARNING: Final = (
+    "the workspace root cannot host a state directory, so history is kept in "
+    "the global Filekeeper state store instead of a project-local directory"
+)
+
 
 @dataclass(frozen=True, slots=True)
 class WorkspaceHandle:
@@ -39,31 +52,136 @@ class WorkspaceHandle:
     workspace_id: str | None
     config: Config
     state_dir: Path
+    state_warning: str | None = None
 
 
-def workspace_state_dir(workspace: Workspace, config: Config, home: Path) -> Path:
-    """Where this workspace's journal and blobs live.
+@dataclass(frozen=True, slots=True)
+class StateLocation:
+    """A resolved state directory plus the warning that explains a fallback."""
+
+    directory: Path
+    warning: str | None = None
+
+
+def global_workspace_state_dir(workspace_id: str, home: Path) -> Path:
+    """The global store's directory for one workspace id."""
+
+    return Path(home) / "workspaces" / workspace_id
+
+
+def _directory_usable(directory: Path) -> bool:
+    """Whether ``directory`` exists and is writable, or can be created."""
+
+    try:
+        if directory.exists():
+            return directory.is_dir() and os.access(directory, os.W_OK | os.X_OK)
+        parent = directory.parent
+        return parent.is_dir() and os.access(parent, os.W_OK | os.X_OK)
+    except OSError:  # pragma: no cover - unreadable ancestors
+        return False
+
+
+def resolve_state_location(workspace: Workspace, config: Config, home: Path) -> StateLocation:
+    """Where this workspace's journal and blobs live, after checking usability.
 
     Project-local is the default: ``<root>/.filekeeper``. Global mode keeps one
     directory per workspace id under the home store, so projects can still be
-    attributed and pruned individually.
+    attributed and pruned individually. When the root cannot host the project
+    directory and the operator did not choose a location explicitly, the global
+    store is used and the returned warning says so.
     """
 
     if config.state_location == "global":
-        return home / "workspaces" / workspace.id
-    return Path(workspace.root_path) / STATE_DIR_NAME
+        return StateLocation(global_workspace_state_dir(workspace.id, home))
+    project_local = Path(workspace.root_path) / STATE_DIR_NAME
+    if _directory_usable(project_local):
+        return StateLocation(project_local)
+    if config.state_location_explicit:
+        # The operator asked for project-local state; do not redirect it.
+        return StateLocation(project_local)
+    return StateLocation(
+        global_workspace_state_dir(workspace.id, home), GLOBAL_FALLBACK_WARNING
+    )
+
+
+def workspace_state_dir(workspace: Workspace, config: Config, home: Path) -> Path:
+    """The state directory only, without the fallback explanation."""
+
+    return resolve_state_location(workspace, config, home).directory
+
+
+def _unattributed_history_note(workspace_id: str, state_dir: Path) -> str | None:
+    """Name earlier per-process transient journals that cannot be adopted.
+
+    Before this release a transient workspace drew a random id per process, so
+    every process wrote its own directory. Those directories carry no record of
+    their root, which makes silent adoption unsafe; they are left untouched and
+    their existence is reported instead of being hidden.
+    """
+
+    if not workspace_id.startswith("ws-transient-"):
+        return None
+    try:
+        siblings = [
+            entry
+            for entry in state_dir.parent.iterdir()
+            if entry.is_dir()
+            and entry != state_dir
+            and entry.name.startswith("ws-transient-")
+            and (entry / STATE_DATABASE_NAME).is_file()
+        ]
+    except OSError:  # pragma: no cover - unreadable store
+        return None
+    if not siblings:
+        return None
+    noun = "directory" if len(siblings) == 1 else "directories"
+    return (
+        f"{len(siblings)} earlier per-process state {noun} remain in the global store; "
+        "their history is not attributed to this workspace"
+    )
 
 
 def handle_for(workspace: Workspace, config: Config, home: Path) -> WorkspaceHandle:
+    location = resolve_state_location(workspace, config, home)
+    warning = location.warning
+    legacy = _unattributed_history_note(workspace.id, location.directory)
+    if legacy is not None:
+        warning = legacy if warning is None else f"{warning}; {legacy}"
     return WorkspaceHandle(
         name=workspace.name,
         root=Path(workspace.root_path),
         workspace_id=workspace.id,
         config=config,
-        state_dir=workspace_state_dir(workspace, config, home),
+        state_dir=location.directory,
+        state_warning=warning,
     )
 
 
+def ensure_state_directory(state_dir: Path, *, root: 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.
+    """
+
+    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)},
+        ) 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.close()
+    return database_path
+
+
 def _inside_git_repository(root: Path) -> bool:
     return any((candidate / ".git").exists() for candidate in (root, *root.parents))
 
@@ -104,7 +222,14 @@ class WorkspaceRegistry:
         self.database_path = self.home / "metadata.sqlite3"
 
     def _connect(self) -> sqlite3.Connection:
-        self.home.mkdir(parents=True, exist_ok=True)
+        try:
+            self.home.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise StorageError(
+                f"cannot create the Filekeeper home directory: "
+                f"{exc.strerror or type(exc).__name__}",
+                details={"state_dir": str(self.home)},
+            ) from exc
         try:
             self.home.chmod(stat.S_IRWXU)
         except OSError:  # pragma: no cover - restricted filesystems
@@ -270,24 +395,12 @@ class WorkspaceRegistry:
         """Create the state directory and its migrated database; return the DB path.
 
         Called before the first mutation that will need durable state. It also
-        makes sure a git repository will not track the directory.
+        makes sure a git repository will not track a project-local directory.
         """
 
-        state_dir = self.state_dir_for(workspace)
-        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: "
-                f"{exc.strerror or type(exc).__name__}",
-                details={"state_dir": str(state_dir)},
-            ) from exc
-        ensure_gitignore_entry(Path(workspace.root_path))
-        database_path = state_dir / STATE_DATABASE_NAME
-        connection = database.open_workspace_database(database_path)
-        connection.close()
-        return database_path
+        return ensure_state_directory(
+            self.state_dir_for(workspace), root=Path(workspace.root_path)
+        )
 
 
 def _row_to_workspace(row: sqlite3.Row) -> Workspace: