sessionmemory 0.2.0__py3-none-any.whl

sessionmemory/__init__.py

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

sessionmemory/cli.py

@@ -0,0 +1,62 @@
+"""Session memory CLI invoked as `sessionmemory` by a user."""
+
+from __future__ import annotations
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands import delete as delete_commands
+from sessionmemory.commands import doctor as doctor_commands
+from sessionmemory.commands import export as export_commands
+from sessionmemory.commands import init as init_commands
+from sessionmemory.commands import inject as inject_commands
+from sessionmemory.commands import log as log_commands
+from sessionmemory.commands import new as new_commands
+from sessionmemory.commands import project
+from sessionmemory.commands import reindex as reindex_commands
+from sessionmemory.commands import search as search_commands
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.callback()
+def _root(
+    verbosity: int = typer.Option(
+        0, "-v", "--verbose", count=True, help="Increase output verbosity. Repeat for more."
+    ),
+) -> None:
+    """Manage a project's memory in a vault of markdown pages."""
+    pp.configure(verbosity=verbosity)
+
+
+app.command("delete", help="Delete files from the vault permanently.")(
+    delete_commands.delete_command
+)
+app.command("doctor", help="Report pages, projects, and indexes worth a look.")(
+    doctor_commands.doctor_command
+)
+app.command("export", help="Write this project's field as a .memoryfield.zip.")(
+    export_commands.export_command
+)
+app.command("init", help="Create the files a new vault needs.")(init_commands.init)
+app.command("inject", help="Print what this project's session should start with.")(
+    inject_commands.inject_command
+)
+app.command("log", help="Record this session's work in one upserted page.")(
+    log_commands.log_command
+)
+app.command("project", help="Report this directory's project, or register it.")(
+    project.project_command
+)
+app.command("reindex", help="Rebuild this project's search indexes.")(
+    reindex_commands.reindex_command
+)
+app.command("search", help="Search this project's learnings by meaning, or its logs with --logs.")(
+    search_commands.search_command
+)
+app.add_typer(new_commands.app, name="new")
+
+
+def main() -> None:
+    """Run the CLI. This is the console script entry point."""
+    app()

sessionmemory/commands/__init__.py

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

sessionmemory/commands/_common.py

