your commit message

cmdlet/_shared.py

@@ -965,6 +965,48 @@ def normalize_hash(hash_hex: Optional[str]) -> Optional[str]:
     return text
 
 
+def resolve_hash_for_cmdlet(
+    raw_hash: Optional[str],
+    raw_path: Optional[str],
+    override_hash: Optional[str],
+) -> Optional[str]:
+    """Resolve a file hash for note/tag/file cmdlets.
+
+    Shared implementation used by add-note, delete-note, get-note, and similar
+    cmdlets that need to identify a file by its SHA-256 hash.
+
+    Resolution order:
+    1. ``override_hash`` — explicit hash provided via *-query* (highest priority)
+    2. ``raw_hash`` — positional hash argument
+    3. ``raw_path`` stem — if the filename stem is a 64-char hex string it is
+       treated directly as the hash (Hydrus-style naming convention)
+    4. SHA-256 computed from the file at ``raw_path``
+
+    Args:
+        raw_hash: Hash string from positional argument.
+        raw_path: Filesystem path to the file (may be None).
+        override_hash: Hash extracted from *-query* (takes precedence).
+
+    Returns:
+        Normalised 64-char lowercase hex hash, or ``None`` if unresolvable.
+    """
+    resolved = normalize_hash(override_hash) if override_hash else normalize_hash(raw_hash)
+    if resolved:
+        return resolved
+    if raw_path:
+        try:
+            p = Path(str(raw_path))
+            stem = p.stem
+            if len(stem) == 64 and all(c in "0123456789abcdef" for c in stem.lower()):
+                return stem.lower()
+            if p.exists() and p.is_file():
+                from SYS.utils import sha256_file as _sha256_file
+                return _sha256_file(p)
+        except Exception:
+            return None
+    return None
+
+
 def parse_hash_query(query: Optional[str]) -> List[str]:
     """Parse a unified query string for `hash:` into normalized SHA256 hashes.