keep-skill 0.2.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

keep/cli.py

@@ -9,6 +9,7 @@ Usage:
 
 import json
 import os
+import re
 import sys
 from pathlib import Path
 from typing import Optional
@@ -16,7 +17,12 @@ from typing import Optional
 import typer
 from typing_extensions import Annotated
 
-from .api import Keeper
+
+# Pattern for version identifier suffix: @V{N} where N is digits only
+VERSION_SUFFIX_PATTERN = re.compile(r'@V\{(\d+)\}$')
+
+from .api import Keeper, _text_content_id
+from .document_store import VersionInfo
 from .types import Item
 from .logging_config import configure_quiet_mode, enable_debug_mode
 
@@ -37,6 +43,7 @@ def _verbose_callback(value: bool):
 # Global state for CLI options
 _json_output = False
 _ids_output = False
+_full_output = False
 
 
 def _json_callback(value: bool):
@@ -57,23 +64,89 @@ def _get_ids_output() -> bool:
     return _ids_output
 
 
+def _full_callback(value: bool):
+    global _full_output
+    _full_output = value
+
+
+def _get_full_output() -> bool:
+    return _full_output
+
+
 app = typer.Typer(
     name="keep",
     help="Associative memory with semantic search.",
     no_args_is_help=False,
     invoke_without_command=True,
+    rich_markup_mode=None,
 )
 
 
-def _format_yaml_frontmatter(item: Item) -> str:
-    """Format item as YAML frontmatter with summary as content."""
+def _format_yaml_frontmatter(
+    item: Item,
+    version_nav: Optional[dict[str, list[VersionInfo]]] = None,
+    viewing_offset: Optional[int] = None,
+    similar_items: Optional[list[Item]] = None,
+) -> str:
+    """
+    Format item as YAML frontmatter with summary as content.
+
+    Args:
+        item: The item to format
+        version_nav: Optional version navigation info (prev/next lists)
+        viewing_offset: If viewing an old version, the offset (1=previous, 2=two ago)
+        similar_items: Optional list of similar items to display
+
+    Note: Offset computation (v1, v2, etc.) assumes version_nav lists
+    are ordered newest-first, matching list_versions() ordering.
+    Changing that ordering would break the vN = -V N correspondence.
+    """
     lines = ["---", f"id: {item.id}"]
+    if viewing_offset is not None:
+        lines.append(f"version: {viewing_offset}")
     if item.tags:
-        lines.append("tags:")
-        for k, v in sorted(item.tags.items()):
-            lines.append(f"  {k}: {v}")
+        tag_items = ", ".join(f"{k}: {v}" for k, v in sorted(item.tags.items()))
+        lines.append(f"tags: {{{tag_items}}}")
     if item.score is not None:
         lines.append(f"score: {item.score:.3f}")
+
+    # Add similar items if available
+    if similar_items:
+        lines.append("similar:")
+        for sim_item in similar_items:
+            score_str = f"({sim_item.score:.2f})" if sim_item.score else ""
+            lines.append(f"  - {sim_item.id} {score_str}")
+
+    # Add version navigation if available
+    if version_nav:
+        # Current offset (0 if viewing current)
+        current_offset = viewing_offset if viewing_offset is not None else 0
+
+        if version_nav.get("prev"):
+            lines.append("prev:")
+            for i, v in enumerate(version_nav["prev"]):
+                # Offset for this prev item: current_offset + i + 1
+                prev_offset = current_offset + i + 1
+                date_part = v.created_at[:10] if v.created_at else "unknown"
+                summary_preview = v.summary[:40].replace("\n", " ")
+                if len(v.summary) > 40:
+                    summary_preview += "..."
+                lines.append(f"  - v{prev_offset}: {date_part} {summary_preview}")
+        if version_nav.get("next"):
+            lines.append("next:")
+            for i, v in enumerate(version_nav["next"]):
+                # Offset for this next item: current_offset - i - 1
+                next_offset = current_offset - i - 1
+                date_part = v.created_at[:10] if v.created_at else "unknown"
+                summary_preview = v.summary[:40].replace("\n", " ")
+                if len(v.summary) > 40:
+                    summary_preview += "..."
+                lines.append(f"  - v{next_offset}: {date_part} {summary_preview}")
+        elif viewing_offset is not None:
+            # Viewing old version and next is empty means current is next
+            lines.append("next:")
+            lines.append("  - v0 (current)")
+
     lines.append("---")
     lines.append(item.summary)  # Summary IS the content
     return "\n".join(lines)
