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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filekeeper-cli
-Version: 0.1.3
+Version: 0.1.6
 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.
@@ -238,6 +244,13 @@ later file fails after earlier ones were written, the written files are rolled
 back to their pre-patch bytes and the failure names what was restored. A crash is
 resolved from the pending journal record, never from an all-or-nothing commit.
 
+When a hunk's header and its body disagree — the hunk is cut short or a line
+prefix is not ` `, `+` or `-` — the `PATCH_FAILED` error states the counts the
+header declares and the counts the body actually supplied, in the message and in
+`details.expected_old_lines`, `expected_new_lines`, `actual_old_lines` and
+`actual_new_lines`. The existing `line` and `reason` fields are still there. Patch
+text is never echoed into the error.
+
 ## Commands
 
 ```
@@ -298,10 +311,11 @@ affected path with the state the operation recorded:
 
 - if the path still matches the recorded **after** state, undo restores the
   recorded **before** bytes;
-- if it already matches the **before** state (a partially applied multi-file
-  operation), undo leaves it alone;
-- if it matches neither, someone changed it afterwards: the undo is refused with
-  `UNDO_CONFLICT` (exit code 12) and **nothing is modified**.
+- if it already matches the **before** state of an operation that never committed
+  (a partially applied multi-file operation), undo leaves it alone;
+- if a committed operation's path no longer matches the **after** state — edited,
+  deleted, or renamed away — the undo is refused with `UNDO_CONFLICT` (exit code
+  12) and **nothing is modified**.
 
 Undoing a create removes the file only while it still matches what was created.
 Undoing a delete restores the file only while the destination is still absent.
@@ -312,6 +326,15 @@ The undo is itself recorded as an operation, so `history list` remains a
 truthful ledger. **Redo is deferred** — it is not half-implemented; undoing an
 undo is the supported way to go forward again.
 
+A copy or a move records the path it read from in the operation's `metadata`
+under `source_path`, and its summary names both ends. `target_path` keeps its
+meaning — the path the operation targets — so existing readers are unaffected.
+
+A refused undo is recorded too: the ledger gains an `undo_refused` row with the
+target path, the conflict code, and the paths that blocked the undo. It changed
+nothing, so it carries no items, is never offered as undoable, and `undo-last`
+skips it. Every recorded path is workspace-relative, never a resolved host path.
+
 `keeper file read` writes file content to standard output unchanged (line endings
 included). Metadata goes to stderr, or into the JSON object with `--json`.
 `--input FILE` reads replacement content from a file, avoiding shell argument
@@ -374,6 +397,16 @@ re-reads the file and writes against its new hash.
 so its previous bytes were deliberately not stored; `history_skipped` then names
 the paths.
 
+**A dry run reports a preview, not a write.** With `"dry_run": true`, `changed` is
+`false`, `operation_id` and `after_hash` are `null`, and each item's `after_hash`
+and `size_bytes` are `null`: nothing was observed, so nothing is claimed. The hash
+a real run would produce appears as `predicted_after_hash` — a prediction, never an
+observation — and `would_change` says whether a real run would alter anything.
+`before_hash` and `preview_diff` are kept, because they describe the state the
+preview was computed against. The same shape applies to every mutating command and
+to the MCP tools that mirror them. A committed operation still reports
+`"changed": true` with its observed `after_hash`.
+
 Editing results add `match_stage` and `match_count` (text replacement),
 `preview_diff` (dry run), and, for patches, `patch_files` with per-hunk status.
 A failure that was rolled back reports the restored paths in the error details.
@@ -415,6 +448,13 @@ a shell predicate.
 
 Codes are stable; messages are not a contract.
 
+Messages name the interface the caller is using. A refusal that offers an
+override states that interface's own argument: Core's keyword, the CLI's flag, or
+the MCP tool argument. The same request therefore reads correctly whether it came
+from a library, a shell, or an agent over MCP, and an adapter never prints another
+surface's argument. Codes, `retryable` and `details` are identical across all
+three surfaces.
+
 ## Safety rules
 
 - **Confinement.** Relative paths resolve inside the workspace root. Absolute paths
@@ -429,8 +469,10 @@ Codes are stable; messages are not a contract.
   `*.key`, `id_rsa` and its siblings, `*.p12`, `*.pfx`, `authorized_keys`,
   `.netrc`, and anything under `.ssh/`, `.gnupg/` or `.aws/` fail with
   `SENSITIVE_PATH_REFUSED` (exit code 10). Override deliberately with
-  `--i-accept-secret-write-risk` (Core: `allow_sensitive_write=True`). The flag is
-  long because the mistake is expensive.
+  `--i-accept-secret-write-risk` on the CLI, `allow_sensitive_write=True` in Core,
+  or `i_accept_secret_write_risk` on the MCP tool. Each name is long because the
+  mistake is expensive. The error message names only the argument belonging to the
+  interface that received the request.
 - **Version-control-ignored targets warn.** Writing a path that git ignores still
   succeeds, but the result carries a warning that the change will not be committed.
 - **No shell.** Filekeeper never interpolates paths into a shell command.

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.6}/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.
@@ -217,6 +223,13 @@ later file fails after earlier ones were written, the written files are rolled
 back to their pre-patch bytes and the failure names what was restored. A crash is
 resolved from the pending journal record, never from an all-or-nothing commit.
 
+When a hunk's header and its body disagree — the hunk is cut short or a line
+prefix is not ` `, `+` or `-` — the `PATCH_FAILED` error states the counts the
+header declares and the counts the body actually supplied, in the message and in
+`details.expected_old_lines`, `expected_new_lines`, `actual_old_lines` and
+`actual_new_lines`. The existing `line` and `reason` fields are still there. Patch
+text is never echoed into the error.
+
 ## Commands
 
 ```
