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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filekeeper-cli
-Version: 0.1.4
+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
@@ -244,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
 
 ```
@@ -304,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.
@@ -318,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
@@ -380,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.
@@ -421,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
@@ -435,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.4 → filekeeper_cli-0.1.6}/README.md

@@ -223,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
 
 ```
@@ -283,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.
@@ -297,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
@@ -359,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.
@@ -400,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
@@ -414,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.4 → filekeeper_cli-0.1.6}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.4"
+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.4 → 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.4"
+__version__ = "0.1.6"
 
 __all__ = [
+    "CallerSurface",
     "Config",
     "ErrorCode",
     "Filekeeper",
     "FilekeeperError",
     "FilekeeperService",
     "MutationResult",
+    "OverrideHint",
     "Workspace",
     "__version__",
 ]

{filekeeper_cli-0.1.4 → 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.4 → 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.4 → 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.4 → 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",

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.6}/src/filekeeper/core/history/undo.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ..errors import (
+    FilekeeperError,
     HistoryUnavailableError,
     StorageError,
     UndoConflictError,
@@ -27,7 +28,14 @@ from ..errors import (
 from ..models import MutationResult, OperationItemRecord, OperationItemResult, OperationRecord
 from ..safety.atomic import atomic_write_bytes, fsync_directory
 from ..safety.hashing import hash_file
-from .journal import COMMITTED, FAILED, UNDONE, OperationJournal, PendingItem
+from .journal import (
+    COMMITTED,
+    FAILED,
+    UNDO_REFUSED,
+    UNDONE,
+    OperationJournal,
+    PendingItem,
+)
 
 
 @dataclass(frozen=True, slots=True)
@@ -104,6 +112,13 @@ def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
             conflicts.append(item.relative_path)
             continue
         if matches_before:
+            # A committed operation left every item in its post-operation state.
+            # Matching only the pre-operation state now means the path was
+            # changed or removed by someone else, not that this undo already
+            # ran. Only a failed operation can legitimately be part-way back.
+            if record.status == COMMITTED and not matches_after:
+                conflicts.append(item.relative_path)
+                continue
             already_before += 1
             continue
 
@@ -140,11 +155,13 @@ def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
             conflicts.append(step.item.relative_path)
 
     if conflicts:
+        named = ", ".join(sorted(conflicts))
         raise UndoConflictError(
-            "cannot undo: these paths changed after the operation, so nothing was modified",
+            f"cannot undo: these paths changed after the operation ({named}), "
+            "so nothing was modified",
             details={
                 "operation_id": record.operation_id,
-                "conflicting_paths": ", ".join(sorted(conflicts)),
+                "conflicting_paths": named,
             },
         )
     if record.status == FAILED and already_before == len(record.items):
@@ -161,6 +178,16 @@ def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
             "operation is not committed and cannot be undone",
             details={"operation_id": record.operation_id, "status": record.status},
         )
+    if not steps:
+        # Every item already holds its pre-operation state, which for a committed
+        # operation means the write left the content unchanged. There is nothing
+        # to restore, and reporting success would claim a change that never
+        # happened.
+        raise UndoConflictError(
+            "cannot undo: the operation left its target in the pre-operation state, "
+            "so undoing it would change nothing",
+            details={"operation_id": record.operation_id},
+        )
     return steps
 
 
@@ -272,6 +299,53 @@ def _result(
     )
 
 
+def _conflicting_paths(error: UndoConflictError) -> list[str]:
+    """The refusal's paths as a list, still caller-relative as Core recorded them."""
+
+    named = error.details.get("conflicting_paths")
+    if not isinstance(named, str):
+        return []
+    return sorted({part.strip() for part in named.split(",") if part.strip()})
+
+
+def _record_refusal(
+    journal: OperationJournal,
+    record: OperationRecord,
+    error: UndoConflictError,
+    *,
+    actor: str | None,
+    task_id: str | None,
+) -> str | None:
+    """Record a refused undo attempt so the ledger shows it was tried.
+
+    A refusal changes nothing, so the row carries no items and no before/after
+    hashes. Its status is ``failed`` — the attempt did not take effect — and its
+    type keeps it out of the undo stack (:func:`latest_undoable`). The conflict
+    code and the paths that blocked the undo travel in metadata. Recording is
+    best-effort: a storage failure here must never replace the refusal the
+    caller is owed.
+    """
+
+    try:
+        begun = journal.begin(
+            operation_type=UNDO_REFUSED,
+            target_path=record.target_path,
+            summary=f"Refused to undo operation {record.operation_id}: {error.message}",
+            items=[],
+            actor=actor,
+            task_id=task_id,
+            metadata={
+                "undone_operation": record.operation_id,
+                "conflict_code": str(error.code),
+                "conflicting_paths": _conflicting_paths(error),
+            },
+        )
+        journal.abort(begun.operation_id)
+    except FilekeeperError:
+        return None
+    return begun.operation_id
+
+
 def undo_operation(
     journal: OperationJournal,
     operation_id: str,
@@ -289,7 +363,11 @@ def undo_operation(
         raise OperationNotFoundError(
             "no operation with that id in this workspace", details={"operation_id": operation_id}
         )
-    steps = _plan(journal, record)
+    try:
+        steps = _plan(journal, record)
+    except UndoConflictError as exc:
+        _record_refusal(journal, record, exc, actor=actor, task_id=task_id)
+        raise
     undo_items = _undo_items(record)
 
     begun = journal.begin(
@@ -316,8 +394,14 @@ def undo_operation(
 
 
 def latest_undoable(journal: OperationJournal, *, actor: str | None = None) -> OperationRecord:
-    clauses = ["status IN (?, ?)"]
-    parameters: list[object] = [COMMITTED, FAILED]
+    """The most recent operation this workspace may undo.
+
+    A recorded refusal changed nothing; it is not a mutation and is never
+    offered as the next undo target, so ``undo-last`` skips those rows.
+    """
+
+    clauses = ["status IN (?, ?)", "operation_type != ?"]
+    parameters: list[object] = [COMMITTED, FAILED, UNDO_REFUSED]
     if actor is not None:
         clauses.append("actor = ?")
         parameters.append(actor)

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.6}/src/filekeeper/core/models.py

@@ -9,7 +9,7 @@ Hashes are SHA-256 and are formatted as ``sha256:<64 hex characters>``.
 
 from __future__ import annotations
 
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from typing import Any, Literal
 
 EntryKind = Literal["file", "directory", "symlink", "other"]
@@ -153,6 +153,10 @@ class OperationItemResult:
 
     ``operation_item_id`` is reserved for the history layer; it is ``None`` in
     releases that do not record history.
+
+    ``after_hash`` and ``size_bytes`` describe observed state: on a dry run they
+    are ``None`` because nothing was written. A dry run puts the predicted digest
+    in ``predicted_after_hash`` instead.
     """
 
     path: str
@@ -160,6 +164,7 @@ class OperationItemResult:
     before_hash: str | None = None
     after_hash: str | None = None
     size_bytes: int | None = None
+    predicted_after_hash: str | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -236,7 +241,11 @@ class PatchHunkResult:
 
 @dataclass(frozen=True, slots=True)
 class PatchFileResult:
-    """One path affected by :func:`apply_patch`, with its per-hunk outcomes."""
+    """One path affected by :func:`apply_patch`, with its per-hunk outcomes.
+
+    ``applied`` is ``False`` for a dry run, and ``after_hash`` is then ``None``;
+    the predicted digest is carried by ``predicted_after_hash``.
+    """
 
     path: str
     change: Literal["created", "modified", "deleted", "unchanged"]
@@ -244,6 +253,7 @@ class PatchFileResult:
     before_hash: str | None
     after_hash: str | None
     hunks: tuple[PatchHunkResult, ...] = ()
+    predicted_after_hash: str | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -260,6 +270,12 @@ class MutationResult:
     ``preview_diff`` carries a dry-run unified diff. ``patch_files`` describes a
     patch application; a recovered failure reports what was rolled back in the
     error details.
+
+    A dry run reports what was *observed* and what *would* happen, never what
+    happened: ``changed`` is ``False``, ``after_hash`` is ``None``, and no
+    operation is recorded. ``would_change`` says whether a real run would alter
+    anything, and ``predicted_after_hash`` carries the digest the content would
+    have -- a prediction, never an observation.
     """
 
     workspace: str
@@ -271,6 +287,8 @@ class MutationResult:
     operation_id: str | None = None
     undo_available: bool = False
     dry_run: bool = False
+    would_change: bool | None = None
+    predicted_after_hash: str | None = None
     warnings: tuple[str, ...] = ()
     items: tuple[OperationItemResult, ...] = ()
     affected_count: int | None = None
@@ -285,9 +303,65 @@ class MutationResult:
         return payload
 
 
+def as_dry_run(
+    result: MutationResult,
+    *,
+    would_change: bool,
+    predicted_after_hash: str | None = None,
+) -> MutationResult:
+    """Return the honest shape of a dry run for ``result``.
+
+    This is the single place the dry-run contract is applied: nothing was
+    written, so the result reports ``changed=False``, no observed ``after_hash``
+    or item size, no operation id and nothing undoable. The prediction a caller
+    may legitimately want survives as ``predicted_after_hash`` on the result,
+    each item and each patch file.
+    """
+
+    return replace(
+        result,
+        changed=False,
+        after_hash=None,
+        operation_id=None,
+        undo_available=False,
+        would_change=would_change,
+        predicted_after_hash=predicted_after_hash,
+        items=tuple(
+            replace(
+                item,
+                after_hash=None,
+                size_bytes=None,
+                predicted_after_hash=(
+                    item.predicted_after_hash
+                    if item.predicted_after_hash is not None
+                    else item.after_hash
+                ),
+            )
+            for item in result.items
+        ),
+        patch_files=tuple(
+            replace(
+                patch_file,
+                applied=False,
+                after_hash=None,
+                predicted_after_hash=(
+                    patch_file.predicted_after_hash
+                    if patch_file.predicted_after_hash is not None
+                    else patch_file.after_hash
+                ),
+            )
+            for patch_file in result.patch_files
+        ),
+    )
+
+
 def _jsonable(value: Any) -> Any:
     if isinstance(value, dict):
-        return {key: _jsonable(item) for key, item in value.items()}
+        return {
+            key: _jsonable(item)
+            for key, item in value.items()
+            if not (item is None and key in {"would_change", "predicted_after_hash"})
+        }
     if isinstance(value, (list, tuple)):
         return [_jsonable(item) for item in value]
     return value

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.6}/src/filekeeper/core/operations/directory.py

@@ -15,22 +15,42 @@ from pathlib import Path
 
 from ..errors import (
     AlreadyExistsError,
+    CallerSurface,
     FilekeeperError,
     PathNotFoundError,
     StorageError,
     ValidationError,
+    override_hint,
     storage_failure,
 )
 from ..errors import (
     NotADirectoryError as FilekeeperNotADirectoryError,
 )
 from ..history.journal import OperationJournal, PendingItem
-from ..models import MutationResult, OperationItemResult
+from ..models import MutationResult, OperationItemResult, as_dry_run
 from ..paths import ensure_parent_directory, resolve_path
 from ..safety.atomic import fsync_directory
 from ..safety.hashing import hash_file
 from ..workspace import WorkspaceHandle
 
+DIRECTORY_PARENTS_HINT = override_hint(
+    core="pass parents=True to create ancestors",
+    cli="pass --parents to create ancestors",
+    mcp="pass parents=true to create ancestors",
+)
+
+DIRECTORY_DELETE_HINT = override_hint(
+    core="pass recursive=True and confirm_recursive=True to delete its contents",
+    cli="pass --recursive --confirm-recursive to delete its contents",
+    mcp="pass recursive=true and confirm_recursive=true to delete its contents",
+)
+
+DIRECTORY_CONFIRM_HINT = override_hint(
+    core="pass confirm_recursive=True to acknowledge the tree deletion",
+    cli="pass --confirm-recursive to acknowledge the tree deletion",
+    mcp="pass confirm_recursive=true to acknowledge the tree deletion",
+)
+
 
 def _mode(path: Path) -> int | None:
     try:
@@ -97,8 +117,10 @@ def create_directory(
     target = resolved.absolute
     if not parents and not target.parent.is_dir():
         raise ValidationError(
-            "parent directory does not exist; pass parents=True to create ancestors",
+            "parent directory does not exist; "
+            f"{DIRECTORY_PARENTS_HINT.sentence(CallerSurface.CORE)}",
             details={"path": resolved.relative},
+            override_hint=DIRECTORY_PARENTS_HINT,
         )
 
     created: list[Path] = [target]
@@ -151,7 +173,7 @@ def create_directory(
         if journal is not None and operation_id is not None:
             journal.commit(operation_id)
 
-    return MutationResult(
+    result = MutationResult(
         workspace=handle.name,
         path=resolved.relative,
         changed=True,
@@ -164,6 +186,9 @@ def create_directory(
         items=(OperationItemResult(path=resolved.relative, change="created"),),
         affected_count=1,
     )
+    if dry_run:
+        return as_dry_run(result, would_change=True)
+    return result
 
 
 def _umask() -> int:
@@ -310,7 +335,7 @@ def move_directory(
             },
         ) from exc
 
-    return MutationResult(
+    result = MutationResult(
         workspace=handle.name,
         path=destination_resolved.relative,
         changed=True,
@@ -330,6 +355,9 @@ def move_directory(
         affected_count=1,
         history_skipped=tuple(sorted(set(skipped))),
     )
+    if dry_run:
+        return as_dry_run(result, would_change=True)
+    return result
 
 
 def _count_entries(root: Path) -> int:
@@ -370,15 +398,17 @@ def delete_directory(
     entries = _count_entries(target)
     if entries > 0 and not recursive:
         raise ValidationError(
-            "directory is not empty; pass --recursive --confirm-recursive "
-            "to delete its contents",
+            "directory is not empty; "
+            f"{DIRECTORY_DELETE_HINT.sentence(CallerSurface.CORE)}",
             details={"path": resolved.relative, "entries": entries},
+            override_hint=DIRECTORY_DELETE_HINT,
         )
     if entries > 0 and not confirm_recursive:
         raise ValidationError(
-            "recursive deletion requires explicit confirmation "
-            "(--recursive --confirm-recursive)",
+            "recursive deletion requires explicit confirmation: "
+            f"{DIRECTORY_CONFIRM_HINT.sentence(CallerSurface.CORE)}",
             details={"path": resolved.relative, "entries": entries},
+            override_hint=DIRECTORY_CONFIRM_HINT,
         )
 
     operation_id: str | None = None
@@ -448,7 +478,7 @@ def delete_directory(
         if journal is not None and operation_id is not None:
             journal.commit(operation_id)
 
-    return MutationResult(
+    result = MutationResult(
         workspace=handle.name,
         path=resolved.relative,
         changed=True,
@@ -473,3 +503,6 @@ def delete_directory(
         else warnings,
         history_skipped=skipped,
     )
+    if dry_run:
+        return as_dry_run(result, would_change=True)
+    return result

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.6}/src/filekeeper/core/operations/edit.py

@@ -49,6 +49,7 @@ from ..models import (
     OperationItemResult,
     PatchFileResult,
     PatchHunkResult,
+    as_dry_run,
 )
 from ..paths import ResolvedPath, ensure_parent_directory, resolve_path
 from ..safety.atomic import atomic_write_bytes, fsync_directory
@@ -682,10 +683,12 @@ class _Plan:
     hunks: tuple[PatchHunkResult, ...]
 
 
-def _syntax(message: str, line: int) -> PatchFailedError:
-    return PatchFailedError(
-        f"invalid patch: {message}", details={"line": line, "reason": "syntax"}
-    )
+def _syntax(message: str, line: int, **counts: int) -> PatchFailedError:
+    """A syntax refusal; ``counts`` carries the hunk's expected/actual line counts."""
+
+    details: dict[str, Any] = {"line": line, "reason": "syntax"}
+    details.update(counts)
+    return PatchFailedError(f"invalid patch: {message}", details=details)
 
 
 def _parse_patch(patch_text: str) -> tuple[_FilePatch, ...]:
@@ -743,13 +746,34 @@ def _parse_patch(patch_text: str) -> tuple[_FilePatch, ...]:
                             body.append(_BodyLine("+", body_line[1:]))
                             remaining_new -= 1
                         else:
+                            found_old = old_count - remaining_old
+                            found_new = new_count - remaining_new
                             raise _syntax(
-                                "hunk is truncated or has an unknown line prefix",
+                                "hunk is truncated or has an unknown line prefix "
+                                f"(header declares {old_count} old and {new_count} new "
+                                f"lines; the body supplies {found_old} old and "
+                                f"{found_new} new)",
                                 index + 1,
+                                expected_old_lines=old_count,
+                                expected_new_lines=new_count,
+                                actual_old_lines=found_old,
+                                actual_new_lines=found_new,
                             )
                         index += 1
                     if remaining_old != 0 or remaining_new != 0:
-                        raise _syntax("hunk line counts do not match its header", index + 1)
+                        found_old = old_count - remaining_old
+                        found_new = new_count - remaining_new
+                        raise _syntax(
+                            "hunk line counts do not match its header "
+                            f"(header declares {old_count} old and {new_count} new "
+                            f"lines; the patch supplies {found_old} old and "
+                            f"{found_new} new)",
+                            index + 1,
+                            expected_old_lines=old_count,
+                            expected_new_lines=new_count,
+                            actual_old_lines=found_old,
+                            actual_new_lines=found_new,
+                        )
                     if index < len(lines) and lines[index].startswith("\\"):
                         if not body:
                             raise _syntax("newline marker has no preceding line", index + 1)
@@ -1120,19 +1144,23 @@ def apply_patch(
     )
 
     if dry_run:
-        return MutationResult(
-            workspace=handle.name,
-            path=primary.relative,
-            changed=True,
-            before_hash=primary.before_hash,
-            after_hash=primary.after_hash,
-            summary=f"Would apply a patch touching {file_count} file(s).",
-            dry_run=True,
-            warnings=tuple(warnings),
-            items=item_results,
-            affected_count=file_count,
-            preview_diff=patch_text,
-            patch_files=file_results,
+        return as_dry_run(
+            MutationResult(
+                workspace=handle.name,
+                path=primary.relative,
+                changed=True,
+                before_hash=primary.before_hash,
+                after_hash=primary.after_hash,
+                summary=f"Would apply a patch touching {file_count} file(s).",
+                dry_run=True,
+                warnings=tuple(warnings),
+                items=item_results,
+                affected_count=file_count,
+                preview_diff=patch_text,
+                patch_files=file_results,
+            ),
+            would_change=True,
+            predicted_after_hash=primary.after_hash,
         )
 
     pending = [

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.6}/src/filekeeper/core/operations/write.py

@@ -21,9 +21,11 @@ import codecs
 import os
 import stat
 from pathlib import Path
+from typing import Any
 
 from ..errors import (
     AlreadyExistsError,
+    CallerSurface,
     ContentConflictError,
     FilekeeperError,
     LimitExceededError,
@@ -32,10 +34,11 @@ from ..errors import (
     StorageError,
     SymlinkWriteRefusedError,
     ValidationError,
+    override_hint,
     storage_failure,
 )
 from ..history.journal import OperationJournal, PendingItem
-from ..models import MutationResult, OperationItemResult
+from ..models import MutationResult, OperationItemResult, as_dry_run
 from ..paths import ResolvedPath, ensure_parent_directory, resolve_path
 from ..safety.atomic import atomic_write_bytes, fsync_directory
 from ..safety.hashing import format_digest, hash_bytes, hash_file, hashes_match, normalize_hash
@@ -44,9 +47,31 @@ from ..safety.textdata import decode_bytes, encode_text, looks_binary
 from ..safety.vcs import ignore_warning
 from ..workspace import WorkspaceHandle
 
-SECRET_FLAG_HINT = (
-    "pass allow_sensitive_write=True in Core, or the CLI flag "
-    "--i-accept-secret-write-risk, if you really mean to write credential material"
+SENSITIVE_WRITE_HINT = override_hint(
+    core="pass allow_sensitive_write=True in Core",
+    cli="pass the CLI flag --i-accept-secret-write-risk",
+    mcp="pass the MCP argument i_accept_secret_write_risk=true",
+)
+
+# Kept for importers of the earlier name.
+SECRET_FLAG_HINT = SENSITIVE_WRITE_HINT
+
+CREATE_OVERWRITE_HINT = override_hint(
+    core="pass expected_absent=False to overwrite",
+    cli="pass --allow-existing to overwrite",
+    mcp="pass expected_absent=false to overwrite",
+)
+
+COPY_OVERWRITE_HINT = override_hint(
+    core="pass expected_destination_hash to replace it deliberately",
+    cli="pass --expected-destination-hash to replace it deliberately",
+    mcp="pass expected_destination_hash to replace it deliberately",
+)
+
+MOVE_OVERWRITE_HINT = override_hint(
+    core="pass overwrite=True to replace it",
+    cli="pass --overwrite to replace it",
+    mcp="pass overwrite=true to replace it",
 )
 
 
@@ -95,8 +120,10 @@ def _guard_sensitive(
     if reason is not None and not allow_sensitive_write:
         raise SensitivePathRefusedError(
             f"refusing to write {resolved.relative}: it looks like credential or key "
-            f"material ({reason}); {SECRET_FLAG_HINT}",
+            f"material ({reason}); {SENSITIVE_WRITE_HINT.sentence(CallerSurface.CORE)}, "
+            "if you really mean to write credential material",
             details={"path": resolved.relative, "reason": reason},
+            override_hint=SENSITIVE_WRITE_HINT,
         )
     warnings: list[str] = []
     warning = ignore_warning(handle.root, resolved.absolute, resolved.relative)
@@ -148,7 +175,17 @@ def _after_write(
     journal: OperationJournal | None,
     actor: str | None,
     task_id: str | None,
+    metadata: dict[str, Any] | None = None,
+    journal_summary: str | None = None,
 ) -> MutationResult:
+    """Write *data*, journaling the change when a journal is supplied.
+
+    ``journal_summary`` overrides the summary recorded in the journal without
+    changing the summary returned to the caller; ``metadata`` is merged into the
+    operation's metadata. Callers that touch more than one path use both to name
+    the other path in the durable record without reinterpreting ``target_path``.
+    """
+
     after_hash = hash_bytes(data)
     operation_id: str | None = None
     skipped: tuple[str, ...] = ()
@@ -171,12 +208,13 @@ def _after_write(
             begun = journal.begin(
                 operation_type=operation_type,
                 target_path=resolved.relative,
-                summary=f"{past_verb} {resolved.relative}.",
+                summary=journal_summary or f"{past_verb} {resolved.relative}.",
                 items=[pending],
                 actor=actor,
                 task_id=task_id,
                 before_hash=before_hash,
                 after_hash=after_hash,
+                metadata=metadata,
             )
             operation_id = begun.operation_id
             skipped = begun.skipped
@@ -197,7 +235,7 @@ def _after_write(
             journal.commit(operation_id)
             undo_available = not skipped
 
-    return MutationResult(
+    result = MutationResult(
         workspace=handle.name,
         path=resolved.relative,
         changed=True,
@@ -222,6 +260,13 @@ def _after_write(
         affected_count=1,
         history_skipped=skipped,
     )
+    if dry_run:
+        return as_dry_run(
+            result,
+            would_change=not before_exists or before_hash != after_hash,
+            predicted_after_hash=after_hash,
+        )
+    return result
 
 
 def create_file(
@@ -244,8 +289,10 @@ def create_file(
         raise NotAFileError("path is a directory", details={"path": resolved.relative})
     if resolved.exists and expected_absent:
         raise AlreadyExistsError(
-            "file already exists; pass expected_absent=False to overwrite",
+            "file already exists; "
+            f"{CREATE_OVERWRITE_HINT.sentence(CallerSurface.CORE)}",
             details={"path": resolved.relative},
+            override_hint=CREATE_OVERWRITE_HINT,
         )
     warnings = _guard_sensitive(handle, resolved, allow_sensitive_write=allow_sensitive_write)
     ensure_parent_directory(resolved)
@@ -401,9 +448,10 @@ def copy_file(
         )
         if expected_destination_hash is None:
             raise AlreadyExistsError(
-                "destination already exists; pass expected_destination_hash to "
-                "replace it deliberately",
+                "destination already exists; "
+                f"{COPY_OVERWRITE_HINT.sentence(CallerSurface.CORE)}",
                 details={"path": destination_resolved.relative},
+                override_hint=COPY_OVERWRITE_HINT,
             )
         wanted = normalize_hash(expected_destination_hash)
         if not hashes_match(wanted, destination_before or ""):
@@ -446,6 +494,10 @@ def copy_file(
         journal=journal,
         actor=actor,
         task_id=task_id,
+        metadata={"source_path": source_resolved.relative},
+        journal_summary=(
+            f"Copied {source_resolved.relative} to {destination_resolved.relative}."
+        ),
     )
     item = OperationItemResult(
         path=source_resolved.relative,
@@ -454,7 +506,8 @@ def copy_file(
         after_hash=hash_bytes(data),
         size_bytes=len(data),
     )
-    return MutationResult(
+    predicted_after_hash = result.predicted_after_hash
+    result = MutationResult(
         workspace=result.workspace,
         path=result.path,
         changed=True,
@@ -472,6 +525,13 @@ def copy_file(
         affected_count=1,
         history_skipped=result.history_skipped,
     )
+    if dry_run:
+        return as_dry_run(
+            result,
+            would_change=True,
+            predicted_after_hash=predicted_after_hash,
+        )
+    return result
 
 
 def move_file(
@@ -524,8 +584,10 @@ def move_file(
         )
     if destination_resolved.exists and not overwrite:
         raise AlreadyExistsError(
-            "destination already exists; pass overwrite=True to replace it",
+            "destination already exists; "
+            f"{MOVE_OVERWRITE_HINT.sentence(CallerSurface.CORE)}",
             details={"path": destination_resolved.relative},
+            override_hint=MOVE_OVERWRITE_HINT,
         )
     warnings = _guard_sensitive(
         handle,
@@ -578,6 +640,7 @@ def move_file(
                 task_id=task_id,
                 before_hash=destination_before,
                 after_hash=source_hash,
+                metadata={"source_path": source_resolved.relative},
             )
             operation_id = begun.operation_id
             skipped = begun.skipped
@@ -612,7 +675,7 @@ def move_file(
     else:
         after_hash = source_hash
 
-    return MutationResult(
+    result = MutationResult(
         workspace=handle.name,
         path=destination_resolved.relative,
         changed=True,
@@ -643,6 +706,13 @@ def move_file(
         affected_count=1,
         history_skipped=skipped,
     )
+    if dry_run:
+        return as_dry_run(
+            result,
+            would_change=True,
+            predicted_after_hash=after_hash,
+        )
+    return result
 
 
 def delete_file(
@@ -725,7 +795,7 @@ def delete_file(
         if journal is not None and operation_id is not None:
             journal.commit(operation_id)
 
-    return MutationResult(
+    result = MutationResult(
         workspace=handle.name,
         path=resolved.relative,
         changed=True,
@@ -746,6 +816,9 @@ def delete_file(
         affected_count=1,
         history_skipped=skipped,
     )
+    if dry_run:
+        return as_dry_run(result, would_change=True, predicted_after_hash=None)
+    return result
 
 
 # Re-exported for adapters that need to format a hash without importing safety.

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

@@ -26,7 +26,12 @@ from .config import (
     load_config,
     resolve_home,
 )
-from .errors import NoWorkspaceSelectedError, ValidationError
+from .errors import (
+    CallerSurface,
+    NoWorkspaceSelectedError,
+    ValidationError,
+    override_hint,
+)
 from .history.blobs import BlobStore
 from .history.journal import OperationJournal
 from .history.repository import diff_operation as read_diff
@@ -58,6 +63,12 @@ from .workspace import (
 TRANSIENT_ID_PREFIX = "ws-transient-"
 TRANSIENT_ID_LENGTH = 16
 
+WORKSPACE_SELECTION_HINT = override_hint(
+    core="select a workspace explicitly or register a default",
+    cli="pass --workspace or --root, or register a default with 'keeper workspace use'",
+    mcp="start the server with --root PATH or register a default workspace",
+)
+
 
 def transient_workspace_id(root: str | Path) -> str:
     """A stable id for the transient workspace rooted at ``root``.
@@ -173,10 +184,11 @@ class Filekeeper:
                 return FilekeeperService(handle_for(workspaces[0], self.config, self.home), self)
             available = ", ".join(workspace.name for workspace in workspaces)
             raise NoWorkspaceSelectedError(
-                "no workspace selected: pass --workspace or --root, or register a "
-                "default with 'keeper workspace use'"
+                "no workspace selected: "
+                f"{WORKSPACE_SELECTION_HINT.sentence(CallerSurface.CORE)}"
                 + (f"; known workspaces: {available}" if available else ""),
                 details={"known_workspaces": available},
+                override_hint=WORKSPACE_SELECTION_HINT,
             )
         return FilekeeperService(handle_for(default, self.config, self.home), self)