sessionmemory 0.2.0__py3-none-any.whl

sessionmemory/commands/new.py

@@ -0,0 +1,102 @@
+"""Commands that create a page or a document and print the path to write into."""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import (
+    emit_json,
+    fail,
+    require_project,
+    require_vault,
+    resolve_body,
+)
+from sessionmemory.lib import field, paths
+from sessionmemory.lib.config import now
+
+app = typer.Typer(no_args_is_help=True, help="Create a learning, spec, or plan.")
+
+TITLE = typer.Option(..., "--title", help="The title.")
+SUMMARY = typer.Option(..., "--summary", help="One sentence a search result shows.")
+BODY = typer.Option("", "--body", help="Markdown body.")
+BODY_FILE = typer.Option(None, "--body-file", help="Read the body from a file, or stdin for '-'.")
+CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def _report(path: Path, *, as_json: bool, uuid: str | None = None) -> None:
+    if as_json:
+        payload: dict[str, str] = {"path": str(path), "title": field.read_page(path).title}
+        if uuid is not None:
+            payload["uuid"] = uuid
+        emit_json(payload)
+        return
+    pp.success(f"created {path.name}", details=[str(path)])
+
+
+@app.command("learning")
+def new_learning(
+    title: str = TITLE,
+    summary: str = SUMMARY,
+    body: str = BODY,
+    body_file: Path | None = BODY_FILE,
+    cwd: Path | None = CWD,
+    *,
+    as_json: bool = JSON,
+) -> None:
+    """Create a memory page in this project's learnings field."""
+    body = resolve_body(body, body_file)
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    try:
+        path = field.new_page(
+            paths.learnings_dir(vault, slug), title=title, summary=summary, body=body, now=now()
+        )
+    except field.PageError as error:
+        fail(str(error))
+    _report(path, as_json=as_json, uuid=field.read_page(path).uuid)
+
+
+def _new_document(folder: Path, title: str, body: str, *, as_json: bool) -> None:
+    try:
+        path = field.new_document(folder, title=title, body=body, now=now())
+    except field.PageError as error:
+        fail(str(error))
+    _report(path, as_json=as_json)
+
+
+@app.command("spec")
+def new_spec(
+    title: str = TITLE,
+    body: str = BODY,
+    body_file: Path | None = BODY_FILE,
+    cwd: Path | None = CWD,
+    *,
+    as_json: bool = JSON,
+) -> None:
+    """Create a spec for this project."""
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    _new_document(
+        paths.specs_dir(vault, slug), title, resolve_body(body, body_file), as_json=as_json
+    )
+
+
+@app.command("plan")
+def new_plan(
+    title: str = TITLE,
+    body: str = BODY,
+    body_file: Path | None = BODY_FILE,
+    cwd: Path | None = CWD,
+    *,
+    as_json: bool = JSON,
+) -> None:
+    """Create a plan for this project."""
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    _new_document(
+        paths.plans_dir(vault, slug), title, resolve_body(body, body_file), as_json=as_json
+    )

sessionmemory/commands/project.py