@@ -277,10 +290,11 @@ affected path with the state the operation recorded:
 
 - if the path still matches the recorded **after** state, undo restores the
   recorded **before** bytes;
-- if it already matches the **before** state (a partially applied multi-file
-  operation), undo leaves it alone;
-- if it matches neither, someone changed it afterwards: the undo is refused with
-  `UNDO_CONFLICT` (exit code 12) and **nothing is modified**.
+- if it already matches the **before** state of an operation that never committed
+  (a partially applied multi-file operation), undo leaves it alone;
+- if a committed operation's path no longer matches the **after** state — edited,
+  deleted, or renamed away — the undo is refused with `UNDO_CONFLICT` (exit code
+  12) and **nothing is modified**.
 
 Undoing a create removes the file only while it still matches what was created.
 Undoing a delete restores the file only while the destination is still absent.
@@ -291,6 +305,15 @@ The undo is itself recorded as an operation, so `history list` remains a
 truthful ledger. **Redo is deferred** — it is not half-implemented; undoing an
 undo is the supported way to go forward again.
 
+A copy or a move records the path it read from in the operation's `metadata`
+under `source_path`, and its summary names both ends. `target_path` keeps its
+meaning — the path the operation targets — so existing readers are unaffected.
+
+A refused undo is recorded too: the ledger gains an `undo_refused` row with the
+target path, the conflict code, and the paths that blocked the undo. It changed
+nothing, so it carries no items, is never offered as undoable, and `undo-last`
+skips it. Every recorded path is workspace-relative, never a resolved host path.
+
 `keeper file read` writes file content to standard output unchanged (line endings
 included). Metadata goes to stderr, or into the JSON object with `--json`.
 `--input FILE` reads replacement content from a file, avoiding shell argument
@@ -353,6 +376,16 @@ re-reads the file and writes against its new hash.
 so its previous bytes were deliberately not stored; `history_skipped` then names
 the paths.
 
+**A dry run reports a preview, not a write.** With `"dry_run": true`, `changed` is
+`false`, `operation_id` and `after_hash` are `null`, and each item's `after_hash`
+and `size_bytes` are `null`: nothing was observed, so nothing is claimed. The hash
+a real run would produce appears as `predicted_after_hash` — a prediction, never an
+observation — and `would_change` says whether a real run would alter anything.
+`before_hash` and `preview_diff` are kept, because they describe the state the
+preview was computed against. The same shape applies to every mutating command and
+to the MCP tools that mirror them. A committed operation still reports
+`"changed": true` with its observed `after_hash`.
+
 Editing results add `match_stage` and `match_count` (text replacement),
 `preview_diff` (dry run), and, for patches, `patch_files` with per-hunk status.
 A failure that was rolled back reports the restored paths in the error details.
@@ -394,6 +427,13 @@ a shell predicate.
 
 Codes are stable; messages are not a contract.
 