@@ -100,15 +173,27 @@ def main_callback(
         callback=_ids_callback,
         is_eager=True,
     )] = False,
+    full_output: Annotated[bool, typer.Option(
+        "--full", "-F",
+        help="Output full items (overrides --ids)",
+        callback=_full_callback,
+        is_eager=True,
+    )] = False,
 ):
     """Associative memory with semantic search."""
     # If no subcommand provided, show the current context (now)
     if ctx.invoked_subcommand is None:
+        from .api import NOWDOC_ID
         kp = _get_keeper(None, "default")
         item = kp.get_now()
-        typer.echo(_format_item(item, as_json=_get_json_output()))
-        if not _get_json_output():
-            typer.echo("\nUse --help for commands.", err=True)
+        version_nav = kp.get_version_nav(NOWDOC_ID, None, collection="default")
+        similar_items = kp.get_similar_for_display(NOWDOC_ID, limit=3, collection="default")
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+            similar_items=similar_items,
+        ))
 
 
 # -----------------------------------------------------------------------------
@@ -154,25 +239,72 @@ SinceOption = Annotated[
 # Output Helpers
 # -----------------------------------------------------------------------------
 
-def _format_item(item: Item, as_json: bool = False) -> str:
+def _format_item(
+    item: Item,
+    as_json: bool = False,
+    version_nav: Optional[dict[str, list[VersionInfo]]] = None,
+    viewing_offset: Optional[int] = None,
+    similar_items: Optional[list[Item]] = None,
+) -> str:
     """
     Format an item for display.
 
     Text format: YAML frontmatter (matches docs/system format)
     With --ids: just the ID (for piping)
+
+    Args:
+        item: The item to format
+        as_json: Output as JSON
+        version_nav: Optional version navigation info (prev/next lists)
+        viewing_offset: If viewing an old version, the offset (1=previous, 2=two ago)
+        similar_items: Optional list of similar items to display
     """
     if _get_ids_output():
         return json.dumps(item.id) if as_json else item.id
 
     if as_json:
-        return json.dumps({
+        result = {
             "id": item.id,
             "summary": item.summary,
             "tags": item.tags,
             "score": item.score,
-        })
-
-    return _format_yaml_frontmatter(item)
+        }
+        if viewing_offset is not None:
+            result["version"] = viewing_offset
+            result["vid"] = f"{item.id}@V{{{viewing_offset}}}"
+        if similar_items:
+            result["similar"] = [
+                {"id": s.id, "score": s.score, "summary": s.summary[:60]}
+                for s in similar_items
+            ]
+        if version_nav:
+            current_offset = viewing_offset if viewing_offset is not None else 0
+            result["version_nav"] = {}
+            if version_nav.get("prev"):
+                result["version_nav"]["prev"] = [
+                    {
+                        "offset": current_offset + i + 1,
+                        "vid": f"{item.id}@V{{{current_offset + i + 1}}}",
+                        "created_at": v.created_at,
+                        "summary": v.summary[:60],
+                    }
+                    for i, v in enumerate(version_nav["prev"])
+                ]
+            if version_nav.get("next"):
+                result["version_nav"]["next"] = [
+                    {
+                        "offset": current_offset - i - 1,
+                        "vid": f"{item.id}@V{{{current_offset - i - 1}}}",
+                        "created_at": v.created_at,
+                        "summary": v.summary[:60],
+                    }
+                    for i, v in enumerate(version_nav["next"])
+                ]
+            elif viewing_offset is not None:
+                result["version_nav"]["next"] = [{"offset": 0, "vid": f"{item.id}@V{{0}}", "label": "current"}]
+        return json.dumps(result)
+
+    return _format_yaml_frontmatter(item, version_nav, viewing_offset, similar_items)
 
 
 def _format_items(items: list[Item], as_json: bool = False) -> str:
@@ -299,6 +431,36 @@ def search(
     typer.echo(_format_items(results, as_json=_get_json_output()))
 
 
+@app.command("list")
+def list_recent(
+    store: StoreOption = None,
+    collection: CollectionOption = "default",
+    limit: Annotated[int, typer.Option(
+        "--limit", "-n",
+        help="Number of items to show"
+    )] = 10,
+):
+    """
+    List recent items by update time.
+
+    Shows IDs by default (composable). Use --full for detailed output.
+    """
+    kp = _get_keeper(store, collection)
+    results = kp.list_recent(limit=limit)
+
+    # Determine output mode: --full > --ids > command default (IDs for list)
+    if _get_json_output():
+        # JSON always outputs full items
+        typer.echo(_format_items(results, as_json=True))
+    elif _get_full_output():
+        # --full flag: full YAML output
+        typer.echo(_format_items(results, as_json=False))
+    else:
+        # Default for list: IDs only (composable)
+        for item in results:
+            typer.echo(item.id)
+
+
 @app.command()
 def tag(
     query: Annotated[Optional[str], typer.Argument(
@@ -446,9 +608,14 @@ def update(
 
     Three input modes (auto-detected):
       keep update file:///path       # URI mode: has ://
-      keep update "my note"          # Text mode: no ://
+      keep update "my note"          # Text mode: content-addressed ID
       keep update -                  # Stdin mode: explicit -
       echo "pipe" | keep update      # Stdin mode: piped input
+
+    Text mode uses content-addressed IDs for versioning:
+      keep update "my note"           # Creates _text:{hash}
+      keep update "my note" -t done   # Same ID, new version (tag change)
+      keep update "different note"    # Different ID (new doc)
     """
     kp = _get_keeper(store, collection)
     parsed_tags = _parse_tags(tags)
@@ -459,14 +626,16 @@ def update(
         content = sys.stdin.read()
         content, frontmatter_tags = _parse_frontmatter(content)
         parsed_tags = {**frontmatter_tags, **parsed_tags}  # CLI tags override
-        doc_id = id or f"mem:{_timestamp()}"
+        # Use content-addressed ID for stdin text (enables versioning)
+        doc_id = id or _text_content_id(content)
         item = kp.remember(content, id=doc_id, summary=summary, tags=parsed_tags or None, lazy=lazy)
     elif source and "://" in source:
         # URI mode: fetch from URI (ID is the URI itself)
         item = kp.update(source, tags=parsed_tags or None, summary=summary, lazy=lazy)
     elif source:
         # Text mode: inline content (no :// in source)
-        doc_id = id or f"mem:{_timestamp()}"
+        # Use content-addressed ID for text (enables versioning)
+        doc_id = id or _text_content_id(source)
         item = kp.remember(source, id=doc_id, summary=summary, tags=parsed_tags or None, lazy=lazy)
     else:
         typer.echo("Error: Provide content, URI, or '-' for stdin", err=True)
@@ -488,6 +657,14 @@ def now(
         "--reset",
         help="Reset to default from system"
     )] = False,
+    version: Annotated[Optional[int], typer.Option(
+        "--version", "-V",
+        help="Get specific version (0=current, 1=previous, etc.)"
+    )] = None,
+    history: Annotated[bool, typer.Option(
+        "--history", "-H",
+        help="List all versions"
+    )] = False,
     store: StoreOption = None,
     collection: CollectionOption = "default",
     tags: Annotated[Optional[list[str]], typer.Option(
@@ -503,19 +680,100 @@ def now(
 
     Examples:
         keep now                         # Show current context
-        keep now "Working on auth flow"  # Set context
-        keep now -f context.md           # Set from file
-        keep now --reset                 # Reset to default
+        keep now "What's important now"  # Update context
+        keep now -f context.md           # Read content from file
+        keep now --reset                 # Reset to default from system
+        keep now -V 1                    # Previous version
+        keep now --history               # List all versions
     """
+    from .api import NOWDOC_ID
+
     kp = _get_keeper(store, collection)
 
+    # Handle history listing
+    if history:
+        versions = kp.list_versions(NOWDOC_ID, limit=50, collection=collection)
+        current = kp.get(NOWDOC_ID, collection=collection)
+
+        if _get_ids_output():
+            # Output version identifiers, one per line
+            if current:
+                typer.echo(f"{NOWDOC_ID}@V{{0}}")
+            for i in range(1, len(versions) + 1):
+                typer.echo(f"{NOWDOC_ID}@V{{{i}}}")
+        elif _get_json_output():
+            result = {
+                "id": NOWDOC_ID,
+                "current": {
+                    "summary": current.summary if current else None,
+                    "offset": 0,
+                    "vid": f"{NOWDOC_ID}@V{{0}}",
+                } if current else None,
+                "versions": [
+                    {
+                        "offset": i + 1,
+                        "vid": f"{NOWDOC_ID}@V{{{i + 1}}}",
+                        "version": v.version,
+                        "summary": v.summary[:60],
+                        "created_at": v.created_at,
+                    }
+                    for i, v in enumerate(versions)
+                ],
+            }
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            if current:
+                summary_preview = current.summary[:60].replace("\n", " ")
+                if len(current.summary) > 60:
+                    summary_preview += "..."
+                typer.echo(f"v0 (current): {summary_preview}")
+            if versions:
+                typer.echo(f"\nArchived:")
+                for i, v in enumerate(versions, start=1):
+                    date_part = v.created_at[:10] if v.created_at else "unknown"
+                    summary_preview = v.summary[:50].replace("\n", " ")
+                    if len(v.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  v{i} ({date_part}): {summary_preview}")
+            else:
+                typer.echo("No version history.")
+        return
+
+    # Handle version retrieval
+    if version is not None:
+        offset = version
+        if offset == 0:
+            item = kp.get_now()
+            internal_version = None
+        else:
+            item = kp.get_version(NOWDOC_ID, offset, collection=collection)
+            # Get internal version number for API call
+            versions = kp.list_versions(NOWDOC_ID, limit=1, collection=collection)
+            if versions:
+                internal_version = versions[0].version - (offset - 1)
+            else:
+                internal_version = None
+
+        if item is None:
+            typer.echo(f"Version not found (offset {offset})", err=True)
+            raise typer.Exit(1)
+
+        version_nav = kp.get_version_nav(NOWDOC_ID, internal_version, collection=collection)
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+            viewing_offset=offset if offset > 0 else None,
+        ))
+        return
+
     # Determine if we're getting or setting
     setting = content is not None or file is not None or reset
 
     if setting:
         if reset:
             # Reset to default from system (delete first to clear old tags)
-            from .api import _load_frontmatter, NOWDOC_ID, SYSTEM_DOC_DIR
+            from .api import _load_frontmatter, SYSTEM_DOC_DIR
             kp.delete(NOWDOC_ID)
             try:
                 new_content, default_tags = _load_frontmatter(SYSTEM_DOC_DIR / "now.md")
@@ -545,48 +803,199 @@ def now(
         item = kp.set_now(new_content, tags=parsed_tags or None)
         typer.echo(_format_item(item, as_json=_get_json_output()))
     else:
-        # Get current context
+        # Get current context with version navigation and similar items
         item = kp.get_now()
-        typer.echo(_format_item(item, as_json=_get_json_output()))
+        version_nav = kp.get_version_nav(NOWDOC_ID, None, collection=collection)
+        similar_items = kp.get_similar_for_display(NOWDOC_ID, limit=3, collection=collection)
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+            similar_items=similar_items,
+        ))
 
 
 @app.command()
 def get(
-    id: Annotated[str, typer.Argument(help="URI of item to retrieve")],
+    id: Annotated[str, typer.Argument(help="URI of item (append @V{N} for version)")],
+    version: Annotated[Optional[int], typer.Option(
+        "--version", "-V",
+        help="Get specific version (0=current, 1=previous, etc.)"
+    )] = None,
+    history: Annotated[bool, typer.Option(
+        "--history", "-H",
+        help="List all versions"
+    )] = False,
+    similar: Annotated[bool, typer.Option(
+        "--similar", "-S",
+        help="List similar items"
+    )] = False,
+    no_similar: Annotated[bool, typer.Option(
+        "--no-similar",
+        help="Suppress similar items in output"
+    )] = False,
+    limit: Annotated[int, typer.Option(
+        "--limit", "-n",
+        help="Max items for --history or --similar (default: 10)"
+    )] = 10,
     store: StoreOption = None,
     collection: CollectionOption = "default",
 ):
     """
     Retrieve a specific item by ID.
+
+    Version identifiers: Append @V{N} to get a specific version.
+
+    Examples:
+        keep get doc:1                  # Current version with similar items
+        keep get doc:1 -V 1             # Previous version with prev/next nav
+        keep get "doc:1@V{1}"           # Same as -V 1
+        keep get doc:1 --history        # List all versions
+        keep get doc:1 --similar        # List similar items
+        keep get doc:1 --no-similar     # Suppress similar items
     """
     kp = _get_keeper(store, collection)
-    item = kp.get(id)
 
-    if item is None:
-        typer.echo(f"Not found: {id}", err=True)
-        raise typer.Exit(1)
+    # Parse @V{N} version identifier from ID (security: check literal first)
+    actual_id = id
+    version_from_id = None
 
-    typer.echo(_format_item(item, as_json=_get_json_output()))
+    if kp.exists(id, collection=collection):
+        # Literal ID exists - use it directly (prevents confusion attacks)
+        actual_id = id
+    else:
+        # Try parsing @V{N} suffix
+        match = VERSION_SUFFIX_PATTERN.search(id)
+        if match:
+            version_from_id = int(match.group(1))
+            actual_id = id[:match.start()]
+
+    # Version from ID only applies if --version not explicitly provided
+    if version is None and version_from_id is not None:
+        version = version_from_id
+
+    if history:
+        # List all versions
+        versions = kp.list_versions(actual_id, limit=limit, collection=collection)
+        current = kp.get(actual_id, collection=collection)
+
+        if _get_ids_output():
+            # Output version identifiers, one per line
+            if current:
+                typer.echo(f"{actual_id}@V{{0}}")
+            for i in range(1, len(versions) + 1):
+                typer.echo(f"{actual_id}@V{{{i}}}")
+        elif _get_json_output():
+            result = {
+                "id": actual_id,
+                "current": {
+                    "summary": current.summary if current else None,
+                    "tags": current.tags if current else {},
+                    "offset": 0,
+                    "vid": f"{actual_id}@V{{0}}",
+                } if current else None,
+                "versions": [
+                    {
+                        "offset": i + 1,
+                        "vid": f"{actual_id}@V{{{i + 1}}}",
+                        "version": v.version,
+                        "summary": v.summary,
+                        "created_at": v.created_at,
+                    }
+                    for i, v in enumerate(versions)
+                ],
+            }
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            if current:
+                summary_preview = current.summary[:60].replace("\n", " ")
+                if len(current.summary) > 60:
+                    summary_preview += "..."
+                typer.echo(f"v0 (current): {summary_preview}")
+            if versions:
+                typer.echo(f"\nArchived:")
+                for i, v in enumerate(versions, start=1):
+                    date_part = v.created_at[:10] if v.created_at else "unknown"
+                    summary_preview = v.summary[:50].replace("\n", " ")
+                    if len(v.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  v{i} ({date_part}): {summary_preview}")
+            else:
+                typer.echo("No version history.")
+        return
 
+    if similar:
+        # List similar items
+        similar_items = kp.get_similar_for_display(actual_id, limit=limit, collection=collection)
+
+        if _get_ids_output():
+            # Output IDs one per line
+            for item in similar_items:
+                typer.echo(item.id)
+        elif _get_json_output():
+            result = {
+                "id": actual_id,
+                "similar": [
+                    {
+                        "id": item.id,
+                        "score": item.score,
+                        "summary": item.summary[:60],
+                    }
+                    for item in similar_items
+                ],
+            }
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            typer.echo(f"Similar to {actual_id}:")
+            if similar_items:
+                for item in similar_items:
+                    score_str = f"({item.score:.2f})" if item.score else ""
+                    summary_preview = item.summary[:50].replace("\n", " ")
+                    if len(item.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  {item.id} {score_str} {summary_preview}")
+            else:
+                typer.echo("  No similar items found.")
+        return
 
-@app.command()
-def exists(
-    id: Annotated[str, typer.Argument(help="URI to check")],
-    store: StoreOption = None,
-    collection: CollectionOption = "default",
-):
-    """
-    Check if an item exists in the store.
-    """
-    kp = _get_keeper(store, collection)
-    found = kp.exists(id)
-    
-    if found:
-        typer.echo(f"Exists: {id}")
+    # Get specific version or current
+    offset = version if version is not None else 0
+
+    if offset == 0:
+        item = kp.get(actual_id, collection=collection)
+        internal_version = None
     else:
-        typer.echo(f"Not found: {id}")
+        item = kp.get_version(actual_id, offset, collection=collection)
+        # Calculate internal version number for API call
+        versions = kp.list_versions(actual_id, limit=1, collection=collection)
+        if versions:
+            internal_version = versions[0].version - (offset - 1)
+        else:
+            internal_version = None
+
+    if item is None:
+        if offset > 0:
+            typer.echo(f"Version not found: {actual_id} (offset {offset})", err=True)
+        else:
+            typer.echo(f"Not found: {actual_id}", err=True)
         raise typer.Exit(1)
 
+    # Get version navigation
+    version_nav = kp.get_version_nav(actual_id, internal_version, collection=collection)
+
+    # Get similar items (unless suppressed or viewing old version)
+    similar_items = None
+    if not no_similar and offset == 0:
+        similar_items = kp.get_similar_for_display(actual_id, limit=3, collection=collection)
+
+    typer.echo(_format_item(
+        item,
+        as_json=_get_json_output(),
+        version_nav=version_nav,
+        viewing_offset=offset if offset > 0 else None,
+        similar_items=similar_items,
+    ))
+
 
 @app.command("collections")
 def list_collections(
@@ -675,45 +1084,6 @@ def config(
             typer.echo(f"  Summarization: {cfg.summarization.name}")
 
 
-@app.command("system")
-def list_system(
-    store: StoreOption = None,
-):
-    """
-    List the system documents.
-
-    Shows ID and summary for each. Use `keep get ID` for full details.
-    """
-    kp = _get_keeper(store, "default")
-    docs = kp.list_system_documents()
-
-    # Use --ids flag for pipe-friendly output
-    if _get_ids_output():
-        ids = [doc.id for doc in docs]
-        if _get_json_output():
-            typer.echo(json.dumps(ids))
-        else:
-            for doc_id in ids:
-                typer.echo(doc_id)
-        return
-
-    if _get_json_output():
-        typer.echo(json.dumps([
-            {"id": doc.id, "summary": doc.summary}
-            for doc in docs
-        ], indent=2))
-    else:
-        if not docs:
-            typer.echo("No system documents.")
-        else:
-            for doc in docs:
-                # Compact summary: collapse whitespace, truncate to 70 chars
-                summary = " ".join(doc.summary.split())[:70]
-                if len(doc.summary) > 70:
-                    summary += "..."
-                typer.echo(f"{doc.id}: {summary}")
-
-
 @app.command("process-pending")
 def process_pending(
     store: StoreOption = None,