@@ -0,0 +1,207 @@
+"""Helpers shared by every command module."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, NoReturn
+
+import typer
+from nclutils import pp
+
+from sessionmemory.lib import embed, registry
+from sessionmemory.lib.bootstrap import is_empty
+from sessionmemory.lib.config import VaultNotConfiguredError, is_initialized, vault_root
+from sessionmemory.lib.paths import SYSTEM_DIR
+from sessionmemory.lib.resolve import resolve as resolve_project
+
+if TYPE_CHECKING:
+    from sessionmemory.lib.embed import Embedder
+
+EMBEDDER_ENV_VAR = "SESSIONMEMORY_EMBEDDER"
+
+
+def build_embedder() -> Embedder:
+    """Build the embedder commands use: the stub under test, the real model otherwise.
+
+    Read at call time so a test selects the stub with `monkeypatch.setenv`.
+    """
+    if os.environ.get(EMBEDDER_ENV_VAR) == "stub":
+        return embed.StubEmbedder()
+    return embed.default_embedder()
+
+
+STDIN_SENTINEL = "-"
+
+
+def resolve_body(body: str, body_file: Path | None) -> str:
+    """Return a note's markdown body, read from a file or stdin when one was named.
+
+    Shell-quoting a document of any real length into `--body` is impractical, so without
+    this a caller creates the note empty and then writes the file itself, which is the
+    one habit every skill in this project tells a caller not to form.
+
+    Args:
+        body (str): The `--body` value.
+        body_file (Path | None): The `--body-file` value, where `-` means stdin.
+
+    Returns:
+        str: The body to write.
+
+    Raises:
+        Exit: When both options carry a value, or the named file cannot be read.
+    """
+    if body_file is None:
+        return body
+
+    if body:
+        fail("--body and --body-file are mutually exclusive", ["pass one or the other"])
+
+    if str(body_file) == STDIN_SENTINEL:
+        return sys.stdin.read()
+
+    try:
+        return body_file.read_text(encoding="utf-8")
+    except OSError as error:
+        fail(f"cannot read {body_file}: {error.strerror or error}")
+    except UnicodeDecodeError:
+        fail(f"{body_file} is not valid UTF-8 text")
+
+
+def emit_value(text: str) -> None:
+    """Print one machine readable value with nothing added to it.
+
+    Machine readable output is read by a caller rather than by a person, so an ANSI escape
+    in it is corruption rather than decoration: a styled path breaks the page path `vault
+    search` prints for a caller to copy, and a styled version string breaks the comparison
+    it exists for. Rich styles values by default and honors `FORCE_COLOR`, which real
+    shells export, so styling does not depend on stdout being a terminal and a caller
+    cannot opt out of it. Every value a caller consumes goes through here; prose for a
+    person keeps its styling and goes through `pp.success`, `pp.warning`, and `pp.error`.
+
+    `markup=False` keeps square brackets from being read as Rich tags, `emoji=False`
+    keeps `:word:` from being replaced by the emoji of that name, `highlight=False`
+    suppresses the automatic value coloring, and `soft_wrap=True` keeps a value longer
+    than the console width on one line.
+
+    Args:
+        text (str): The value to print.
+    """
+    pp.console().print(text, markup=False, emoji=False, highlight=False, soft_wrap=True)
+
+
+def emit_json(payload: object) -> None:
+    """Print a machine readable payload as unstyled JSON.
+
+    `--json` exists so a caller can read a value out of the output instead of scraping
+    prose, which makes an escape sequence anywhere in the payload a parse error. Rich's
+    JSON printer syntax-highlights what it writes, so the payload is serialized here and
+    printed through `emit_value`, which documents why nothing may style it.
+
+    Args:
+        payload (object): Any JSON-serializable value.
+    """
+    emit_value(json.dumps(payload, indent=2))
+
+
+def require_vault() -> Path:
+    """Return an initialized vault root, or exit with the command that fixes it.
+
+    Every command needs the vault location before it can do anything else, so this is
+    the one place that turns an unset, missing, or uninitialized `SESSIONMEMORY_VAULT`
+    into a clean message instead of a traceback or a note scattered into the wrong place.
+
+    Returns:
+        Path: The resolved, initialized vault directory.
+
+    Raises:
+        Exit: When the variable is unset, names a missing directory, or names a
+            directory that `sessionmemory init` has never touched.
+    """
+    try:
+        vault = vault_root()
+    except VaultNotConfiguredError as error:
+        pp.error(str(error), details=["export SESSIONMEMORY_VAULT=/path/to/your/vault"])
+        raise typer.Exit(1) from error
+
+    if not is_initialized(vault):
+        # An empty directory is the ordinary bootstrap case, and `sessionmemory init` is safe
+        # for a caller, human or agent, to run there. A non-empty directory holding no
+        # marker is different: initializing it is a one-time human decision about a
+        # specific path, never something to hand an agent as its next action, so that
+        # case is described rather than phrased as a `run:` instruction to follow.
+        if is_empty(vault):
+            pp.error(f"{vault} is not a vault", details=["run: sessionmemory init"])
+            raise typer.Exit(1)
+
+        pp.error(
+            f"{vault} is not an initialized vault",
+            details=[
+                "it holds files but no _system/vault.toml marker",
+                (
+                    "if this is an existing vault, a human can initialize it once by "
+                    "hand with: sessionmemory init --force"
+                ),
+            ],
+        )
+        raise typer.Exit(1)
+
+    return vault
+
+
+def fail(message: str, details: list[str] | None = None) -> NoReturn:
+    """Report a failure and exit non-zero.
+
+    Args:
+        message (str): The error line.
+        details (list[str] | None): Follow-up lines.
+
+    Raises:
+        Exit: Always, with code 1.
+    """
+    pp.error(message, details=details if details is not None else [])
+    raise typer.Exit(1)
+
+
+def report_malformed_registry(vault: Path, error: registry.RegistryError) -> NoReturn:
+    """Report a malformed registry.toml and exit non-zero.
+
+    Args:
+        vault (Path): The vault root.
+        error (registry.RegistryError): The error raised while loading the registry.
+
+    Raises:
+        Exit: Always, with code 1.
+    """
+    path = vault / SYSTEM_DIR / registry.REGISTRY_FILE
+    pp.error(f"{path} is malformed: {error}")
+    raise typer.Exit(1) from error
+
+
+def require_project(vault: Path, cwd: Path | None = None) -> str:
+    """Return the current project's slug, or exit with instructions.
+
+    Args:
+        vault (Path): The vault root.
+        cwd (Path | None): The directory to resolve, or None for the shell's.
+
+    Returns:
+        str: The resolved project slug.
+
+    Raises:
+        Exit: When the working directory is not a registered project.
+    """
+    try:
+        result = resolve_project(vault, (cwd if cwd is not None else Path.cwd()).resolve())
+    except registry.RegistryError as error:
+        report_malformed_registry(vault, error)
+
+    if not result.registered or result.slug is None:
+        pp.error(
+            "this directory is not a registered project",
+            details=["run: sessionmemory project --register"],
+        )
+        raise typer.Exit(1)
+    return result.slug

sessionmemory/commands/delete.py

@@ -0,0 +1,71 @@
+"""The `delete` command: remove pages and files from the vault permanently.
+
+No confirmation and no dry run. The vault is a git repository, so a regretted delete is
+recovered from history, and a page that is wrong or spent has no other end.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import build_embedder, emit_json, fail, require_vault
+from sessionmemory.lib import fieldindex, paths
+
+if TYPE_CHECKING:
+    from sessionmemory.lib.embed import Embedder
+
+PATHS = typer.Argument(..., help="Files to delete.")
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def _check_vault_boundary(targets: list[Path], vault: Path) -> None:
+    """Verify all targets are inside the vault; fail if any is outside."""
+    for target in targets:
+        resolved = target.resolve()
+        if not resolved.is_relative_to(vault):
+            fail(f"{target} is outside the vault", ["nothing was deleted"])
+
+
+def _delete_targets(targets: list[Path]) -> list[dict[str, object]]:
+    """Delete each target and forget its index row if applicable."""
+    embedder: Embedder | None = None
+    records: list[dict[str, object]] = []
+    for target in targets:
+        # Unlink the path as given, not its resolved target, so deleting a
+        # symlink removes the link rather than the page it points at.
+        absolute = target if target.is_absolute() else Path.cwd() / target
+        deleted = absolute.is_file()
+        if deleted:
+            absolute.unlink()
+            if absolute.parent.name in paths.FIELD_DIRS:
+                embedder = embedder or build_embedder()
+                fieldindex.forget(absolute.parent, embedder, absolute.name)
+        records.append({"path": str(target), "deleted": deleted})
+    return records
+
+
+def delete_command(targets: list[Path] = PATHS, *, as_json: bool = JSON) -> None:
+    """Delete files from the vault, dropping a page's index row with it.
+
+    Raises:
+        Exit: With code 1 when a path is outside the vault or does not exist.
+    """
+    vault = require_vault()
+    _check_vault_boundary(targets, vault)
+    records = _delete_targets(targets)
+
+    missing = [record["path"] for record in records if not record["deleted"]]
+    if as_json:
+        emit_json(records)
+    else:
+        for record in records:
+            if record["deleted"]:
+                pp.success(f"deleted {record['path']}")
+    if missing:
+        if as_json:
+            raise typer.Exit(1)
+        fail(f"not found: {', '.join(str(path) for path in missing)}")