+Messages name the interface the caller is using. A refusal that offers an
+override states that interface's own argument: Core's keyword, the CLI's flag, or
+the MCP tool argument. The same request therefore reads correctly whether it came
+from a library, a shell, or an agent over MCP, and an adapter never prints another
+surface's argument. Codes, `retryable` and `details` are identical across all
+three surfaces.
+
 ## Safety rules
 
 - **Confinement.** Relative paths resolve inside the workspace root. Absolute paths
@@ -408,8 +448,10 @@ Codes are stable; messages are not a contract.
   `*.key`, `id_rsa` and its siblings, `*.p12`, `*.pfx`, `authorized_keys`,
   `.netrc`, and anything under `.ssh/`, `.gnupg/` or `.aws/` fail with
   `SENSITIVE_PATH_REFUSED` (exit code 10). Override deliberately with
-  `--i-accept-secret-write-risk` (Core: `allow_sensitive_write=True`). The flag is
-  long because the mistake is expensive.
+  `--i-accept-secret-write-risk` on the CLI, `allow_sensitive_write=True` in Core,
+  or `i_accept_secret_write_risk` on the MCP tool. Each name is long because the
+  mistake is expensive. The error message names only the argument belonging to the
+  interface that received the request.
 - **Version-control-ignored targets warn.** Writing a path that git ignores still
   succeeds, but the result carries a warning that the change will not be committed.
 - **No shell.** Filekeeper never interpolates paths into a shell command.

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

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

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

@@ -12,24 +12,28 @@ work; see ``CHANGELOG.md`` and ``README.md``.
 from __future__ import annotations
 
 from .core import (
+    CallerSurface,
     Config,
     ErrorCode,
     Filekeeper,
     FilekeeperError,
     FilekeeperService,
     MutationResult,
+    OverrideHint,
     Workspace,
 )
 
-__version__ = "0.1.3"
+__version__ = "0.1.6"
 
 __all__ = [
+    "CallerSurface",
     "Config",
     "ErrorCode",
     "Filekeeper",
     "FilekeeperError",
     "FilekeeperService",
     "MutationResult",
+    "OverrideHint",
     "Workspace",
     "__version__",
 ]

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.6}/src/filekeeper/cli/output.py

@@ -14,7 +14,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any
 
-from ..core.errors import FilekeeperError
+from ..core.errors import CallerSurface, FilekeeperError
 from ..core.models import (
     ContentSearchResult,
     DirectoryListing,
@@ -53,6 +53,9 @@ def print_json(payload: dict[str, Any]) -> None:
 
 
 def print_error(error: FilekeeperError, *, as_json: bool) -> None:
+    """Render an error for this surface: its override hint names this CLI's flag."""
+
+    error = error.for_surface(CallerSurface.CLI)
     if as_json:
         print_json({"ok": False, "error": error.to_dict()})
         return
@@ -210,6 +213,15 @@ def history_show(record: OperationRecord) -> str:
             f"  {item.item_type:<9} {item.relative_path}  exists {exists}  "
             f"before {item.before_blob_hash or '-'}  after {item.after_blob_hash or '-'}"
         )
+    if record.metadata:
+        lines.append("metadata:")
+        for key in sorted(record.metadata):
+            value = record.metadata[key]
+            if isinstance(value, list):
+                rendered = ", ".join(str(entry) for entry in value)
+            else:
+                rendered = str(value)
+            lines.append(f"  {key}: {rendered}")
     if record.history_skipped:
         lines.append("history_skipped: " + ", ".join(record.history_skipped))
     return "\n".join(lines)

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

