fkf 5.0.0__py3-none-any.whl

fkf/__init__.py

@@ -0,0 +1,22 @@
+"""Local, offline evidence retrieval for coding agents."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+from typing import NoReturn
+
+__version__ = version("fkf")
+DISPLAY_VERSION = f"v{__version__}"
+
+
+def main() -> NoReturn:
+    """Run the ``fkf`` console command."""
+    from fkf.cli import app
+    from fkf.cli_support import exit_main
+    from fkf.logging_config import configure_logging
+
+    configure_logging()
+    exit_main(app)
+
+
+__all__ = ["DISPLAY_VERSION", "__version__", "main"]

fkf/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from fkf import main
+
+if __name__ == "__main__":
+    main()

fkf/assets.py

@@ -0,0 +1,117 @@
+"""Wheel-safe access to FKF's exact bundled presets, helpers, skills, and evals."""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+from collections.abc import Mapping
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import PurePosixPath
+from typing import Final
+
+PRESETS: Final = ("minimal", "personal", "team")
+BUNDLED_SKILLS: Final = ("fkf-use", "fkf-learn", "daily-brief")
+HOOK_SCRIPT: Final = "fkf-hook.py"
+DEMO_HELPER: Final = "fkf-demo-json.sh"
+_PYTHON_BYTECODE_SUFFIXES: Final = frozenset({".pyc", ".pyo"})
+
+
+def asset_root() -> Traversable:
+    """Return the package resource tree without assuming a filesystem install."""
+    return resources.files("fkf").joinpath("assets_data")
+
+
+def _parts(relative: str) -> tuple[str, ...]:
+    path = PurePosixPath(relative)
+    if not relative or path.is_absolute() or any(part in {"", ".", ".."} for part in path.parts):
+        raise ValueError(f"invalid bundled asset path {relative!r}")
+    return path.parts
+
+
+def asset(relative: str) -> Traversable:
+    """Resolve one confined package resource."""
+    return asset_root().joinpath(*_parts(relative))
+
+
+def read_asset(relative: str) -> bytes:
+    """Read one exact bundled file from a source tree, wheel, or zip import."""
+    target = asset(relative)
+    if not target.is_file():
+        raise FileNotFoundError(f"bundled asset {relative!r} is missing or not a file")
+    return target.read_bytes()
+
+
+def _walk_files(root: Traversable, prefix: str = "") -> list[tuple[str, bytes]]:
+    files: list[tuple[str, bytes]] = []
+    for entry in sorted(root.iterdir(), key=lambda item: item.name):
+        relative = f"{prefix}/{entry.name}" if prefix else entry.name
+        if entry.is_dir():
+            # Editable installs expose ignored interpreter caches that wheels and sdists omit.
+            if entry.name == "__pycache__":
+                continue
+            files.extend(_walk_files(entry, relative))
+        elif entry.is_file():
+            if PurePosixPath(entry.name).suffix in _PYTHON_BYTECODE_SUFFIXES:
+                continue
+            files.append((relative, entry.read_bytes()))
+        else:
+            raise ValueError(f"bundled asset {relative!r} is neither a regular file nor a directory")
+    return files
+
+
+def asset_files(relative: str) -> tuple[tuple[str, bytes], ...]:
+    """Return all files below one bundled directory in stable relative-path order."""
+    root = asset(relative)
+    if not root.is_dir():
+        raise FileNotFoundError(f"bundled asset directory {relative!r} is missing")
+    return tuple(_walk_files(root))
+
+
+def digest_tree(files: Mapping[str, bytes] | Traversable) -> str:
+    """Hash a tree with FKF's injective path/content framing."""
+    entries = _walk_files(files) if isinstance(files, Traversable) else sorted(files.items())
+    digest = hashlib.sha256()
+    for relative, content in entries:
+        normalized = PurePosixPath(relative).as_posix()
+        encoded = normalized.encode()
+        digest.update(b"P")
+        digest.update(struct.pack(">Q", len(encoded)))
+        digest.update(encoded)
+        digest.update(b"C")
+        digest.update(struct.pack(">Q", len(content)))
+        digest.update(content)
+    return digest.hexdigest()
+
+
+def skill_digest(name: str) -> str:
+    """Return the exact digest of one closed-vocabulary bundled skill."""
+    if name not in BUNDLED_SKILLS:
+        raise ValueError(f"unknown bundled skill {name!r}")
+    target = asset(f"skills/{name}")
+    if not target.is_dir():
+        raise FileNotFoundError(f"bundled skill {name!r} is missing")
+    return digest_tree(target)
+
+
+def shipped_helpers() -> dict[str, bytes]:
+    """Load every official helper by basename in deterministic order."""
+    helpers = dict(asset_files("presets/bin"))
+    if HOOK_SCRIPT not in helpers:
+        raise FileNotFoundError(f"bundled helper {HOOK_SCRIPT!r} is missing")
+    return helpers
+
+
+__all__ = [
+    "BUNDLED_SKILLS",
+    "DEMO_HELPER",
+    "HOOK_SCRIPT",
+    "PRESETS",
+    "asset",
+    "asset_files",
+    "asset_root",
+    "digest_tree",
+    "read_asset",
+    "shipped_helpers",
+    "skill_digest",
+]