sessionmemory/commands/doctor.py

@@ -0,0 +1,30 @@
+"""The `doctor` command: report what is off, never fail over it."""
+
+from __future__ import annotations
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import build_embedder, emit_json, require_vault
+from sessionmemory.lib import doctor
+
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def doctor_command(*, as_json: bool = JSON) -> None:
+    """Report pages, projects, and indexes worth a look. Always exits 0."""
+    vault = require_vault()
+    findings = doctor.run(vault, build_embedder())
+    if as_json:
+        emit_json([{"check": f.check, "path": f.path, "message": f.message} for f in findings])
+        return
+    if not findings:
+        pp.success("nothing to report")
+        return
+    pp.info(
+        f"{len(findings)} suggestion{'s' if len(findings) != 1 else ''}",
+        details=[
+            f"{f.check}: {f.path}: {f.message}" if f.path else f"{f.check}: {f.message}"
+            for f in findings
+        ],
+    )

sessionmemory/commands/export.py

@@ -0,0 +1,61 @@
+"""The `export` command: write a project's field as a .memoryfield.zip."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import (
+    build_embedder,
+    emit_json,
+    fail,
+    require_project,
+    require_vault,
+)
+from sessionmemory.lib import export, field, paths
+
+CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
+LOGS = typer.Option(False, "--logs", help="Export the logs field instead of learnings.")  # noqa: FBT003
+OUTPUT = typer.Option(
+    None,
+    "--output",
+    help="Where to write the zip. Defaults to <slug>.memoryfield.zip in the current directory.",
+)
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def export_command(
+    cwd: Path | None = CWD,
+    *,
+    logs: bool = LOGS,
+    output: Path | None = OUTPUT,
+    as_json: bool = JSON,
+) -> None:
+    """Write this project's field as a .memoryfield.zip."""
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    embedder = build_embedder()
+
+    field_directory = paths.logs_dir(vault, slug) if logs else paths.learnings_dir(vault, slug)
+
+    if output is None:
+        suffix = "-logs.memoryfield.zip" if logs else ".memoryfield.zip"
+        output = Path.cwd() / f"{slug}{suffix}"
+
+    if not as_json and not field_directory.is_dir():
+        pp.warning(f"{field_directory} does not exist; the archive holds no pages")
+
+    try:
+        result = export.export_field(field_directory, embedder, output)
+    except OSError as error:
+        fail(f"cannot write {output}: {error}")
+    pages = len(field.iter_pages(field_directory))
+
+    if as_json:
+        emit_json({"path": str(result), "pages": pages})
+        return
+
+    label = "page" if pages == 1 else "pages"
+    pp.success(f"exported {pages} {label}", details=[str(result)])

