sessionmemory 0.2.0__py3-none-any.whl

sessionmemory/lib/gitinfo.py

@@ -0,0 +1,177 @@
+"""Read the git facts that identify which project a directory belongs to.
+
+The repository root is the main checkout's working tree, derived from
+`--git-common-dir`, never from `--show-toplevel` alone. In a worktree the two differ:
+`--show-toplevel` returns the worktree directory while `--git-common-dir` returns the
+main checkout's `.git`. Resolving on the former would make every worktree an
+unregistered project. `_main_worktree` documents the layouts where the shared git
+directory is not a `.git` beside the checkout.
+
+An empty answer from git is not a fact about the directory. Git declining to inspect a
+directory, timing out, or not being installed at all is a different state from git
+reporting that the directory is not in a repository, and `GitContext.git_answered`
+carries that distinction so a caller never reads git's silence as "there is no
+repository here".
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from sessionmemory.lib import registry
+
+GIT_TIMEOUT_SECONDS = 10
+
+# The one git failure that is an answer rather than an outage. Every other non-zero exit,
+# such as a `safe.directory` refusal or a held index lock, leaves the question open.
+_NOT_A_REPOSITORY = "not a git repository"
+
+
+@dataclass(frozen=True)
+class _GitAnswer:
+    """One git invocation's outcome, separating a definite answer from a failure to ask."""
+
+    stdout: str | None
+    answered: bool
+
+
+@dataclass(frozen=True)
+class GitContext:
+    """What git knows about a working directory."""
+
+    repo_root: Path | None
+    worktree_root: Path | None
+    remotes: tuple[str, ...]
+    git_answered: bool
+    is_bare: bool
+
+    @property
+    def is_worktree(self) -> bool:
+        """Report whether this directory is a linked worktree.
+
+        Returns:
+            bool: True when the working tree differs from the main checkout.
+        """
+        if self.repo_root is None or self.worktree_root is None:
+            return False
+        return self.repo_root != self.worktree_root
+
+
+def _git(cwd: Path, *args: str) -> _GitAnswer:
+    """Run a git command and report both its output and whether git answered at all.
+
+    Args:
+        cwd (Path): The directory to run in.
+        *args: Arguments passed to git.
+
+    Returns:
+        _GitAnswer: The stripped stdout, and whether git reached a verdict. A non-zero
+            exit counts as a verdict only when git says the directory is not a
+            repository.
+    """
+    try:
+        completed = subprocess.run(  # noqa: S603
+            ["git", *args],  # noqa: S607
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=GIT_TIMEOUT_SECONDS,
+            # The C locale keeps git's own messages in the wording the classifier reads.
+            env={**os.environ, "LC_ALL": "C", "LANGUAGE": ""},
+        )
+    except (OSError, subprocess.SubprocessError):
+        return _GitAnswer(stdout=None, answered=False)
+
+    if completed.returncode != 0:
+        return _GitAnswer(stdout=None, answered=_NOT_A_REPOSITORY in completed.stderr.lower())
+    return _GitAnswer(stdout=completed.stdout.strip() or None, answered=True)
+
+
+def _main_worktree(cwd: Path, common_dir: Path, worktree_root: Path | None) -> Path:
+    """Return the main checkout's working tree directory.
+
+    The parent of `--git-common-dir` is the main checkout only where the shared git
+    directory is a `.git` inside that checkout. A submodule's is
+    `<superproject>/.git/modules/<path>` and a `--separate-git-dir` checkout's is
+    wherever it was put, so the parent rule would name a directory that is no working
+    tree at all: two submodules under one directory even share the same parent, which
+    would make the second one look like the first. Git sets `core.worktree` in exactly
+    the layouts where the parent rule fails, and it names the main working tree directly.
+
+    Args:
+        cwd (Path): The directory being inspected.
+        common_dir (Path): The absolute `--git-common-dir` for `cwd`.
+        worktree_root (Path | None): The `--show-toplevel` for `cwd`, if git gave one.
+
+    Returns:
+        Path: The main checkout's root.
+    """
+    # core.worktree is stored relative to the shared git directory, which is the same
+    # file for a linked worktree as for the checkout it was added from.
+    configured = _git(cwd, "config", "--local", "--get", "core.worktree").stdout
+    if configured:
+        return (common_dir / configured).resolve()
+
+    if common_dir.name == ".git":
+        return common_dir.resolve().parent
+
+    # No rule names the main checkout here, so this working tree stands in for it. It is
+    # a real directory, which the parent of the git directory would not be, and remotes
+    # are the primary registry key regardless.
+    return worktree_root or common_dir.resolve().parent
+
+
+def git_context(cwd: Path) -> GitContext:
+    """Read the repository root, worktree root, and normalized remotes for `cwd`.
+
+    Args:
+        cwd (Path): The directory to inspect.
+
+    Returns:
+        GitContext: The git facts. Both roots are None when `cwd` is not in a repository,
+            when the repository is bare, and when git could not answer, so a caller that
+            cares which of those it is reads `git_answered` and `is_bare`.
+    """
+    common_dir = _git(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir")
+    if common_dir.stdout is None:
+        return GitContext(
+            repo_root=None,
+            worktree_root=None,
+            remotes=(),
+            git_answered=common_dir.answered,
+            is_bare=False,
+        )
+
+    # A bare repository's --git-common-dir is the repository directory itself, so the
+    # parent-of-common-dir rule would name the directory containing it and hand that
+    # directory's whole subtree a project slug. It has no working tree, so no working
+    # directory belongs to it.
+    is_bare = _git(cwd, "rev-parse", "--is-bare-repository").stdout == "true"
+    if is_bare:
+        return GitContext(
+            repo_root=None, worktree_root=None, remotes=(), git_answered=True, is_bare=True
+        )
+
+    toplevel = _git(cwd, "rev-parse", "--show-toplevel").stdout
+    worktree_root = Path(toplevel).resolve() if toplevel else None
+    repo_root = _main_worktree(cwd, Path(common_dir.stdout), worktree_root)
+
+    # --local reads only this repository's config. Without it a stray remote in
+    # ~/.gitconfig would be read as this repository's remote and become a registry key
+    # every repository on the machine shares. A worktree reads the same local config as
+    # its main checkout, so a worktree still resolves to its parent project.
+    listed = _git(cwd, "config", "--local", "--get-regexp", r"^remote\..*\.url").stdout or ""
+    urls = [line.split(" ", 1)[1] for line in listed.splitlines() if " " in line]
+    remotes = tuple(dict.fromkeys(registry.normalize_remote(url) for url in urls if url))
+
+    return GitContext(
+        repo_root=repo_root,
+        worktree_root=worktree_root,
+        remotes=remotes,
+        git_answered=True,
+        is_bare=False,
+    )

sessionmemory/lib/ids.py

@@ -0,0 +1,101 @@
+"""Turn a title into a filename stem.
+
+A stem only has to be unique inside the flat directory it is written to. The slug
+alphabet is the memoryfield spec's: lowercase ASCII letters, digits, and hyphens.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Container, Iterator
+
+MAX_ID_LENGTH = 72
+
+_NON_SLUG = re.compile(r"[^a-z0-9]+")
+
+# What a leading date costs an id, reserved out of the length budget so a dated id
+# still fits MAX_ID_LENGTH.
+DATE_PREFIX_WIDTH = len("2026-08-18-")
+
+
+def slugify(title: str, *, max_length: int = MAX_ID_LENGTH) -> str:
+    """Reduce a title to a lowercase, hyphenated, ascii slug.
+
+    Args:
+        title (str): The note title.
+        max_length (int): The longest slug to return. A caller whose id will carry a
+            prefix passes a smaller budget so the finished id still fits the limit.
+
+    Returns:
+        str: The slug.
+
+    Raises:
+        ValueError: If the title contains no characters that survive slugification.
+    """
+    folded = unicodedata.normalize("NFKD", title).encode("ascii", "ignore").decode("ascii")
+    slug = _NON_SLUG.sub("-", folded.lower()).strip("-")
+
+    if not slug:
+        msg = f"title {title!r} has no usable characters for an id"
+        raise ValueError(msg)
+
+    if len(slug) > max_length:
+        slug = slug[:max_length].rsplit("-", 1)[0].strip("-")
+
+    return slug
+
+
+def strip_date(title: str, created: str) -> str:
+    """Remove `created` from `title`, which the filename is about to supply anyway.
+
+    Only a date equal to the note's own creation date is removed, because the problem is
+    redundancy rather than discovery: matching any date-shaped run of digits would eat a
+    version number or a date the title is genuinely about. The title itself is never
+    rewritten, only the stem derived from it, so a wrong guess costs an odd filename and
+    not a renamed note.
+
+    Args:
+        title (str): The note title.
+        created (str): The note's creation date as an ISO string.
+
+    Returns:
+        str: The title with the date removed and its whitespace collapsed, or the title
+            unchanged when removing the date would leave nothing to slugify.
+    """
+    stripped = " ".join(title.replace(created, " ").split())
+    return stripped or title
+
+
+def id_candidates(base: str, taken: Container[str]) -> Iterator[str]:
+    """Yield `base`, then `base-2`, `base-3`, ..., skipping anything `taken` reports as claimed.
+
+    `base` is expected to already be `slugify` output; its length guarantee (at most
+    `MAX_ID_LENGTH`) is what keeps the first candidate within the limit. `taken` is a
+    filter to skip likely collisions, not the final word on which candidate is free: a
+    caller with a stronger source of truth, such as an exclusive filesystem claim, is
+    expected to test each yielded candidate itself and keep pulling from this generator
+    on rejection.
+
+    Args:
+        base (str): The desired slug.
+        taken (Container[str]): Ids known to be in use, case folded. Every candidate
+            tested against it is lowercase, since `base` is a slug.
+
+    Yields:
+        str: Each untried candidate, in order, without limit.
+    """
+    if base not in taken:
+        yield base
+
+    counter = 2
+    while True:
+        suffix = f"-{counter}"
+        trimmed = base[: MAX_ID_LENGTH - len(suffix)].strip("-")
+        candidate = f"{trimmed}{suffix}"
+        if candidate not in taken:
+            yield candidate
+        counter += 1

sessionmemory/lib/inject.py

@@ -0,0 +1,97 @@
+"""Assemble and render what a project's session starts with.
+
+Guidance first, then titles. Titles rather than nothing because an agent does not
+reliably decide to search; titles rather than summaries because this is a push channel
+and must stay small. Bodies never enter an injection.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sessionmemory.lib import field, paths
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+OPEN_ITEM = "- [ ]"
+
+
+@dataclass(frozen=True)
+class Injection:
+    """Everything one project's session start receives."""
+
+    project: str
+    titles: tuple[str, ...]
+    open_backlog: int
+    specs: tuple[str, ...]
+    plans: tuple[str, ...]
+
+
+def _titles(directory: Path) -> tuple[str, ...]:
+    titles = [field.read_page(path).title or path.stem for path in field.iter_pages(directory)]
+    return tuple(sorted(titles, key=str.casefold))
+
+
+def _open_backlog(path: Path) -> int:
+    if not path.is_file():
+        return 0
+    return sum(
+        1
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.lstrip().startswith(OPEN_ITEM)
+    )
+
+
+def build(vault: Path, slug: str) -> Injection:
+    """Read the project's pages and files; the index is never consulted here."""
+    return Injection(
+        project=slug,
+        titles=_titles(paths.learnings_dir(vault, slug)),
+        open_backlog=_open_backlog(paths.backlog_path(vault, slug)),
+        specs=_titles(paths.specs_dir(vault, slug)),
+        plans=_titles(paths.plans_dir(vault, slug)),
+    )
+
+
+GUIDANCE = """## Using this vault
+
+Durable memory for this project lives in a vault of markdown pages. Below is the
+list of what it already knows; each title is one `{command} search` away.
+
+  - A title below matches what you are doing: `{command} search "<words>"` returns
+    the page's path, and you Read it. Search before assuming nothing was written down.
+  - Past sessions: `{command} search "<words>" --logs`. Open work: read `backlog.md`
+    in the project's vault folder (`{command} project --json` prints every path).
+  - Something worth keeping past this session: `{command} new learning --title "..."
+    --summary "..." --cwd .` creates the page and prints the path to write prose into.
+    Keep a page under 8KB; more detail is another page.
+  - Specs and plans: `{command} new spec|plan --title "..." --cwd .` creates the file.
+    Edit `backlog.md`, specs, and plans directly; the CLI only creates pages."""
+
+
+def render(injection: Injection, *, command: str = "sessionmemory") -> str:
+    """Render the block a session start receives: guidance, then titles, then work."""
+    lines = [GUIDANCE.format(command=command), "", "## What this project knows", ""]
+    lines.extend(f"  - {title}" for title in injection.titles)
+    if not injection.titles:
+        lines.append("  nothing yet")
+    lines.extend(["", "## Open work", ""])
+    item = "item" if injection.open_backlog == 1 else "items"
+    lines.append(f"  {injection.open_backlog} open backlog {item}")
+    lines.extend(f"  spec: {title}" for title in injection.specs)
+    lines.extend(f"  plan: {title}" for title in injection.plans)
+    return "\n".join(lines)
+
+
+def payload(injection: Injection, *, command: str) -> dict[str, object]:
+    """Build the machine-readable form, a superset of the prose."""
+    return {
+        "guidance": GUIDANCE.format(command=command),
+        "project": injection.project,
+        "titles": list(injection.titles),
+        "open_backlog": injection.open_backlog,
+        "specs": list(injection.specs),
+        "plans": list(injection.plans),
+    }

sessionmemory/lib/log.py

@@ -0,0 +1,73 @@
+"""A project's session logs: one page per session, replaced whole on every write.
+
+The body is replaced rather than appended to, so a caller sends all of it every time
+and repeated calls are idempotent. Logs are a field of their own so they can be
+searched on request without diluting the learnings field.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sessionmemory.lib import field, paths
+from sessionmemory.lib.ids import slugify, strip_date
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+SESSION_FIELD = "session_id"
+
+
+@dataclass(frozen=True)
+class Upserted:
+    """Where the log landed, and whether this call created it."""
+
+    path: Path
+    created: bool
+
+
+def find_session_log(vault: Path, slug: str, session_id: str) -> Path | None:
+    """Return the page already recording this session, if any."""
+    for path in field.iter_pages(paths.logs_dir(vault, slug)):
+        if field.read_page(path).meta.get(SESSION_FIELD) == session_id:
+            return path
+    return None
+
+
+def upsert_log(  # noqa: PLR0913
+    vault: Path,
+    *,
+    slug: str,
+    session_id: str,
+    title: str,
+    summary: str,
+    body: str,
+    now: str,
+    today: str,
+) -> Upserted:
+    """Write this session's log, replacing the page it already has rather than adding one."""
+    existing = find_session_log(vault, slug, session_id)
+    if existing is not None:
+        page = field.read_page(existing)
+        meta = dict(page.meta)
+        meta.update({"title": title, "summary": summary, "updated": now})
+        field.write_page(existing, meta, body)
+        return Upserted(path=existing, created=False)
+
+    try:
+        stem = f"{today}-{slugify(strip_date(title, today))}"
+    except ValueError as error:
+        raise field.PageError(str(error)) from error
+    path = field.claim_filename(paths.logs_dir(vault, slug), title, stem=stem)
+    meta = {
+        "title": title,
+        "uuid": str(uuid.uuid4()),
+        "summary": summary,
+        "created": now,
+        "updated": now,
+        SESSION_FIELD: session_id,
+    }
+    field.write_page(path, meta, body)
+    return Upserted(path=path, created=True)

sessionmemory/lib/paths.py

@@ -0,0 +1,77 @@
+"""Where a project's files live inside the vault.
+
+`learnings/` and `logs/` are fields: flat directories of pages, each with its own
+index. `specs/`, `plans/`, and `backlog.md` sit beside them and are never indexed. A
+project's files are found by its slug and nothing else; there is no global scope.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+PROJECTS_DIR = "projects"
+SYSTEM_DIR = "_system"
+
+LEARNINGS_DIR = "learnings"
+LOGS_DIR = "logs"
+SPECS_DIR = "specs"
+PLANS_DIR = "plans"
+BACKLOG_FILE = "backlog.md"
+
+FIELD_DIRS: tuple[str, ...] = (LEARNINGS_DIR, LOGS_DIR)
+
+
+def project_dir(vault: Path, slug: str) -> Path:
+    """Return the folder holding everything belonging to one project."""
+    return vault / PROJECTS_DIR / slug
+
+
+def learnings_dir(vault: Path, slug: str) -> Path:
+    """Return the project's learnings field."""
+    return project_dir(vault, slug) / LEARNINGS_DIR
+
+
+def logs_dir(vault: Path, slug: str) -> Path:
+    """Return the project's logs field."""
+    return project_dir(vault, slug) / LOGS_DIR
+
+
+def specs_dir(vault: Path, slug: str) -> Path:
+    """Return the project's specs folder."""
+    return project_dir(vault, slug) / SPECS_DIR
+
+
+def plans_dir(vault: Path, slug: str) -> Path:
+    """Return the project's plans folder."""
+    return project_dir(vault, slug) / PLANS_DIR
+
+
+def backlog_path(vault: Path, slug: str) -> Path:
+    """Return the project's backlog checklist file."""
+    return project_dir(vault, slug) / BACKLOG_FILE
+
+
+def project_paths(vault: Path, slug: str) -> dict[str, str]:
+    """Return every path a caller of `sessionmemory project --json` reads, by its payload key.
+
+    The keys are what `sessionmemory project --json` emits and the plugin's hooks read.
+    """
+    return {
+        "project_dir": str(project_dir(vault, slug)),
+        "learnings": str(learnings_dir(vault, slug)),
+        "logs": str(logs_dir(vault, slug)),
+        "specs": str(specs_dir(vault, slug)),
+        "plans": str(plans_dir(vault, slug)),
+        "backlog": str(backlog_path(vault, slug)),
+    }
+
+
+def iter_project_slugs(vault: Path) -> list[str]:
+    """Return every project folder's name, sorted, whether or not it is registered."""
+    root = vault / PROJECTS_DIR
+    if not root.is_dir():
+        return []
+    return sorted(entry.name for entry in root.iterdir() if entry.is_dir())