@@ -0,0 +1,321 @@
+"""Commands that answer and record which project a directory belongs to."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import (
+    emit_json,
+    fail,
+    report_malformed_registry,
+    require_vault,
+)
+from sessionmemory.lib import paths as paths_lib
+from sessionmemory.lib import registry
+from sessionmemory.lib.gitinfo import git_context
+from sessionmemory.lib.ids import slugify
+from sessionmemory.lib.resolve import resolve as resolve_project
+
+CWD_OPTION = typer.Option(None, "--cwd", help="Directory to resolve. Defaults to the shell's.")
+JSON_OPTION = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+SLUG_OPTION = typer.Option(None, "--slug", help="Override the derived slug.")
+REGISTER_OPTION = typer.Option(
+    False,  # noqa: FBT003
+    "--register",
+    help="Create this directory's registry entry.",
+)
+
+
+def _target(cwd: Path | None) -> Path:
+    """Return the directory to operate on.
+
+    Args:
+        cwd (Path | None): An explicit directory, or None for the current one.
+
+    Returns:
+        Path: The resolved directory.
+    """
+    return (cwd or Path.cwd()).resolve()
+
+
+def _slug_from_remotes(remotes: tuple[str, ...]) -> str | None:
+    """Return the repository name from the first normalized remote.
+
+    The remote is preferred over the directory name because a checkout can be renamed
+    or cloned into a differently named directory while the remote stays put.
+
+    Args:
+        remotes (tuple[str, ...]): Normalized remote keys, as `host/owner/name`.
+
+    Returns:
+        str | None: The repository name, or None when there are no remotes.
+    """
+    for remote in remotes:
+        name = remote.rstrip("/").rsplit("/", 1)[-1]
+        if name:
+            return name
+    return None
+
+
+def _derived_slug(remotes: tuple[str, ...], root: Path) -> str:
+    """Slugify the best name available for a project the caller did not name.
+
+    A derived slug has to satisfy the same rule an explicit `--slug` must already meet,
+    since either becomes a directory name under `projects/`. Explicit input is refused
+    rather than corrected because a caller must not silently get a slug it did not ask
+    for, but a remote or directory name has no caller to surprise, so it is slugified:
+    `My.Repo` becomes `my-repo`. A remote is preferred over the directory name because a
+    checkout can be renamed while the remote stays put, and the directory name is the
+    only source a project outside git has.
+
+    Args:
+        remotes (tuple[str, ...]): Normalized remote keys, as `host/owner/name`.
+        root (Path): The project root being registered.
+
+    Returns:
+        str: The slug to register under.
+
+    Raises:
+        Exit: When neither the remote nor the directory name yields a slug.
+    """
+    for candidate in (_slug_from_remotes(remotes), root.name):
+        if not candidate:
+            continue
+        try:
+            return slugify(candidate)
+        except ValueError:
+            continue
+
+    pp.error(
+        f"cannot derive a slug from {root.name or str(root)!r}",
+        details=["name it explicitly, for example: --slug my-project"],
+    )
+    raise typer.Exit(1)
+
+
+def _require_slug_form(slug: str) -> None:
+    """Refuse a `--slug` that is not already the form the vault files projects under.
+
+    An explicit value is rejected rather than quietly corrected: a caller that asked
+    for one slug must not silently end up with another, and the slug becomes a
+    directory name under `projects/`, so anything outside the slug alphabet is either a
+    path escape or a name that will not match its own notes.
+
+    Args:
+        slug (str): The value passed to `--slug`.
+
+    Raises:
+        Exit: When the value is blank or is not its own slugification.
+    """
+    if not slug.strip():
+        pp.error("--slug must not be empty")
+        raise typer.Exit(1)
+
+    try:
+        normalized: str | None = slugify(slug)
+    except ValueError:
+        normalized = None
+
+    if normalized != slug:
+        pp.error(
+            "--slug must be lowercase letters, digits, and hyphens",
+            details=[f"try: --slug {normalized}"] if normalized else [],
+        )
+        raise typer.Exit(1)
+
+
+def _entry_root(vault: Path, slug: str, fallback: Path) -> str:
+    """Return the root the registry records for `slug`.
+
+    A directory outside git resolves by longest path prefix, so the directory asked
+    about is routinely several levels below the one the entry was registered at, and
+    reporting the former would name a root the registry does not hold.
+
+    Args:
+        vault (Path): The vault root.
+        slug (str): The project the entry belongs to.
+        fallback (Path): The directory asked about, for an entry that has since gone.
+
+    Returns:
+        str: The recorded root.
+    """
+    entry = registry.load(vault).get(slug)
+    return entry.root if entry else str(fallback)
+
+
+def _report(vault: Path, target: Path, action: str | None, *, as_json: bool) -> None:
+    """Print the entry as it now stands, and exit non-zero when there is none.
+
+    This is the command's only stdout in either mode, so a write is reported by showing
+    its result rather than by a line of its own.
+
+    Args:
+        vault (Path): The vault root.
+        target (Path): The directory to report on.
+        action (str | None): The verb naming a write that just happened, or None for a
+            plain view.
+        as_json (bool): Emit the payload instead of prose.
+
+    Raises:
+        Exit: With code 1 when the directory is not registered.
+    """
+    try:
+        result = resolve_project(vault, target)
+    except registry.RegistryError as error:
+        report_malformed_registry(vault, error)
+
+    project_paths = (
+        paths_lib.project_paths(vault, result.slug) if result.registered and result.slug else {}
+    )
+
+    payload = {
+        "slug": result.slug,
+        "registered": result.registered,
+        "repo_root": str(result.repo_root) if result.repo_root else None,
+        "is_worktree": result.is_worktree,
+        "project_dir": (
+            str(paths_lib.project_dir(vault, result.slug))
+            if result.registered and result.slug
+            else None
+        ),
+        "paths": project_paths,
+    }
+
+    if as_json:
+        emit_json(payload)
+    elif result.registered:
+        headline = f"{action} {result.slug!r}" if action else result.slug or ""
+        root = _entry_root(vault, result.slug, target) if result.slug else str(target)
+        pp.success(headline, details=[f"root: {root}"])
+    else:
+        pp.error(
+            f"{target} is not a registered project",
+            details=["run: sessionmemory project --register"],
+        )
+
+    if not result.registered:
+        raise typer.Exit(1)
+
+
+def _register(
+    vault: Path,
+    target: Path,
+    slug: str | None,
+) -> None:
+    """Record this directory in the vault registry.
+
+    Args:
+        vault (Path): The vault root.
+        target (Path): The directory to register.
+        slug (str | None): An explicit slug, or None to derive one.
+
+    Raises:
+        Exit: When the target is not an existing directory, when git could not determine
+            whether it is a repository, when it is a bare repository, when it is already
+            registered, when its slug is already in use, or when no slug can be derived
+            from its remote or its directory name.
+    """
+    # A slug is permanent and its notes have to be moved by hand, so a mistyped --cwd is
+    # the one accident registration must not accept.
+    if not target.is_dir():
+        pp.error(
+            f"{target} is not a directory",
+            details=["--cwd takes a directory that exists"],
+        )
+        raise typer.Exit(1)
+
+    context = git_context(target)
+
+    # An entry recorded while git was unavailable stays wrong once git works again: a
+    # repository would be filed as a plain directory, with no remote and the wrong root.
+    if not context.git_answered:
+        pp.error(
+            f"cannot tell whether {target} is a git repository",
+            details=[
+                "git did not answer: it may be missing, or it may refuse this directory",
+                "fix that first, since a slug is permanent once notes carry it",
+            ],
+        )
+        raise typer.Exit(1)
+
+    # A bare repository has no working tree, so no working directory belongs to it and
+    # nothing filed under it could ever be resolved back.
+    if context.is_bare:
+        pp.error(
+            f"{target} is a bare repository",
+            details=["register a working checkout instead"],
+        )
+        raise typer.Exit(1)
+
+    # A directory outside git has no remote and no repository root, so the directory
+    # itself is the only key it can be registered and resolved under.
+    root = context.repo_root or target
+
+    if slug is not None:
+        _require_slug_form(slug)
+
+    try:
+        projects = registry.load(vault)
+    except registry.RegistryError as error:
+        report_malformed_registry(vault, error)
+
+    existing = registry.find_by_remote(projects, context.remotes) or registry.find_by_root(
+        projects, str(root)
+    )
+    if existing:
+        pp.error(f"already registered as {existing.slug!r}")
+        raise typer.Exit(1)
+
+    resolved_slug = slug if slug is not None else _derived_slug(context.remotes, root)
+    if resolved_slug in projects:
+        pp.error(f"slug {resolved_slug!r} is already in use; pass --slug")
+        raise typer.Exit(1)
+
+    # Read before the new entry is inserted, or it would match itself.
+    enclosing = registry.find_by_path_prefix(projects, str(root))
+
+    projects[resolved_slug] = registry.Project(
+        slug=resolved_slug,
+        remotes=context.remotes,
+        root=str(root),
+    )
+    registry.save(vault, projects)
+
+    # Registering inside another project is legitimate, but an accidental one looks
+    # exactly like a deliberate one, so the nesting is reported rather than assumed.
+    if enclosing is not None:
+        pp.warning(
+            f"{root} sits inside project {enclosing.slug!r}",
+            details=[
+                f"{resolved_slug!r} now wins for paths under {root}",
+                f"remove it from the registry if you meant to use {enclosing.slug!r}",
+            ],
+        )
+
+
+def project_command(
+    cwd: Path | None = CWD_OPTION,
+    slug: str | None = SLUG_OPTION,
+    *,
+    register: bool = REGISTER_OPTION,
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Report this directory's project, or create its registry entry.
+
+    Raises:
+        Exit: When `--slug` is given without `--register`, when `--register` names a
+            directory that does not exist, is a bare repository, or is already
+            registered, or with code 1 when the directory has no project.
+    """
+    if slug is not None and not register:
+        fail("--slug applies only with --register", ["a slug is permanent once notes carry it"])
+    vault = require_vault()
+    target = _target(cwd)
+    action: str | None = None
+    if register:
+        _register(vault, target, slug)
+        action = "registered"
+    _report(vault, target, action, as_json=as_json)