sessionmemory/commands/init.py

@@ -0,0 +1,88 @@
+"""The `init` command that creates a new vault."""
+
+from __future__ import annotations
+
+# Typer resolves annotations from the module's globals to build its CLI, so this
+# cannot move into a TYPE_CHECKING block.
+from pathlib import Path  # noqa: TC003
+
+import typer
+from nclutils import pp
+
+from sessionmemory.commands._common import emit_json
+from sessionmemory.lib.bootstrap import InitResult, NotAVaultError, initialize
+from sessionmemory.lib.config import VaultNotConfiguredError, vault_root
+
+DIRECTORY_ARGUMENT = typer.Argument(
+    None, help="Where to create the vault. Defaults to SESSIONMEMORY_VAULT."
+)
+FORCE_OPTION = typer.Option(
+    False,  # noqa: FBT003
+    "--force",
+    help="Initialize a directory that already has contents. Nothing existing is overwritten.",
+)
+JSON_OPTION = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def _report(result: InitResult, *, as_json: bool) -> None:
+    """Report what initialization did.
+
+    Args:
+        result (InitResult): What `bootstrap.initialize` created and found already there.
+        as_json (bool): Emit a machine readable payload instead of prose.
+    """
+    if as_json:
+        emit_json(
+            {
+                "vault": str(result.vault),
+                "created": list(result.created),
+                "existed": list(result.existed),
+            }
+        )
+        return
+
+    if result.created:
+        pp.success(f"initialized {result.vault}", details=list(result.created))
+    else:
+        pp.info(f"{result.vault} is already initialized; nothing to create")
+
+    if result.existed:
+        pp.info(f"already present: {', '.join(result.existed)}")
+
+
+def init(
+    directory: Path | None = DIRECTORY_ARGUMENT,
+    *,
+    force: bool = FORCE_OPTION,
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Create the files a new vault needs.
+
+    A vault cannot be created through `require_vault`, since that helper refuses an
+    uninitialized directory and this command is what fixes that. When no directory is
+    given, `SESSIONMEMORY_VAULT` is read directly instead.
+
+    Raises:
+        Exit: When no directory is given and the environment variable is unset or names
+            a missing directory, or when the target directory holds unrelated files and
+            `--force` is not given.
+    """
+    if directory is not None:
+        # Every other reader resolves the vault path, so a relative or symlinked path
+        # recorded verbatim names a different directory than the one this created.
+        vault = directory.expanduser().resolve()
+        vault.mkdir(parents=True, exist_ok=True)
+    else:
+        try:
+            vault = vault_root()
+        except VaultNotConfiguredError as error:
+            pp.error(str(error), details=["export SESSIONMEMORY_VAULT=/path/to/your/vault"])
+            raise typer.Exit(1) from error
+
+    try:
+        result = initialize(vault, force=force)
+    except NotAVaultError as error:
+        pp.error(str(error))
+        raise typer.Exit(1) from error
+
+    _report(result, as_json=as_json)

sessionmemory/commands/inject.py

@@ -0,0 +1,25 @@
+"""The `inject` command: what a project's session should start with."""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003
+
+import typer
+
+from sessionmemory.commands._common import emit_json, emit_value, require_project, require_vault
+from sessionmemory.lib import inject
+
+CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
+COMMAND = typer.Option("sessionmemory", "--command", help="How the guidance names this CLI.")
+JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+
+
+def inject_command(cwd: Path | None = CWD, command: str = COMMAND, *, as_json: bool = JSON) -> None:
+    """Print what this project's session should start with."""
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    injection = inject.build(vault, slug)
+    if as_json:
+        emit_json(inject.payload(injection, command=command))
+        return
+    emit_value(inject.render(injection, command=command))

sessionmemory/commands/log.py

@@ -0,0 +1,64 @@
+"""The `log` command: record this session's work in one upserted page."""
+
+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, log
+from sessionmemory.lib.config import now, today
+
+SESSION_ID = typer.Option(..., "--session-id", help="This session's identifier.")
+TITLE = typer.Option(..., "--title", help="The log's title.")
+SUMMARY = typer.Option("", "--summary", help="One sentence a search result shows.")
+BODY = typer.Option("", "--body", help="Markdown body. Replaces what is there.")
+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 log_command(
+    session_id: str = SESSION_ID,
+    title: str = TITLE,
+    summary: str = SUMMARY,
+    body: str = BODY,
+    body_file: Path | None = BODY_FILE,
+    cwd: Path | None = CWD,
+    *,
+    as_json: bool = JSON,
+) -> None:
+    """Record this session's work in the one page that belongs to it.
+
+    Raises:
+        Exit: When the directory is not a registered project or the page cannot be written.
+    """
+    body = resolve_body(body, body_file)
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    try:
+        result = log.upsert_log(
+            vault,
+            slug=slug,
+            session_id=session_id,
+            title=title,
+            summary=summary,
+            body=body,
+            now=now(),
+            today=today(),
+        )
+    except field.PageError as error:
+        fail(str(error))
+    action = "created" if result.created else "updated"
+    if as_json:
+        emit_json({"path": str(result.path), "action": action})
+        return
+    pp.success(f"{action} {result.path.name}", details=[str(result.path)])