fkf/assets_data/demo/fkf-demo-json.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+set -eu
+
+[ "$#" -eq 2 ] || { echo "usage: fkf-demo-json.sh <source> <date>" >&2; exit 2; }
+source=$1
+date=$2
+case "$source" in
+  github-pull-requests|google-calendar-events|google-gmail-emails|jira-issues|git-commits|shell-commands) ;;
+  *) echo "unknown synthetic source: $source" >&2; exit 2 ;;
+esac
+case "$date" in
+  ????-??-??) ;;
+  *) echo "date must be YYYY-MM-DD" >&2; exit 2 ;;
+esac
+case "$date" in
+  *[!0-9-]*) echo "date must be YYYY-MM-DD" >&2; exit 2 ;;
+esac
+
+printf '[{"id":"%s-%s-0","time":"%s","title":"Synthetic %s activity","url":"https://example.test/demo/%s/%s","repo":"repo:github.com/fmind/fkf","author":"person:email/demo@example.test","attendees":["person:email/demo@example.test"],"from":"person:email/demo@example.test","to":["person:email/reader@example.test"],"assignee":"person:email/demo@example.test","ticket":"ticket:DEMO-1"}]\n' \
+  "$source" "$date" "$date" "$source" "$source" "$date"

fkf/assets_data/presets/bin/agent-memory-body.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Print one bounded file from the reviewed coding-agent memory roots."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+LIMIT = 4 * 1024 * 1024
+READ_BYTES = 64 << 10
+type PathPart = str | bytes | os.PathLike[str] | os.PathLike[bytes]
+
+
+def reviewed_root(path: Path, home: Path) -> Path | None:
+    candidates = (
+        (home / ".claude" / "projects", lambda parts: len(parts) == 3 and parts[1] == "memory"),
+        (home / ".codex" / "memories", lambda parts: 1 <= len(parts) <= 2),
+        (home / ".gemini" / "tmp", lambda parts: len(parts) == 3 and parts[1] == "memory"),
+        (home / ".grok" / "memory", lambda parts: 1 <= len(parts) <= 2),
+    )
+    for root, shape in candidates:
+        try:
+            relative = path.relative_to(root)
+        except ValueError:
+            continue
+        if path.suffix == ".md" and ".." not in relative.parts and shape(relative.parts):
+            return root
+    return None
+
+
+def fingerprint(value: os.stat_result) -> tuple[int, int, int, int, int, int]:
+    return value.st_dev, value.st_ino, value.st_mode, value.st_size, value.st_mtime_ns, value.st_ctime_ns
+
+
+def open_directory(path: PathPart, parent: int | None = None) -> int:
+    inspected = os.stat(path, dir_fd=parent, follow_symlinks=False)
+    if not stat.S_ISDIR(inspected.st_mode):
+        raise RuntimeError("memory root is missing or linked")
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(path, flags, dir_fd=parent)
+    if fingerprint(inspected) != fingerprint(os.fstat(descriptor)):
+        os.close(descriptor)
+        raise RuntimeError("memory root changed while it was being opened")
+    return descriptor
+
+
+def open_chain(home: Path, components: tuple[str, ...]) -> int:
+    descriptor = open_directory(home)
+    try:
+        for component in components:
+            child = open_directory(component, descriptor)
+            os.close(descriptor)
+            descriptor = child
+    except BaseException:
+        os.close(descriptor)
+        raise
+    return descriptor
+
+
+def read_body(home: Path, path: Path) -> bytes:
+    relative = path.relative_to(home)
+    parent = open_chain(home, relative.parts[:-1])
+    descriptor = -1
+    try:
+        name = relative.parts[-1]
+        inspected = os.stat(name, dir_fd=parent, follow_symlinks=False)
+        if not stat.S_ISREG(inspected.st_mode):
+            raise RuntimeError("file is absent, linked, or outside the reviewed roots")
+        flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+        descriptor = os.open(name, flags, dir_fd=parent)
+        opened = os.fstat(descriptor)
+        if fingerprint(inspected) != fingerprint(opened):
+            raise RuntimeError("memory file changed while it was being opened")
+        output = bytearray()
+        while chunk := os.read(descriptor, min(READ_BYTES, LIMIT + 1 - len(output))):
+            output.extend(chunk)
+            if len(output) > LIMIT:
+                raise RuntimeError(f"file exceeds the {LIMIT}-byte body limit")
+        after = os.fstat(descriptor)
+        current = os.stat(name, dir_fd=parent, follow_symlinks=False)
+        if fingerprint(opened) != fingerprint(after) or fingerprint(opened) != fingerprint(current):
+            raise RuntimeError("memory file changed while it was being read")
+        return bytes(output)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        os.close(parent)
+
+
+def main(arguments: list[str]) -> int:
+    if arguments[:1] in (["--version"], ["-v"]):
+        sys.stdout.write("agent-memory-body.py (fkf base helper)\n")
+        return 0
+    if len(arguments) != 1:
+        sys.stderr.write("usage: agent-memory-body.py <absolute-memory-file>\n")
+        return 2
+    path = Path(arguments[0])
+    root = reviewed_root(path, Path(os.environ.get("HOME", "")))
+    if root is None:
+        sys.stderr.write("agent-memory-body.py: path is outside the reviewed harness memory roots\n")
+        return 2
+    try:
+        content = read_body(Path(os.environ.get("HOME", "")), path)
+    except RuntimeError as error:
+        sys.stderr.write(f"agent-memory-body.py: {error}\n")
+        return 1
+    except OSError:
+        sys.stderr.write("agent-memory-body.py: file is absent, linked, or outside the reviewed roots\n")
+        return 1
+    sys.stdout.buffer.write(content)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

