rm-contextos 0.1.0__py3-none-any.whl

contextos/__init__.py

@@ -0,0 +1,6 @@
+"""ContextOS — a context operating system for AI coding agents."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

contextos/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI package."""
+
+from __future__ import annotations

contextos/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command modules."""
+
+from __future__ import annotations

contextos/cli/commands/export.py

@@ -0,0 +1,270 @@
+"""export command — generate tool-specific context files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Protocol, cast
+
+import typer
+from rich.console import Console
+
+from contextos.core.context_selector import ContextSelection
+from contextos.exporters.base import ExportConfig
+
+app = typer.Typer(help="Export context packs for specific AI coding tools.")
+console = Console()
+
+_CONTEXTOS_DIR = ".contextos"
+
+
+# ---------------------------------------------------------------------------
+# Shared option types (re-declared in each sub-command for Typer compatibility)
+# ---------------------------------------------------------------------------
+
+_REPO_HELP = "Repository root (default: current directory)."
+_TASK_HELP = "Task description for relevance ranking."
+_BUDGET_HELP = "Token budget for context selection."
+_TESTS_HELP = "Include test files in context selection."
+_SOURCE_HELP = "Include only file summaries; never embed full source."
+_TIMESTAMP_HELP = "Omit timestamp for reproducible output."
+_OUT_HELP = "Also write output to this additional file path."
+_SENSITIVE_HELP = (
+    "[DANGEROUS] Disable secret redaction. Secrets will appear in plain text. "
+    "Only use in fully isolated, private environments."
+)
+
+
+class _ExporterModule(Protocol):
+    TOOL_NAME: str
+    FILENAME: str
+
+    def export(
+        self,
+        task: str,
+        repo_root: Path,
+        contextos_dir: Path,
+        *,
+        config: ExportConfig,
+    ) -> tuple[str, ContextSelection]: ...
+
+
+@app.callback()
+def export_root(ctx: typer.Context) -> None:  # noqa: ARG001
+    """Generate tool-specific context files from your repo and active task."""
+
+
+# ---------------------------------------------------------------------------
+# claude
+# ---------------------------------------------------------------------------
+
+
+@app.command("claude")
+def export_claude(
+    repo: Annotated[Path, typer.Option("--repo", "-r", help=_REPO_HELP)] = Path("."),
+    task: Annotated[str, typer.Option("--task", "-t", help=_TASK_HELP)] = ...,  # type: ignore[assignment]
+    budget: Annotated[int, typer.Option("--budget", "-b", help=_BUDGET_HELP)] = 8000,
+    include_tests: Annotated[
+        bool, typer.Option("--include-tests/--no-tests", help=_TESTS_HELP)
+    ] = True,
+    no_source: Annotated[bool, typer.Option("--no-source", help=_SOURCE_HELP)] = False,
+    no_timestamp: Annotated[bool, typer.Option("--no-timestamp", help=_TIMESTAMP_HELP)] = False,
+    allow_sensitive: Annotated[
+        bool, typer.Option("--allow-sensitive", help=_SENSITIVE_HELP)
+    ] = False,
+    out: Annotated[Path | None, typer.Option("--out", "-o", help=_OUT_HELP)] = None,
+) -> None:
+    """Generate CLAUDE_CONTEXT.md for Claude Code sessions."""
+    from contextos.exporters import claude
+
+    _run_export(
+        tool_module=claude,
+        repo=repo,
+        task=task,
+        budget=budget,
+        include_tests=include_tests,
+        no_source=no_source,
+        no_timestamp=no_timestamp,
+        allow_sensitive=allow_sensitive,
+        out=out,
+    )
+
+
+# ---------------------------------------------------------------------------
+# codex
+# ---------------------------------------------------------------------------
+
+
+@app.command("codex")
+def export_codex(
+    repo: Annotated[Path, typer.Option("--repo", "-r", help=_REPO_HELP)] = Path("."),
+    task: Annotated[str, typer.Option("--task", "-t", help=_TASK_HELP)] = ...,  # type: ignore[assignment]
+    budget: Annotated[int, typer.Option("--budget", "-b", help=_BUDGET_HELP)] = 8000,
+    include_tests: Annotated[
+        bool, typer.Option("--include-tests/--no-tests", help=_TESTS_HELP)
+    ] = True,
+    no_source: Annotated[bool, typer.Option("--no-source", help=_SOURCE_HELP)] = False,
+    no_timestamp: Annotated[bool, typer.Option("--no-timestamp", help=_TIMESTAMP_HELP)] = False,
+    allow_sensitive: Annotated[
+        bool, typer.Option("--allow-sensitive", help=_SENSITIVE_HELP)
+    ] = False,
+    out: Annotated[Path | None, typer.Option("--out", "-o", help=_OUT_HELP)] = None,
+) -> None:
+    """Generate CODEX_CONTEXT.md for OpenAI Codex / GPT-4 agent sessions."""
+    from contextos.exporters import codex
+
+    _run_export(
+        tool_module=codex,
+        repo=repo,
+        task=task,
+        budget=budget,
+        include_tests=include_tests,
+        no_source=no_source,
+        no_timestamp=no_timestamp,
+        allow_sensitive=allow_sensitive,
+        out=out,
+    )
+
+
+# ---------------------------------------------------------------------------
+# cursor
+# ---------------------------------------------------------------------------
+
+
+@app.command("cursor")
+def export_cursor(
+    repo: Annotated[Path, typer.Option("--repo", "-r", help=_REPO_HELP)] = Path("."),
+    task: Annotated[str, typer.Option("--task", "-t", help=_TASK_HELP)] = ...,  # type: ignore[assignment]
+    budget: Annotated[int, typer.Option("--budget", "-b", help=_BUDGET_HELP)] = 8000,
+    include_tests: Annotated[
+        bool, typer.Option("--include-tests/--no-tests", help=_TESTS_HELP)
+    ] = True,
+    no_source: Annotated[bool, typer.Option("--no-source", help=_SOURCE_HELP)] = False,
+    no_timestamp: Annotated[bool, typer.Option("--no-timestamp", help=_TIMESTAMP_HELP)] = False,
+    allow_sensitive: Annotated[
+        bool, typer.Option("--allow-sensitive", help=_SENSITIVE_HELP)
+    ] = False,
+    out: Annotated[Path | None, typer.Option("--out", "-o", help=_OUT_HELP)] = None,
+) -> None:
+    """Generate CURSOR_CONTEXT.md for Cursor IDE sessions."""
+    from contextos.exporters import cursor
+
+    _run_export(
+        tool_module=cursor,
+        repo=repo,
+        task=task,
+        budget=budget,
+        include_tests=include_tests,
+        no_source=no_source,
+        no_timestamp=no_timestamp,
+        allow_sensitive=allow_sensitive,
+        out=out,
+    )
+
+
+# ---------------------------------------------------------------------------
+# aider
+# ---------------------------------------------------------------------------
+
+
+@app.command("aider")
+def export_aider(
+    repo: Annotated[Path, typer.Option("--repo", "-r", help=_REPO_HELP)] = Path("."),
+    task: Annotated[str, typer.Option("--task", "-t", help=_TASK_HELP)] = ...,  # type: ignore[assignment]
+    budget: Annotated[int, typer.Option("--budget", "-b", help=_BUDGET_HELP)] = 8000,
+    include_tests: Annotated[
+        bool, typer.Option("--include-tests/--no-tests", help=_TESTS_HELP)
+    ] = True,
+    no_source: Annotated[bool, typer.Option("--no-source", help=_SOURCE_HELP)] = False,
+    no_timestamp: Annotated[bool, typer.Option("--no-timestamp", help=_TIMESTAMP_HELP)] = False,
+    allow_sensitive: Annotated[
+        bool, typer.Option("--allow-sensitive", help=_SENSITIVE_HELP)
+    ] = False,
+    out: Annotated[Path | None, typer.Option("--out", "-o", help=_OUT_HELP)] = None,
+) -> None:
+    """Generate AIDER_CONTEXT.md for Aider pair-programming sessions."""
+    from contextos.exporters import aider
+
+    _run_export(
+        tool_module=aider,
+        repo=repo,
+        task=task,
+        budget=budget,
+        include_tests=include_tests,
+        no_source=no_source,
+        no_timestamp=no_timestamp,
+        allow_sensitive=allow_sensitive,
+        out=out,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Shared runner (called by all sub-commands)
+# ---------------------------------------------------------------------------
+
+
+def _run_export(
+    *,
+    tool_module: object,
+    repo: Path,
+    task: str,
+    budget: int,
+    include_tests: bool,
+    no_source: bool,
+    no_timestamp: bool,
+    allow_sensitive: bool = False,
+    out: Path | None,
+) -> None:
+    """Validate inputs, call the tool exporter, and print a summary."""
+    from contextos.exporters.base import ExportConfig
+
+    root = repo.resolve()
+    if not root.is_dir():
+        console.print(f"[red]Error:[/red] {root} is not a directory.")
+        raise typer.Exit(code=1)
+
+    if budget <= 0:
+        console.print("[red]Error:[/red] --budget must be a positive integer.")
+        raise typer.Exit(code=1)
+
+    contextos_dir = root / _CONTEXTOS_DIR
+    exporter = cast(_ExporterModule, tool_module)
+    tool_name = getattr(exporter, "TOOL_NAME", "Unknown")
+    filename = getattr(exporter, "FILENAME", "CONTEXT.md")
+
+    console.print(f"[bold]Exporting[/bold] context for [cyan]{tool_name}[/cyan]")
+    console.print(f"  Repo   : {root}")
+    console.print(f"  Task   : {task}")
+    console.print(f"  Budget : {budget:,} tokens")
+    if no_source:
+        console.print("  Source : [dim]summaries only[/dim]")
+    if not include_tests:
+        console.print("  Tests  : [dim]excluded[/dim]")
+    if allow_sensitive:
+        console.print("  [bold red]⚠  --allow-sensitive: secret redaction DISABLED[/bold red]")
+
+    cfg = ExportConfig(
+        budget=budget,
+        include_tests=include_tests,
+        no_source=no_source,
+        add_timestamp=not no_timestamp,
+        allow_sensitive=allow_sensitive,
+    )
+
+    content, selection = exporter.export(task, root, contextos_dir, config=cfg)
+
+    if selection.secret_warnings and not allow_sensitive:
+        console.print(
+            f"  [yellow]⚠  {len(selection.secret_warnings)} secret(s) detected and "
+            f"redacted with [REDACTED_*][/yellow]"
+        )
+
+    default_out = contextos_dir / filename
+    console.print(
+        f"\n[green]✓[/green] Wrote [bold]{filename}[/bold] "
+        f"({len(selection.selected)} files, ~{selection.used_tokens:,} tokens)"
+    )
+    console.print(f"  Path: {default_out}")
+
+    if out is not None:
+        out.write_text(content, encoding="utf-8")
+        console.print(f"[green]✓[/green] Also written to [bold]{out}[/bold]")

contextos/cli/commands/init.py

@@ -0,0 +1,96 @@
+"""init command — initialize the .contextos/ project directory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from contextos.core import initializer
+
+app = typer.Typer(help="Initialize the .contextos/ directory in a project.")
+console = Console()
+
+_STATUS_STYLE: dict[str, str] = {
+    "created": "green",
+    "overwritten": "yellow",
+    "skipped": "dim",
+    "error": "red",
+}
+
+_STATUS_ICON: dict[str, str] = {
+    "created": "✓",
+    "overwritten": "↺",
+    "skipped": "–",
+    "error": "✗",
+}
+
+
+def init_command(
+    directory: Annotated[Path, typer.Argument(help="Project directory to initialize.")] = Path("."),
+    force: Annotated[
+        bool, typer.Option("--force", "-f", help="Overwrite all existing files.")
+    ] = False,
+    quiet: Annotated[
+        bool, typer.Option("--quiet", "-q", help="Suppress file-by-file output.")
+    ] = False,
+) -> None:
+    """Create the .contextos/ directory with template files.
+
+    Safe to run multiple times — existing memory files are skipped unless
+    --force is passed.  Computed files (file_summaries.json, etc.) are also
+    skipped by init; they are overwritten by `scan` and `pack`.
+    """
+    root = directory.resolve()
+
+    if not root.exists():
+        console.print(f"[red]Error:[/red] directory does not exist: {root}")
+        raise typer.Exit(code=1)
+
+    result = initializer.run(root, force=force)
+
+    if not quiet:
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 1))
+        table.add_column("Status", width=2)
+        table.add_column("File")
+        table.add_column("Note", style="dim")
+
+        for f in result.files:
+            icon = _STATUS_ICON.get(f.status, "?")
+            style = _STATUS_STYLE.get(f.status, "")
+            note = f.message if f.status == "error" else ""
+            table.add_row(
+                f"[{style}]{icon}[/{style}]",
+                f"[{style}].contextos/{f.name}[/{style}]",
+                note,
+            )
+
+        console.print(table)
+        console.print()
+
+    created = len(result.created)
+    skipped = len(result.skipped)
+    overwritten = len(result.overwritten)
+    errors = len(result.errors)
+
+    parts: list[str] = []
+    if created:
+        parts.append(f"[green]{created} created[/green]")
+    if overwritten:
+        parts.append(f"[yellow]{overwritten} overwritten[/yellow]")
+    if skipped:
+        parts.append(f"[dim]{skipped} skipped[/dim]")
+    if errors:
+        parts.append(f"[red]{errors} error(s)[/red]")
+
+    summary = ", ".join(parts) if parts else "nothing to do"
+    console.print(f"[bold]{result.contextos_dir}[/bold]  {summary}")
+
+    if errors:
+        raise typer.Exit(code=1)
+
+
+app.command()(init_command)

contextos/cli/commands/memory.py

@@ -0,0 +1,262 @@
+"""memory command — manage .contextos/MEMORY.md and .contextos/DECISIONS.md."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+
+app = typer.Typer(help="Manage project memory and decision log in .contextos/.")
+console = Console()
+
+_CONTEXTOS_DIR = ".contextos"
+_MEMORY_FILE = "MEMORY.md"
+_DECISIONS_FILE = "DECISIONS.md"
+
+# Patterns that suggest embedded secrets — reject notes containing these.
+# Matches "keyword=<value>" or "keyword: <value>" (not bare mentions of the word).
+_SECRET_RE: re.Pattern[str] = re.compile(
+    r"(?:password|secret|api[_\-.]?key|access[_\-.]?token|bearer|private[_\-.]?key)"
+    r"\s*[=:]\s*\S{4,}",
+    re.IGNORECASE,
+)
+# Long hex strings that look like raw API keys or hashes.
+_HEX_RE: re.Pattern[str] = re.compile(r"[0-9a-fA-F]{40,}")
+# Base64 blobs (common in JWT / bearer tokens).
+_B64_RE: re.Pattern[str] = re.compile(r"[A-Za-z0-9+/]{60,}={0,2}")
+
+
+# ---------------------------------------------------------------------------
+# Sub-command group
+# ---------------------------------------------------------------------------
+
+
+@app.callback()
+def memory_root(ctx: typer.Context) -> None:  # noqa: ARG001
+    """Manage .contextos/MEMORY.md and .contextos/DECISIONS.md."""
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@app.command("add")
+def memory_add(
+    note: Annotated[str, typer.Argument(help="Note text to append to MEMORY.md.")],
+    repo: Annotated[
+        Path,
+        typer.Option("--repo", "-r", help="Repository root (default: current directory)."),
+    ] = Path("."),
+) -> None:
+    """Append a timestamped note to .contextos/MEMORY.md."""
+    _impl_add(note, repo.resolve())
+
+
+@app.command("update")
+def memory_update(
+    note: Annotated[str, typer.Argument(help="Note text to append to MEMORY.md.")],
+    repo: Annotated[
+        Path,
+        typer.Option("--repo", "-r", help="Repository root (default: current directory)."),
+    ] = Path("."),
+) -> None:
+    """Append a timestamped note to .contextos/MEMORY.md (alias for add)."""
+    _impl_add(note, repo.resolve())
+
+
+@app.command("decision")
+def memory_decision(
+    text: Annotated[str, typer.Argument(help="Decision text to record.")],
+    repo: Annotated[
+        Path,
+        typer.Option("--repo", "-r", help="Repository root (default: current directory)."),
+    ] = Path("."),
+    status: Annotated[
+        str,
+        typer.Option("--status", "-s", help='Decision status (default: "accepted").'),
+    ] = "accepted",
+) -> None:
+    """Append a timestamped decision to .contextos/DECISIONS.md."""
+    _impl_decision(text, status, repo.resolve())
+
+
+@app.command("list")
+def memory_list(
+    repo: Annotated[
+        Path,
+        typer.Option("--repo", "-r", help="Repository root (default: current directory)."),
+    ] = Path("."),
+    show_decisions: Annotated[
+        bool,
+        typer.Option("--decisions/--no-decisions", help="Also show DECISIONS.md."),
+    ] = True,
+) -> None:
+    """Display .contextos/MEMORY.md and optionally DECISIONS.md."""
+    _impl_list(repo.resolve(), show_decisions=show_decisions)
+
+
+@app.command("compact")
+def memory_compact(
+    repo: Annotated[  # noqa: ARG001
+        Path,
+        typer.Option("--repo", "-r", help="Repository root (default: current directory)."),
+    ] = Path("."),
+) -> None:
+    """[Placeholder] Compact memory via LLM — not yet implemented."""
+    console.print("[yellow]Compaction is not yet implemented.[/yellow]")
+    console.print(
+        "To compact manually: edit [bold].contextos/MEMORY.md[/bold] and remove outdated entries."
+    )
+    console.print("Future versions will compress notes into concise summaries using an LLM.")
+
+
+# ---------------------------------------------------------------------------
+# Implementation helpers (also imported directly in tests)
+# ---------------------------------------------------------------------------
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=UTC).isoformat(timespec="seconds")
+
+
+def _memory_path(root: Path) -> Path:
+    return root / _CONTEXTOS_DIR / _MEMORY_FILE
+
+
+def _decisions_path(root: Path) -> Path:
+    return root / _CONTEXTOS_DIR / _DECISIONS_FILE
+
+
+def _contains_secret(text: str) -> bool:
+    """Return True if *text* appears to embed a secret or credential value."""
+    return bool(_SECRET_RE.search(text) or _HEX_RE.search(text) or _B64_RE.search(text))
+
+
+def _impl_add(note: str, root: Path) -> None:
+    if _contains_secret(note):
+        console.print("[red]Error:[/red] Note appears to contain a secret or credential value.")
+        console.print("Remove secrets before saving to memory.")
+        raise typer.Exit(code=1)
+
+    path = _memory_path(root)
+    _ensure_memory(path)
+    ts = _now_iso()
+    entry = f"- **{ts}** — {note}\n"
+    _append_to_notes(path, entry)
+    console.print(f"[green]✓[/green] Note appended to [bold]{_CONTEXTOS_DIR}/{_MEMORY_FILE}[/bold]")
+    console.print(f"  Set : {ts}")
+    console.print(f"  Note: {note}")
+
+
+def _impl_decision(text: str, status: str, root: Path) -> None:
+    if _contains_secret(text):
+        console.print(
+            "[red]Error:[/red] Decision text appears to contain a secret or credential value."
+        )
+        raise typer.Exit(code=1)
+
+    path = _decisions_path(root)
+    _ensure_decisions(path)
+    ts = _now_iso()
+    date = ts[:10]
+    entry = (
+        "\n---\n\n"
+        f"### [{date}] Decision\n\n"
+        f"**Status:** {status}\n\n"
+        f"**Decision:** {text}\n\n"
+        f"**Logged:** {ts}\n"
+    )
+    _append_raw(path, entry)
+    console.print(
+        f"[green]✓[/green] Decision appended to [bold]{_CONTEXTOS_DIR}/{_DECISIONS_FILE}[/bold]"
+    )
+    console.print(f"  Status   : {status}")
+    console.print(f"  Decision : {text}")
+    console.print(f"  Logged   : {ts}")
+
+
+def _impl_list(root: Path, *, show_decisions: bool = True) -> None:
+    mem = _memory_path(root)
+    dec = _decisions_path(root)
+    found_any = False
+
+    if mem.exists():
+        found_any = True
+        console.print(f"\n[bold cyan]── {_MEMORY_FILE} ──[/bold cyan]")
+        console.print(Markdown(mem.read_text(encoding="utf-8")))
+
+    if show_decisions and dec.exists():
+        found_any = True
+        console.print(f"\n[bold cyan]── {_DECISIONS_FILE} ──[/bold cyan]")
+        console.print(Markdown(dec.read_text(encoding="utf-8")))
+
+    if not found_any:
+        console.print(
+            "[yellow]No memory files found.[/yellow] "
+            "Run `contextos init` or `contextos memory add` first."
+        )
+
+
+# ---------------------------------------------------------------------------
+# File helpers
+# ---------------------------------------------------------------------------
+
+
+def _ensure_memory(path: Path) -> None:
+    """Create MEMORY.md with a Notes section if it doesn't exist."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(
+            "# Project Memory\n\n"
+            "> Persistent notes managed by ContextOS. Append-only recommended.\n\n"
+            "## Notes\n\n",
+            encoding="utf-8",
+        )
+    elif "## Notes" not in path.read_text(encoding="utf-8"):
+        _append_raw(path, "\n## Notes\n\n")
+
+
+def _ensure_decisions(path: Path) -> None:
+    """Create DECISIONS.md with a header if it doesn't exist."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(
+            "# Decision Log\n\n> Architectural and design decisions. Append-only recommended.\n\n",
+            encoding="utf-8",
+        )
+
+
+def _append_to_notes(path: Path, entry: str) -> None:
+    """Append *entry* inside the ## Notes section (before next ## or EOF)."""
+    text = path.read_text(encoding="utf-8")
+    section = "## Notes"
+    if section not in text:
+        _append_raw(path, f"\n{section}\n\n{entry}")
+        return
+
+    idx = text.index(section)
+    after_section = text[idx + len(section) :]
+    # Find next top-level section heading after ## Notes
+    next_h2 = re.search(r"\n##\s", after_section)
+    if next_h2:
+        insert_pos = idx + len(section) + next_h2.start()
+        text = text[:insert_pos] + "\n" + entry + text[insert_pos:]
+    else:
+        if not text.endswith("\n"):
+            text += "\n"
+        text += entry
+    path.write_text(text, encoding="utf-8")
+
+
+def _append_raw(path: Path, text: str) -> None:
+    """Append *text* verbatim to the end of *path*."""
+    existing = path.read_text(encoding="utf-8")
+    if existing and not existing.endswith("\n"):
+        existing += "\n"
+    path.write_text(existing + text, encoding="utf-8")