sessionmemory/commands/reindex.py

@@ -0,0 +1,46 @@
+"""The `reindex` command: rebuild a project's field indexes from its pages."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from pathlib import Path  # noqa: TC003
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import (
+    build_embedder,
+    emit_json,
+    require_project,
+    require_vault,
+)
+from sessionmemory.lib import fieldindex, paths
+
+CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def reindex_command(cwd: Path | None = CWD, *, as_json: bool = JSON) -> None:
+    """Bring this project's learnings and logs indexes up to date."""
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    embedder = build_embedder()
+    fields = {
+        "learnings": paths.learnings_dir(vault, slug),
+        "logs": paths.logs_dir(vault, slug),
+    }
+    if as_json:
+        emit_json(
+            {
+                name: asdict(fieldindex.refresh(directory, embedder))
+                for name, directory in fields.items()
+            }
+        )
+        return
+    with pp.step("reindexing") as step:
+        for name, directory in fields.items():
+            result = fieldindex.refresh(directory, embedder)
+            step.sub(
+                f"{name}: {result.added} added, {result.updated} updated, "
+                f"{result.removed} removed, {result.unchanged} unchanged"
+            )

sessionmemory/commands/search.py

@@ -0,0 +1,83 @@
+"""The `search` command: the one read the agent cannot do with its own tools."""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import (
+    build_embedder,
+    emit_json,
+    emit_value,
+    fail,
+    require_project,
+    require_vault,
+)
+from sessionmemory.lib import fieldindex, paths
+
+QUERY = typer.Argument(..., help="What to look for, in plain words.")
+LOGS = typer.Option(False, "--logs", help="Search past session logs instead of learnings.")  # noqa: FBT003
+LIMIT = typer.Option(10, "--limit", help="Maximum number of results.")
+MAX_DISTANCE = typer.Option(
+    fieldindex.DEFAULT_MAX_DISTANCE,
+    "--max-distance",
+    min=0.0,
+    max=2.0,
+    help="Farthest cosine distance that still counts as a hit.",
+)
+READ = typer.Option(False, "--read", help="Print each hit's whole file under its path.")  # noqa: FBT003
+CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def search_command(
+    query: str = QUERY,
+    *,
+    logs: bool = LOGS,
+    limit: int = LIMIT,
+    max_distance: float = MAX_DISTANCE,
+    read: bool = READ,
+    cwd: Path | None = CWD,
+    as_json: bool = JSON,
+) -> None:
+    """Find the pages nearest in meaning to the query, nearest first."""
+    if limit < 1:
+        fail("--limit must be at least 1")
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    directory = paths.logs_dir(vault, slug) if logs else paths.learnings_dir(vault, slug)
+    hits = fieldindex.search(
+        directory, build_embedder(), query, limit=limit, max_distance=max_distance
+    )
+
+    if as_json:
+        payload = []
+        for hit in hits:
+            entry: dict[str, object] = {
+                "path": str(hit.path),
+                "title": hit.title,
+                "summary": hit.summary,
+                "distance": hit.distance,
+            }
+            if read:
+                entry["content"] = _content(hit.path)
+            payload.append(entry)
+        emit_json(payload)
+        return
+    if not hits:
+        pp.info(
+            f"no results within distance {max_distance}; raise --max-distance to see farther pages"
+        )
+        return
+    # A path, a title, a summary, and a page are all things a caller copies or parses,
+    # so nothing here may be styled.
+    if read:
+        emit_value("\n\n".join(f"{hit.path}\n{_content(hit.path).rstrip()}" for hit in hits))
+        return
+    emit_value("\n\n".join(f"{hit.path}\n  {hit.title}\n  {hit.summary}" for hit in hits))
+
+
+def _content(path: Path) -> str:
+    return path.read_bytes().decode("utf-8", errors="replace")

