session-glue 0.1.0__py3-none-any.whl

session_glue/__init__.py

@@ -0,0 +1,11 @@
+"""Session Glue.
+
+A zero-daemon, repo-local session-continuity protocol and CLI for coding agents.
+
+Cut a bloated coding-agent session at a clean boundary, then glue the useful
+context onto the next session.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

session_glue/__main__.py

@@ -0,0 +1,8 @@
+"""Support ``python -m session_glue``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

session_glue/cli.py

@@ -0,0 +1,275 @@
+"""Command-line entry point for Session Glue.
+
+This module wires up the ``glue`` (and fallback ``session-glue``) console
+scripts. It implements ``glue create``, ``glue validate``, ``glue status``,
+``glue resume-prompt``, and ``glue install --dry-run`` (see
+:mod:`session_glue.writer`, :mod:`session_glue.validator`,
+:mod:`session_glue.reader`, and :mod:`session_glue.installer`). The CLI is built
+on :mod:`argparse` from the standard library so the package has no required
+runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__, installer, reader, validator, writer
+from .schema import Handoff, HandoffParseError, parse_frontmatter
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level argument parser for the ``glue`` CLI."""
+    parser = argparse.ArgumentParser(
+        prog="glue",
+        description=(
+            "Session Glue — cut a bloated coding-agent session at a clean "
+            "boundary and glue the useful context onto a clean new session."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"session-glue {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    create = subparsers.add_parser(
+        "create",
+        help="Archive a handoff into .agent-history/ and update pointers.",
+        description=(
+            "Write an agent-composed handoff (frontmatter + body) into "
+            ".agent-history/: archive a timestamped session file, refresh "
+            "LATEST.md, RESUME_PROMPT.txt, and INDEX.yaml."
+        ),
+    )
+    create.add_argument(
+        "--input",
+        "-i",
+        default="-",
+        metavar="PATH",
+        help="Handoff markdown file (frontmatter + body). Use '-' for stdin (default).",
+    )
+    create.add_argument(
+        "--repo-root",
+        default=".",
+        metavar="PATH",
+        help="Repository root that holds .agent-history/ (default: current directory).",
+    )
+    create.set_defaults(func=_cmd_create)
+
+    validate = subparsers.add_parser(
+        "validate",
+        help="Validate .agent-history/ handoff artifacts.",
+        description=(
+            "Validate LATEST.md frontmatter, the next_todo_items[0] lint, "
+            "RESUME_PROMPT.txt presence, and INDEX.yaml consistency. Exits "
+            "non-zero if any problem is found."
+        ),
+    )
+    validate.add_argument(
+        "--repo-root",
+        default=".",
+        metavar="PATH",
+        help="Repository root that holds .agent-history/ (default: current directory).",
+    )
+    validate.add_argument(
+        "--sessions",
+        action="store_true",
+        help="Also validate archived session files under sessions/.",
+    )
+    validate.set_defaults(func=_cmd_validate)
+
+    status = subparsers.add_parser(
+        "status",
+        help="Show compact .agent-history/ status.",
+        description=(
+            "Print compact metadata from INDEX.yaml (latest session/file, "
+            "branch, head commit, first next action) and a cheap validation "
+            "summary. Does not print the full session narrative."
+        ),
+    )
+    status.add_argument(
+        "--repo-root",
+        default=".",
+        metavar="PATH",
+        help="Repository root that holds .agent-history/ (default: current directory).",
+    )
+    status.set_defaults(func=_cmd_status)
+
+    resume_prompt = subparsers.add_parser(
+        "resume-prompt",
+        help="Print .agent-history/RESUME_PROMPT.txt exactly.",
+        description="Print the exact contents of .agent-history/RESUME_PROMPT.txt.",
+    )
+    resume_prompt.add_argument(
+        "--repo-root",
+        default=".",
+        metavar="PATH",
+        help="Repository root that holds .agent-history/ (default: current directory).",
+    )
+    resume_prompt.set_defaults(func=_cmd_resume_prompt)
+
+    install = subparsers.add_parser(
+        "install",
+        help="Show the managed instruction block for a coding agent (dry-run only).",
+        description=(
+            "Dry-run only: print the target instruction file and the managed "
+            "Session Glue block that would be added for a coding agent. Never "
+            "modifies user-home files; real installation is not implemented "
+            "(operator-gated)."
+        ),
+    )
+    install.add_argument(
+        "agent",
+        choices=(*installer.AGENT_ORDER, "all"),
+        help="Coding agent to show the install block for (or 'all').",
+    )
+    install.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Required: print the target path and proposed block without writing.",
+    )
+    install.set_defaults(func=_cmd_install)
+
+    return parser
+
+
+def _read_input(source: str) -> str:
+    """Read handoff text from a file path or stdin (``-``)."""
+    if source == "-":
+        return sys.stdin.read()
+    return Path(source).read_text(encoding="utf-8")
+
+
+def _cmd_create(args: argparse.Namespace) -> int:
+    """Implement ``glue create``."""
+    try:
+        text = _read_input(args.input)
+    except OSError as exc:
+        print(f"glue create: cannot read input: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        frontmatter, body = parse_frontmatter(text)
+    except HandoffParseError as exc:
+        print(f"glue create: invalid handoff: {exc}", file=sys.stderr)
+        return 2
+
+    handoff = Handoff.from_frontmatter(frontmatter, body)
+    errors = handoff.validate()
+    if errors:
+        print("glue create: handoff failed validation:", file=sys.stderr)
+        for error in errors:
+            print(f"  - {error}", file=sys.stderr)
+        return 2
+
+    repo_root = Path(args.repo_root)
+    if not repo_root.is_dir():
+        print(f"glue create: repo root is not a directory: {repo_root}", file=sys.stderr)
+        return 1
+
+    try:
+        written = writer.create_handoff(
+            repo_root=repo_root,
+            frontmatter=frontmatter,
+            body=body,
+            handoff=handoff,
+        )
+    except writer.HandoffWriteError as exc:
+        print(f"glue create: {exc}", file=sys.stderr)
+        return 1
+    print("Wrote handoff for session " + str(handoff.session_id) + ":")
+    for label in ("archive", "latest", "resume_prompt", "index"):
+        print(f"  {label}: {written[label]}")
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    """Implement ``glue validate``."""
+    problems = validator.validate_history(
+        Path(args.repo_root), check_sessions=args.sessions
+    )
+    if problems:
+        print("glue validate: found problems:", file=sys.stderr)
+        for problem in problems:
+            print(f"  - {problem}", file=sys.stderr)
+        return 1
+    print("glue validate: OK")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    """Implement ``glue status``."""
+    status = reader.collect_status(Path(args.repo_root))
+    if not status.exists:
+        print(f"glue status: no .agent-history/ found at {status.history_dir}")
+        return 1
+
+    print(".agent-history: present")
+    index = status.index or {}
+    for label, key in reader.STATUS_FIELDS:
+        value = index.get(key)
+        print(f"{label}: {value if value not in (None, '') else '(unknown)'}")
+
+    if status.problems:
+        print(f"validation: {len(status.problems)} problem(s)")
+        for problem in status.problems:
+            print(f"  - {problem}")
+    else:
+        print("validation: OK")
+    return 0
+
+
+def _cmd_resume_prompt(args: argparse.Namespace) -> int:
+    """Implement ``glue resume-prompt``."""
+    text = reader.read_resume_prompt(Path(args.repo_root))
+    if text is None:
+        print("glue resume-prompt: no .agent-history/RESUME_PROMPT.txt found", file=sys.stderr)
+        return 1
+    # Print the file contents exactly (no added or stripped trailing newline).
+    sys.stdout.write(text)
+    return 0
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    """Implement ``glue install <agent> --dry-run`` (dry-run only)."""
+    if not args.dry_run:
+        print(
+            "glue install: only --dry-run is supported; real installation is "
+            "operator-gated and not implemented. Re-run with --dry-run.",
+            file=sys.stderr,
+        )
+        return 2
+
+    block = installer.managed_block()
+    for target in installer.resolve_agents(args.agent):
+        print(f"# {target.name} (dry-run — no files modified)")
+        print(f"target: {target.target}")
+        if target.note:
+            print(f"note: {target.note}")
+        print("proposed block:")
+        print(block)
+        print()
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Program entry point. Returns the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    handler = getattr(args, "func", None)
+    if handler is None:
+        # No subcommand given: show help and exit successfully.
+        parser.print_help()
+        return 0
+
+    return handler(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

session_glue/installer.py

@@ -0,0 +1,92 @@
+"""Dry-run installer blocks for ``glue install <agent> --dry-run``.
+
+This module only *describes* what Session Glue would add to a coding agent's
+global instruction file — it renders the managed instruction block and the
+target path. It never mutates user-home files, accesses the network or OS
+clipboard, or performs a real install. Non-dry-run installation is intentionally
+not implemented here (operator-gated).
+
+The managed block is delimited by stable begin/end markers so a future updater
+can replace it idempotently, and so existing installs can be detected.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Stable managed-block markers. These are part of the on-disk contract: keep
+# them byte-for-byte stable so idempotent updates and detection keep working.
+BEGIN_MARKER = "<!-- BEGIN SESSION GLUE (managed) -->"
+END_MARKER = "<!-- END SESSION GLUE (managed) -->"
+
+# Agent-agnostic body of the managed block. Tells any file-writing coding agent
+# how to respond to the glue triggers while preserving the v1 constraints.
+_BLOCK_BODY = """\
+## Session Glue
+
+When the user runs `/glue`, `/freeze`, `/handoff`, or `/checkpoint`, or asks in
+natural language to glue / freeze / checkpoint / hand off the current session:
+
+1. Compose a handoff document: YAML frontmatter (session_id, session_date,
+   generated_at, schema_version, project_root, repo_root, current_branch,
+   head_commit, agent, status, active_context_files, completed_tasks,
+   next_todo_items, known_issues) plus a narrative body covering what changed,
+   what is still broken, and what to do next. `next_todo_items[0]` MUST be the
+   first productive work item, never a resume mechanic (do not write "read
+   LATEST.md", "paste the prompt", "start a new session", etc.).
+2. Run `glue create` to write the handoff into the repository-local
+   `.agent-history/` directory (LATEST.md, RESUME_PROMPT.txt, INDEX.yaml, and
+   sessions/<id>.md). Optionally run `glue validate` to check it.
+3. Print the contents of `.agent-history/RESUME_PROMPT.txt` in a fenced code
+   block so the operator can copy it into a fresh session.
+
+Constraints:
+- Write only the repository-local `.agent-history/` directory.
+- Do not access the OS clipboard.
+- Do not run a daemon, watcher, or any external/network service."""
+
+
+@dataclass(frozen=True)
+class AgentTarget:
+    """Where a given agent's global instruction block lives (display only)."""
+
+    name: str
+    target: str
+    note: str = ""
+
+
+# Target instruction files per agent. Paths are shown in ``~`` form and are
+# never opened or written during dry-run.
+AGENT_TARGETS: dict[str, AgentTarget] = {
+    "codex": AgentTarget("codex", "~/.codex/AGENTS.md"),
+    "claude": AgentTarget("claude", "~/.claude/commands/glue.md"),
+    "cursor": AgentTarget(
+        "cursor",
+        "~/.cursor/rules/session-glue.md",
+        note="or paste the block into Cursor Settings -> Rules for AI",
+    ),
+    "gemini": AgentTarget("gemini", "~/.gemini/GEMINI.md"),
+}
+
+# Order used when installing "all".
+AGENT_ORDER: tuple[str, ...] = ("codex", "claude", "cursor", "gemini")
+
+
+def managed_block() -> str:
+    """Return the full managed instruction block, including begin/end markers."""
+    return f"{BEGIN_MARKER}\n{_BLOCK_BODY}\n{END_MARKER}"
+
+
+def has_managed_block(text: str) -> bool:
+    """Return True if ``text`` already contains a Session Glue managed block."""
+    return BEGIN_MARKER in text and END_MARKER in text
+
+
+def resolve_agents(agent: str) -> list[AgentTarget]:
+    """Resolve an agent name (or ``all``) to a list of targets.
+
+    Raises ``KeyError`` for an unknown agent name.
+    """
+    if agent == "all":
+        return [AGENT_TARGETS[name] for name in AGENT_ORDER]
+    return [AGENT_TARGETS[agent]]

session_glue/reader.py

@@ -0,0 +1,69 @@
+"""Read-only helpers for ``glue status`` and ``glue resume-prompt``.
+
+These commands orient the operator without recreating context bloat: ``status``
+reports compact metadata from ``INDEX.yaml`` plus a cheap validation summary —
+it deliberately does **not** read or print the full session narrative — and
+``resume-prompt`` returns the exact contents of ``RESUME_PROMPT.txt``. Both are
+strictly read-only: no writes, no network, no subprocess.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .schema import HandoffParseError, parse_mapping
+from .validator import validate_history
+from .writer import AGENT_HISTORY_DIRNAME, INDEX_FILENAME, RESUME_PROMPT_FILENAME
+
+# Compact fields surfaced by ``glue status``, in display order, mapped from
+# their ``INDEX.yaml`` keys. The full ``next_todo_items`` narrative is never
+# included (token-economics requirement).
+STATUS_FIELDS: tuple[tuple[str, str], ...] = (
+    ("latest session", "latest_session"),
+    ("latest file", "latest_file"),
+    ("current branch", "current_branch"),
+    ("head commit", "head_commit"),
+    ("first next action", "first_next_action"),
+)
+
+
+@dataclass
+class Status:
+    """A compact, read-only snapshot of ``.agent-history/`` state."""
+
+    exists: bool
+    history_dir: Path
+    index: dict[str, Any] | None = None
+    problems: list[str] = field(default_factory=list)
+
+
+def collect_status(repo_root: Path, run_validation: bool = True) -> Status:
+    """Gather compact status for ``<repo_root>/.agent-history/``.
+
+    Reads only ``INDEX.yaml`` (plus a cheap, non-``--sessions`` validation pass
+    when ``run_validation`` is true). Never reads archived session narratives.
+    """
+    history = Path(repo_root) / AGENT_HISTORY_DIRNAME
+    if not history.is_dir():
+        return Status(exists=False, history_dir=history)
+
+    index: dict[str, Any] | None = None
+    index_path = history / INDEX_FILENAME
+    if index_path.is_file():
+        try:
+            index = parse_mapping(index_path.read_text(encoding="utf-8"))
+        except HandoffParseError:
+            index = None
+
+    problems = validate_history(repo_root) if run_validation else []
+    return Status(exists=True, history_dir=history, index=index, problems=problems)
+
+
+def read_resume_prompt(repo_root: Path) -> str | None:
+    """Return the exact contents of ``RESUME_PROMPT.txt``, or None if missing."""
+    path = Path(repo_root) / AGENT_HISTORY_DIRNAME / RESUME_PROMPT_FILENAME
+    if not path.is_file():
+        return None
+    return path.read_text(encoding="utf-8")