@@ -5,7 +5,7 @@ the CLI, of the MCP server, or of any filesystem protocol.
 """
 
 from .config import Config
-from .errors import ErrorCode, FilekeeperError
+from .errors import CallerSurface, ErrorCode, FilekeeperError, OverrideHint
 from .history.blobs import BlobStore
 from .models import (
     ContentMatch,
@@ -27,6 +27,7 @@ from .workspace import WorkspaceHandle, WorkspaceRegistry
 
 __all__ = [
     "BlobStore",
+    "CallerSurface",
     "Config",
     "ContentMatch",
     "ContentSearchResult",
@@ -41,6 +42,7 @@ __all__ = [
     "FilekeeperService",
     "MutationResult",
     "OperationItemResult",
+    "OverrideHint",
     "PathInfo",
     "PathSearchResult",
     "ReadManyEntry",

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.6}/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.6}/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.6}/src/filekeeper/core/errors.py

@@ -7,6 +7,9 @@ error payloads, and callers may branch on the code without parsing prose.
 
 from __future__ import annotations
 
+import copy
+from collections.abc import Mapping
+from dataclasses import dataclass
 from enum import StrEnum
 from typing import Any
 
@@ -46,6 +49,38 @@ class ErrorCode(StrEnum):
     INTERNAL_ERROR = "INTERNAL_ERROR"
 
 
+class CallerSurface(StrEnum):
+    """The interface a caller reached Core through.
+
+    A refusal that offers an override must name the argument the caller actually
+    has. Core renders the sentence for ``CORE``; each adapter re-renders the same
+    error for its own surface before returning it, so no message ever names
+    another interface's argument.
+    """
+
+    CORE = "core"
+    CLI = "cli"
+    MCP = "mcp"
+
+
+@dataclass(frozen=True, slots=True)
+class OverrideHint:
+    """One "pass X to override" instruction, worded for each caller surface."""
+
+    sentences: Mapping[CallerSurface, str]
+
+    def sentence(self, surface: CallerSurface) -> str:
+        return self.sentences[surface]
+
+
+def override_hint(*, core: str, cli: str, mcp: str) -> OverrideHint:
+    """Build a hint whose sentence names each surface's own argument."""
+
+    return OverrideHint(
+        {CallerSurface.CORE: core, CallerSurface.CLI: cli, CallerSurface.MCP: mcp}
+    )
+
+
 class FilekeeperError(Exception):
     """Base error carrying a stable code, a human message, and optional details."""
 
@@ -59,6 +94,7 @@ class FilekeeperError(Exception):
         code: ErrorCode | None = None,
         retryable: bool | None = None,
         details: dict[str, Any] | None = None,
+        override_hint: OverrideHint | None = None,
     ) -> None:
         super().__init__(message)
         self.message = message
@@ -67,6 +103,27 @@ class FilekeeperError(Exception):
         if retryable is not None:
             self.retryable = retryable
         self.details: dict[str, Any] = details or {}
+        # Not serialised: the hint only lets an adapter re-word the message.
+        self.override_hint = override_hint
+
+    def for_surface(self, surface: CallerSurface) -> FilekeeperError:
+        """Return this error worded for the interface that received it.
+
+        ``code``, ``retryable`` and ``details`` are carried over untouched; only
+        the message's override sentence changes. An error with no hint, or a
+        request for the surface Core already rendered, is returned as is.
+        """
+
+        hint = self.override_hint
+        if hint is None or surface is CallerSurface.CORE:
+            return self
+        core_sentence = hint.sentence(CallerSurface.CORE)
+        if core_sentence not in self.message:
+            return self
+        adapted = copy.copy(self)
+        adapted.message = self.message.replace(core_sentence, hint.sentence(surface))
+        adapted.args = (adapted.message,)
+        return adapted
 
     def to_dict(self) -> dict[str, Any]:
         payload: dict[str, Any] = {
@@ -135,8 +192,14 @@ class SensitivePathRefusedError(FilekeeperError):
 
     code = ErrorCode.SENSITIVE_PATH_REFUSED
 
-    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
-        super().__init__(message, details=details)
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict[str, Any] | None = None,
+        override_hint: OverrideHint | None = None,
+    ) -> None:
+        super().__init__(message, details=details, override_hint=override_hint)
 
 
 class AlreadyExistsError(FilekeeperError):

{filekeeper_cli-0.1.3 → filekeeper_cli-0.1.6}/src/filekeeper/core/history/journal.py

@@ -38,6 +38,9 @@ COMMITTED = "committed"
 UNDONE = "undone"
 FAILED = "failed"
 PARTIALLY_UNDONE = "partially_undone"
+# A refused undo is recorded so the ledger shows the attempt, but it is not a
+# mutation and is never offered as undoable.
+UNDO_REFUSED = "undo_refused"
 
 
 @dataclass(frozen=True, slots=True)
@@ -424,6 +427,7 @@ __all__ = [
     "PARTIALLY_UNDONE",
     "PENDING",
     "UNDONE",
+    "UNDO_REFUSED",
     "BeginResult",
     "OperationJournal",
     "PendingItem",