sessionmemory/lib/__init__.py

@@ -0,0 +1 @@
+"""Session memory CLI library."""

sessionmemory/lib/atomic.py

@@ -0,0 +1,71 @@
+"""Replace a file's contents in one step, or not at all.
+
+Every file this CLI owns is the source of truth for something that cannot be rebuilt: a
+note is knowledge no index holds a copy of, and the registry is the only record of which
+slug a project's existing notes were filed under. A write interrupted by a crash, a full
+disk, or a signal must therefore leave the previous contents in place rather than a
+truncated file, so contents are written to a temporary file beside the target and renamed
+over it.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+DEFAULT_UMASK = 0o022
+
+
+def write_text(path: Path, text: str) -> None:
+    """Write `text` to `path`, replacing it in a single rename.
+
+    Args:
+        path (Path): The destination file. Its parent directory is created if needed.
+        text (str): The complete contents to write.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    handle, name = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    temporary = Path(name)
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as file:
+            file.write(text)
+        # mkstemp creates the file mode 0600; match the umask default so a CLI-written
+        # file is indistinguishable from one made by hand, since Path.replace preserves
+        # the source file's mode across the rename.
+        umask = os.umask(DEFAULT_UMASK)
+        os.umask(umask)
+        temporary.chmod(0o666 & ~umask)
+        temporary.replace(path)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def claim(path: Path) -> bool:
+    """Create `path` as an empty file, or report that someone else already has it.
+
+    Exclusive creation is the only way to take a filename that cannot lose a race. A
+    check followed by a write leaves a window in which another process takes the same
+    name, and `write_text` renames over whatever is there, so the loser's note is
+    destroyed with nothing reported. `Path.touch(exist_ok=False)` is `O_CREAT |
+    O_EXCL | O_WRONLY` under the hood, so this needs no lock file to clean up after a
+    crash.
+
+    On a case-insensitive filesystem, which is the default on macOS, this also refuses a
+    name differing only in case from an existing file. That is the wanted behavior:
+    those two names cannot coexist there.
+
+    Args:
+        path (Path): The file to claim. Its parent directory is created if needed.
+
+    Returns:
+        bool: True when this call created the file, False when it already existed.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        path.touch(exist_ok=False)
+    except FileExistsError:
+        return False
+    return True