fkf/assets_data/presets/bin/agent-memory-files.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Project bounded metadata for coding-agent memory files touched in a UTC window."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+PREVIEW_BYTES = 65_536
+PREVIEW_LINES = 256
+READ_BYTES = 64 << 10
+MAX_FILES = 8192
+MAX_RECORDS = 8192
+MAX_OUTPUT_BYTES = 64 << 20
+type PathPart = str | bytes | os.PathLike[str] | os.PathLike[bytes]
+
+
+@dataclass(frozen=True)
+class MemoryFile:
+    path: Path
+    inspected: os.stat_result
+
+
+def instant(value: str) -> datetime:
+    parsed = datetime.fromisoformat(value)
+    if parsed.tzinfo is None:
+        raise ValueError("timestamp must include an offset")
+    return parsed.astimezone(UTC)
+
+
+def fingerprint(value: os.stat_result) -> tuple[int, int, int, int, int, int]:
+    return value.st_dev, value.st_ino, value.st_mode, value.st_size, value.st_mtime_ns, value.st_ctime_ns
+
+
+def open_directory(path: PathPart, parent: int | None = None, expected: os.stat_result | None = None) -> int:
+    inspected = os.stat(path, dir_fd=parent, follow_symlinks=False)
+    if not stat.S_ISDIR(inspected.st_mode):
+        raise RuntimeError("memory root is missing or linked")
+    if expected is not None and fingerprint(expected) != fingerprint(inspected):
+        raise RuntimeError("memory root changed while it was being opened")
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(path, flags, dir_fd=parent)
+    if fingerprint(inspected) != fingerprint(os.fstat(descriptor)):
+        os.close(descriptor)
+        raise RuntimeError("memory root changed while it was being opened")
+    return descriptor
+
+
+def open_chain(home: Path, components: tuple[str, ...]) -> int:
+    descriptor = open_directory(home)
+    try:
+        for component in components:
+            child = open_directory(component, descriptor)
+            os.close(descriptor)
+            descriptor = child
+    except BaseException:
+        os.close(descriptor)
+        raise
+    return descriptor
+
+
+def read_prefix(home: Path, candidate: MemoryFile) -> bytes:
+    relative = candidate.path.relative_to(home)
+    parent = open_chain(home, relative.parts[:-1])
+    descriptor = -1
+    try:
+        name = relative.parts[-1]
+        inspected = os.stat(name, dir_fd=parent, follow_symlinks=False)
+        if not stat.S_ISREG(inspected.st_mode):
+            raise RuntimeError("memory file is missing or linked")
+        if fingerprint(candidate.inspected) != fingerprint(inspected):
+            raise RuntimeError("memory file changed while it was being opened")
+        flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+        descriptor = os.open(name, flags, dir_fd=parent)
+        opened = os.fstat(descriptor)
+        if fingerprint(inspected) != fingerprint(opened):
+            raise RuntimeError("memory file changed while it was being opened")
+        output = bytearray()
+        while len(output) < PREVIEW_BYTES and (
+            chunk := os.read(descriptor, min(READ_BYTES, PREVIEW_BYTES - len(output)))
+        ):
+            output.extend(chunk)
+        after = os.fstat(descriptor)
+        current = os.stat(name, dir_fd=parent, follow_symlinks=False)
+        if fingerprint(opened) != fingerprint(after) or fingerprint(opened) != fingerprint(current):
+            raise RuntimeError("memory file changed while it was being read")
+        return bytes(output)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        os.close(parent)
+
+
+def title_of(home: Path, candidate: MemoryFile) -> str:
+    preview = read_prefix(home, candidate).decode("utf-8", errors="replace").splitlines()[:PREVIEW_LINES]
+    front = bool(preview and preview[0] == "---")
+    for index, line in enumerate(preview):
+        if index == 0 and front:
+            continue
+        if front and line == "---":
+            front = False
+            continue
+        if front and line.startswith("name: "):
+            return line.removeprefix("name: ")
+        if not front and line.startswith("# "):
+            return line.removeprefix("# ")
+    return candidate.path.stem
+
+
+def clean_title(value: str) -> str:
+    printable = "".join(" " if ord(character) < 32 or ord(character) == 127 else character for character in value)
+    return re.sub(r"\s+", " ", printable).strip()[:160]
+
+
+def allowed_file(parts: tuple[str, ...], memory_component: bool) -> bool:
+    if memory_component:
+        return len(parts) == 3 and parts[1] == "memory"
+    return 1 <= len(parts) <= 2
+
+
+def allowed_directory(parts: tuple[str, ...], memory_component: bool) -> bool:
+    if memory_component:
+        return len(parts) == 1 or (len(parts) == 2 and parts[1] == "memory")
+    return len(parts) == 1
+
+
+def scan_files(
+    descriptor: int,
+    root: Path,
+    parts: tuple[str, ...],
+    memory_component: bool,
+    maximum: int,
+    results: list[MemoryFile],
+) -> None:
+    with os.scandir(descriptor) as entries:
+        for entry in entries:
+            relative = (*parts, entry.name)
+            inspected = entry.stat(follow_symlinks=False)
+            if stat.S_ISDIR(inspected.st_mode) and allowed_directory(relative, memory_component):
+                child = open_directory(entry.name, descriptor, inspected)
+                try:
+                    scan_files(child, root, relative, memory_component, maximum, results)
+                finally:
+                    os.close(child)
+            elif (
+                stat.S_ISREG(inspected.st_mode)
+                and entry.name.endswith(".md")
+                and allowed_file(relative, memory_component)
+            ):
+                if len(results) >= maximum:
+                    raise RuntimeError(f"more than {MAX_FILES} memory files")
+                results.append(MemoryFile(root.joinpath(*relative), inspected))
+
+
+def files(home: Path, root: Path, *, memory_component: bool, maximum: int) -> list[MemoryFile]:
+    try:
+        descriptor = open_chain(home, root.relative_to(home).parts)
+    except FileNotFoundError:
+        return []
+    results: list[MemoryFile] = []
+    try:
+        scan_files(descriptor, root, (), memory_component, maximum, results)
+    finally:
+        os.close(descriptor)
+    return sorted(results, key=lambda item: os.fspath(item.path))
+
+
+def main(arguments: list[str]) -> int:
+    if len(arguments) != 2:
+        sys.stderr.write("usage: agent-memory-files.py <start> <end>\n")
+        return 2
+    try:
+        start, end = map(instant, arguments)
+        home = Path(os.environ.get("HOME", ""))
+        roots = (
+            (home / ".claude" / "projects", "claude", True),
+            (home / ".codex" / "memories", "codex", False),
+            (home / ".gemini" / "tmp", "gemini", True),
+            (home / ".grok" / "memory", "grok", False),
+        )
+        candidates: list[tuple[MemoryFile, str]] = []
+        for root, agent, memory_component in roots:
+            candidates.extend(
+                (candidate, agent)
+                for candidate in files(
+                    home,
+                    root,
+                    memory_component=memory_component,
+                    maximum=MAX_FILES - len(candidates),
+                )
+            )
+        records: list[dict[str, Any]] = []
+        for candidate, agent in candidates:
+            modified = datetime.fromtimestamp(candidate.inspected.st_mtime, UTC)
+            if not start <= modified < end:
+                continue
+            if len(records) >= MAX_RECORDS:
+                raise RuntimeError(f"more than {MAX_RECORDS} memory records")
+            records.append(
+                {
+                    "id": os.fspath(candidate.path),
+                    "time": modified.replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+                    "title": clean_title(title_of(home, candidate)),
+                    "agent": agent,
+                }
+            )
+        output = (json.dumps(records, ensure_ascii=False, separators=(",", ":")) + "\n").encode()
+        if len(output) > MAX_OUTPUT_BYTES:
+            raise RuntimeError("output exceeds 64 MiB")
+    except (OSError, RuntimeError, UnicodeError, ValueError) as error:
+        sys.stderr.write(f"agent-memory-files.py: {error}\n")
+        return 1
+    sys.stdout.buffer.write(output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))