ctx-lessons 0.1.0__py3-none-any.whl

ctx/cli/app.py

@@ -0,0 +1,66 @@
+"""Typer chassis. Feature units register their subcommands here."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+import typer
+
+app = typer.Typer(
+    name="ctx",
+    help="Curated knowledge CLI for AI coding agents.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        # Distribution name is `ctx-lessons`; the command is `ctx`.
+        try:
+            version = importlib.metadata.version("ctx-lessons")
+        except importlib.metadata.PackageNotFoundError:
+            version = "unknown (not installed)"
+        typer.echo(version)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Verbose progress output (stderr).",
+    ),
+) -> None:
+    """Curated knowledge CLI for AI coding agents."""
+
+
+def main() -> None:
+    """Entry point for `ctx` script."""
+    app()
+
+
+def _register_subcommands() -> None:
+    from ctx.cli.init import register as register_init
+    from ctx.ingest.commands import register as register_ingest
+    from ctx.lesson.commands import register as register_lesson
+    from ctx.promote.commands import register as register_promote
+    from ctx.query.commands import register as register_query
+    from ctx.sync.commands import register as register_sync
+
+    register_lesson(app)
+    register_init(app)
+    register_query(app)
+    register_ingest(app)
+    register_sync(app)
+    register_promote(app)
+
+
+_register_subcommands()

ctx/cli/config.py

@@ -0,0 +1,226 @@
+"""Config discovery + loading per ADR-0005.
+
+Two separate config surfaces:
+- **Repo** (`<repo>/.ctx.toml` or ``[ctx]`` table in pyproject.toml /
+  package.json): team-shared, defines scope identity for the repo.
+- **Home** (``~/.ctx/config.toml``): per-developer, holds extractor
+  provider, model, and bot-author allowlist. Never overridden by repo.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ctx.lesson.models import SCOPE_RE
+
+_DEFAULT_BOT_AUTHORS = [
+    "dependabot[bot]",
+    "renovate[bot]",
+    "codecov[bot]",
+    "github-actions[bot]",
+]
+
+_MAX_CONFIG_FILE_BYTES = 1 * 1024 * 1024  # 1 MiB cap; defends against memory DoS
+_MAX_WALK_DEPTH = 32
+
+_CTX_HEADING_RE = re.compile(r"^## ctx\s*$", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class RepoConfig:
+    scope: str
+    team: str | None = None
+    product: str | None = None
+    include_products: list[str] = field(default_factory=list)
+    applies_to_default: str | None = None
+
+
+@dataclass(frozen=True)
+class HomeConfig:
+    extractor_provider: str = "anthropic"
+    extractor_model: str | None = None
+    extractor_base_url: str | None = None
+    excluded_authors: list[str] = field(default_factory=lambda: list(_DEFAULT_BOT_AUTHORS))
+
+
+@dataclass(frozen=True)
+class ActiveScope:
+    """The scope set used as the default for queries.
+
+    Per ADR-0005 + ADR-0003: when no explicit ``--scope`` is given,
+    queries run against this set; ranking favours the most specific match.
+    """
+
+    scope_set: set[str]
+
+    @classmethod
+    def from_repo_config(cls, cfg: RepoConfig | None) -> ActiveScope:
+        if cfg is None:
+            return cls(scope_set={"org"})
+        scopes = {cfg.scope, "org"}
+        if cfg.team:
+            scopes.add(f"team:{cfg.team}")
+        if cfg.product:
+            scopes.add(f"product:{cfg.product}")
+        # C5: .ctx.toml `include_products` opts in to additional product scopes
+        # (e.g. predecessor product for legacy lesson access).
+        for product in cfg.include_products:
+            scopes.add(f"product:{product}")
+        return cls(scope_set=scopes)
+
+
+def discover_repo_config(start: Path) -> RepoConfig | None:
+    """Walk from ``start`` upward looking for a ctx config.
+
+    Stops at the first match, the directory containing ``.git``, the user's
+    home directory, the filesystem root, or after ``_MAX_WALK_DEPTH`` steps —
+    whichever comes first.
+
+    To prevent symlink-based bypass of the home-boundary check, the walk
+    operates on logical (non-resolved) paths.
+    """
+    home = Path(os.environ.get("HOME", str(Path.home())))
+    start_path = Path(start)
+
+    # If start is not under home, only check start itself — do not walk into
+    # ancestor directories that may be attacker-plantable.
+    if not _is_under(start_path, home):
+        return _try_loaders_in(start_path)
+
+    cur = start_path
+    for _ in range(_MAX_WALK_DEPTH):
+        cfg = _try_loaders_in(cur)
+        if cfg is not None:
+            return cfg
+        if (cur / ".git").exists():
+            return None
+        if cur == home or cur.parent == cur:
+            return None
+        cur = cur.parent
+    return None
+
+
+def _is_under(path: Path, ancestor: Path) -> bool:
+    """True if `path` is `ancestor` or below, comparing logical components."""
+    try:
+        path.relative_to(ancestor)
+        return True
+    except ValueError:
+        return False
+
+
+def _try_loaders_in(directory: Path) -> RepoConfig | None:
+    if cfg := _load_ctx_toml(directory / ".ctx.toml"):
+        return cfg
+    if cfg := _load_table_from_toml(directory / "pyproject.toml"):
+        return cfg
+    if cfg := _load_table_from_package_json(directory / "package.json"):
+        return cfg
+    return None
+
+
+def _safe_read_text(path: Path) -> str | None:
+    """Read a config file, refusing oversized files. Returns None if absent."""
+    try:
+        size = path.stat().st_size
+    except FileNotFoundError:
+        return None
+    if size > _MAX_CONFIG_FILE_BYTES:
+        return None
+    return path.read_text(encoding="utf-8")
+
+
+def _load_ctx_toml(path: Path) -> RepoConfig | None:
+    text = _safe_read_text(path)
+    if text is None:
+        return None
+    data = tomllib.loads(text)
+    return _repo_config_from_dict(data, source=str(path))
+
+
+def _load_table_from_toml(path: Path) -> RepoConfig | None:
+    text = _safe_read_text(path)
+    if text is None:
+        return None
+    data = tomllib.loads(text)
+    ctx_table = data.get("ctx")
+    if not isinstance(ctx_table, dict):
+        return None
+    return _repo_config_from_dict(ctx_table, source=str(path))
+
+
+def _load_table_from_package_json(path: Path) -> RepoConfig | None:
+    text = _safe_read_text(path)
+    if text is None:
+        return None
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    ctx_table = data.get("ctx")
+    if not isinstance(ctx_table, dict):
+        return None
+    return _repo_config_from_dict(ctx_table, source=str(path))
+
+
+def _repo_config_from_dict(data: dict, *, source: str) -> RepoConfig:
+    if "scope" not in data:
+        raise ValueError(f"{source}: missing required field 'scope'")
+    scope = data["scope"]
+    if not isinstance(scope, str) or not SCOPE_RE.match(scope):
+        raise ValueError(f"{source}: invalid scope: {scope!r}")
+    return RepoConfig(
+        scope=scope,
+        team=data.get("team"),
+        product=data.get("product"),
+        include_products=list(data.get("include_products", [])),
+        applies_to_default=data.get("applies_to_default"),
+    )
+
+
+def load_home_config() -> HomeConfig:
+    home = Path(os.environ.get("HOME", str(Path.home())))
+    path = home / ".ctx" / "config.toml"
+    text = _safe_read_text(path)
+    if text is None:
+        return HomeConfig()
+    data = tomllib.loads(text)
+    extractor = data.get("extractor", {})
+    return HomeConfig(
+        extractor_provider=extractor.get("provider", "anthropic"),
+        extractor_model=extractor.get("model"),
+        extractor_base_url=extractor.get("base_url"),
+        excluded_authors=list(data.get("excluded_authors", _DEFAULT_BOT_AUTHORS)),
+    )
+
+
+# --- warn-once-per-session ----------------------------------------------------
+
+
+def warn_if_no_repo_config(cfg: RepoConfig | None) -> None:
+    """Emit a one-shot stderr warning when falling back to org-only.
+
+    Per ADR-0005: at most one warning per shell session, gated by a touch
+    file under ``~/.ctx/`` keyed on the session id (see ``ctx.session``).
+    """
+    from ctx.session import session_hash
+
+    if cfg is not None:
+        return
+    home = Path(os.environ.get("HOME", str(Path.home())))
+    marker_dir = home / ".ctx"
+    marker_dir.mkdir(parents=True, exist_ok=True)
+    marker = marker_dir / f".warned-{session_hash()}"
+    if marker.exists():
+        return
+    marker.touch()
+    print(
+        "warning: no .ctx.toml found walking up to .git; falling back to org-only retrieval.",
+        file=sys.stderr,
+    )

ctx/cli/init.py

@@ -0,0 +1,123 @@
+"""`ctx init` subcommand: scaffold .ctx.toml + AGENTS.md (+ optional GHA workflow)."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+import typer
+
+from ctx.lesson.models import SCOPE_RE
+
+_AGENTS_SECTION_TEMPLATE = """## ctx
+
+This repo's curated knowledge corpus is queryable via the `ctx` CLI.
+Default scope: `{scope}`.
+
+- `ctx search "<query>"` — search the corpus
+- `ctx show <lesson-id>` — full lesson by id
+- `ctx draft new` — capture a personal-layer lesson
+- `ctx deprecate <id> [--superseded-by <id>]` — mark a lesson outdated
+- `ctx validate <path>` — frontmatter + dead-glob CI gate
+- `ctx sync` — pull team-knowledge updates and reindex
+
+`ctx --help` lists every subcommand. Snippet output is capped at ~30
+lines per result; pass `--json` for parseable agent consumption.
+"""
+
+_CTX_TOML_TEMPLATE = """scope = "{scope}"
+"""
+
+_GHA_WORKFLOW = """name: ctx validate
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv tool install ctx
+      - run: ctx validate "**/*.md"
+"""
+
+_CTX_HEADING_RE = re.compile(r"^## ctx\s*$", re.MULTILINE)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("init")
+    def init(
+        scope: str = typer.Option(..., "--scope"),
+        team_knowledge: bool = typer.Option(
+            False,
+            "--team-knowledge",
+            help="Also write a starter GitHub Actions workflow that runs ctx validate.",
+        ),
+    ) -> None:
+        """Scaffold .ctx.toml and an AGENTS.md ctx section in the current directory."""
+        if not SCOPE_RE.match(scope):
+            typer.echo(f"invalid scope: {scope!r}", err=True)
+            raise typer.Exit(code=2)
+
+        cwd = Path.cwd()
+
+        ctx_toml = cwd / ".ctx.toml"
+        if ctx_toml.is_symlink():
+            typer.echo(f"refusing to write through symlink: {ctx_toml}", err=True)
+            raise typer.Exit(code=2)
+        if not ctx_toml.exists():
+            _write_no_follow(ctx_toml, _CTX_TOML_TEMPLATE.format(scope=scope))
+            typer.echo(f"wrote {ctx_toml}")
+        else:
+            typer.echo(f"{ctx_toml} already exists (skipped)")
+
+        _write_or_append_agents_md(cwd / "AGENTS.md", scope=scope)
+
+        if team_knowledge:
+            wf = cwd / ".github" / "workflows" / "ctx-validate.yml"
+            if wf.is_symlink():
+                typer.echo(f"refusing to write through symlink: {wf}", err=True)
+                raise typer.Exit(code=2)
+            wf.parent.mkdir(parents=True, exist_ok=True)
+            _write_no_follow(wf, _GHA_WORKFLOW)
+            typer.echo(f"wrote {wf}")
+
+
+def _write_no_follow(path: Path, content: str) -> None:
+    """Create-or-truncate `path` without following symlinks.
+
+    Refuses if `path` exists as a symlink. Atomic-enough for v1: an attacker
+    racing to plant a symlink between this and the open() call would still
+    be blocked by O_NOFOLLOW.
+    """
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW
+    fd = os.open(path, flags, 0o644)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def _write_or_append_agents_md(path: Path, *, scope: str) -> None:
+    section = _AGENTS_SECTION_TEMPLATE.format(scope=scope)
+    if path.is_symlink():
+        typer.echo(f"refusing to write through symlink: {path}", err=True)
+        raise typer.Exit(code=2)
+    if not path.exists():
+        _write_no_follow(path, section)
+        typer.echo(f"wrote {path}")
+        return
+    existing = path.read_text(encoding="utf-8")
+    if _CTX_HEADING_RE.search(existing):
+        typer.echo(f"{path} already has a ## ctx section (skipped)")
+        return
+    sep = "" if existing.endswith("\n\n") else ("\n" if existing.endswith("\n") else "\n\n")
+    _write_no_follow(path, existing + sep + section)
+    typer.echo(f"updated {path}")

ctx/db/__init__.py

@@ -0,0 +1,38 @@
+"""SQLite + FTS5 storage for the lesson corpus.
+
+Public surface per ADR-0001. SQL strings never cross this package boundary.
+"""
+
+from ctx.db.migrations import CURRENT_VERSION, apply_v2_reserved, migrate
+from ctx.db.queries import (
+    LessonRecord,
+    SearchResult,
+    add_lesson,
+    connect,
+    count_lessons,
+    deprecated_lessons,
+    get,
+    list_by_scope,
+    mark_deprecated,
+    search,
+    set_superseded_by,
+    stale_lessons,
+)
+
+__all__ = [
+    "CURRENT_VERSION",
+    "LessonRecord",
+    "SearchResult",
+    "add_lesson",
+    "apply_v2_reserved",
+    "connect",
+    "count_lessons",
+    "deprecated_lessons",
+    "get",
+    "list_by_scope",
+    "mark_deprecated",
+    "migrate",
+    "search",
+    "set_superseded_by",
+    "stale_lessons",
+]

ctx/db/migrations.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import sqlite3
+
+from ctx.db.schema import V1_SCHEMA, V2_RESERVED
+
+CURRENT_VERSION = 1
+
+
+def migrate(conn: sqlite3.Connection) -> None:
+    """Apply forward migrations from the stored version to CURRENT_VERSION."""
+    current = conn.execute("PRAGMA user_version").fetchone()[0]
+    if current < 1:
+        conn.executescript(V1_SCHEMA)
+        conn.execute(f"PRAGMA user_version = {1}")
+    # Future: if current < 2: apply v2 here. v2 is NOT auto-applied in v1.
+    conn.commit()
+
+
+def apply_v2_reserved(conn: sqlite3.Connection) -> None:
+    """Apply the reserved v2 embeddings-column migration.
+
+    Used by ADR-0002 forward-compat tests. NOT called by ``migrate()`` in v1.
+    """
+    conn.executescript(V2_RESERVED)
+    conn.execute("PRAGMA user_version = 2")
+    conn.commit()

ctx/db/queries.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import date, timedelta
+from pathlib import Path
+
+from ctx.lesson.frontmatter import dump_yaml, parse_yaml
+from ctx.lesson.models import Lesson
+
+
+@dataclass(frozen=True)
+class LessonRecord:
+    lesson: Lesson
+    body: str
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    lesson: Lesson
+    score: float
+    snippet: str
+
+
+def connect(path: Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(str(path))
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def add_lesson(conn: sqlite3.Connection, lesson: Lesson, *, body: str) -> None:
+    """Upsert a lesson and rebuild its side-table rows. Atomic."""
+    fm = dump_yaml(lesson)
+    with conn:
+        conn.execute(
+            """
+            INSERT INTO lessons (id, scope, category, status, created, last_reviewed,
+                                 superseded_by, body, frontmatter)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                scope=excluded.scope,
+                category=excluded.category,
+                status=excluded.status,
+                created=excluded.created,
+                last_reviewed=excluded.last_reviewed,
+                superseded_by=excluded.superseded_by,
+                body=excluded.body,
+                frontmatter=excluded.frontmatter
+            """,
+            (
+                lesson.id,
+                lesson.scope,
+                lesson.category,
+                lesson.status,
+                lesson.created.isoformat(),
+                lesson.last_reviewed.isoformat(),
+                lesson.superseded_by,
+                body,
+                fm,
+            ),
+        )
+        conn.execute("DELETE FROM lesson_authors WHERE lesson_id = ?", (lesson.id,))
+        conn.execute("DELETE FROM lesson_tags WHERE lesson_id = ?", (lesson.id,))
+        conn.execute("DELETE FROM lesson_applies_to_files WHERE lesson_id = ?", (lesson.id,))
+        conn.executemany(
+            "INSERT INTO lesson_authors (lesson_id, author) VALUES (?, ?)",
+            [(lesson.id, a) for a in lesson.authors],
+        )
+        conn.executemany(
+            "INSERT INTO lesson_tags (lesson_id, tag) VALUES (?, ?)",
+            [(lesson.id, t) for t in lesson.tags],
+        )
+        conn.executemany(
+            "INSERT INTO lesson_applies_to_files (lesson_id, glob) VALUES (?, ?)",
+            [(lesson.id, g) for g in lesson.applies_to_files],
+        )
+
+
+def get(conn: sqlite3.Connection, lesson_id: str) -> LessonRecord | None:
+    row = conn.execute(
+        "SELECT frontmatter, body FROM lessons WHERE id = ?", (lesson_id,)
+    ).fetchone()
+    if row is None:
+        return None
+    return LessonRecord(lesson=parse_yaml(row[0]), body=row[1])
+
+
+def list_by_scope(conn: sqlite3.Connection, scope: str) -> list[Lesson]:
+    rows = conn.execute(
+        "SELECT frontmatter FROM lessons WHERE scope = ? ORDER BY id", (scope,)
+    ).fetchall()
+    return [parse_yaml(r[0]) for r in rows]
+
+
+def _build_fts_query(query: str) -> str | None:
+    """Build a safe FTS5 MATCH expression from raw CLI input.
+
+    Each whitespace-separated term is wrapped as its own quoted phrase and the
+    terms are OR-ed together. Quoting every term defuses the FTS5 operator
+    grammar (NEAR, AND, column:term, parens, ``c++``, unbalanced quotes) — the
+    same injection-safety the old single-phrase wrapper gave us — while OR over
+    individual terms restores recall: a multi-word query matches lessons that
+    contain *any* of the terms, and bm25 ranks lessons matching more of them
+    higher. We deliberately do not treat the whole input as one contiguous
+    phrase, which required every word to appear adjacently and in order.
+
+    Returns ``None`` when the query has no usable terms (caller short-circuits
+    to an empty result set rather than issuing an empty MATCH, which errors).
+    """
+    terms = [t for t in query.split() if t]
+    if not terms:
+        return None
+    return " OR ".join(f'"{t.replace(chr(34), chr(34) * 2)}"' for t in terms)
+
+
+def search(
+    conn: sqlite3.Connection,
+    query: str,
+    *,
+    scope_set: set[str] | None = None,
+    include_deprecated: bool = False,
+    limit: int = 5,
+) -> list[SearchResult]:
+    match_expr = _build_fts_query(query)
+    if match_expr is None:
+        return []
+    sql = """
+        SELECT l.frontmatter,
+               bm25(lessons_fts) AS rank,
+               snippet(lessons_fts, 0, '[', ']', '…', 16) AS snip
+        FROM lessons_fts
+        JOIN lessons l ON l.rowid = lessons_fts.rowid
+        WHERE lessons_fts MATCH ?
+    """
+    params: list[object] = [match_expr]
+    if not include_deprecated:
+        sql += " AND l.status != 'deprecated'"
+    if scope_set is not None:
+        placeholders = ",".join("?" for _ in scope_set)
+        sql += f" AND l.scope IN ({placeholders})"
+        params.extend(scope_set)
+    sql += " ORDER BY rank LIMIT ?"
+    params.append(limit)
+
+    rows = conn.execute(sql, params).fetchall()
+    return [
+        SearchResult(lesson=parse_yaml(fm), score=-rank, snippet=snip or "")
+        for fm, rank, snip in rows
+    ]
+
+
+def count_lessons(
+    conn: sqlite3.Connection,
+    *,
+    scope_set: set[str] | None = None,
+    include_deprecated: bool = False,
+) -> int:
+    """Count lessons, optionally restricted to ``scope_set``.
+
+    Used by the search command to detect the silent empty-scope trap: an active
+    scope (e.g. the org-only fallback) that contains zero lessons while the
+    corpus as a whole is non-empty.
+    """
+    sql = "SELECT count(*) FROM lessons WHERE 1=1"
+    params: list[object] = []
+    if not include_deprecated:
+        sql += " AND status != 'deprecated'"
+    if scope_set is not None:
+        if not scope_set:
+            return 0
+        placeholders = ",".join("?" for _ in scope_set)
+        sql += f" AND scope IN ({placeholders})"
+        params.extend(scope_set)
+    return int(conn.execute(sql, params).fetchone()[0])
+
+
+def mark_deprecated(
+    conn: sqlite3.Connection, lesson_id: str, superseded_by: str | None = None
+) -> None:
+    row = conn.execute("SELECT frontmatter FROM lessons WHERE id = ?", (lesson_id,)).fetchone()
+    if row is None:
+        raise KeyError(lesson_id)
+    updated = parse_yaml(row[0]).model_copy(
+        update={"status": "deprecated", "superseded_by": superseded_by}
+    )
+    with conn:
+        conn.execute(
+            "UPDATE lessons SET status=?, superseded_by=?, frontmatter=? WHERE id=?",
+            ("deprecated", superseded_by, dump_yaml(updated), lesson_id),
+        )
+
+
+def set_superseded_by(conn: sqlite3.Connection, lesson_id: str, replacement_id: str) -> None:
+    row = conn.execute("SELECT frontmatter FROM lessons WHERE id = ?", (lesson_id,)).fetchone()
+    if row is None:
+        raise KeyError(lesson_id)
+    updated = parse_yaml(row[0]).model_copy(update={"superseded_by": replacement_id})
+    with conn:
+        conn.execute(
+            "UPDATE lessons SET superseded_by=?, frontmatter=? WHERE id=?",
+            (replacement_id, dump_yaml(updated), lesson_id),
+        )
+
+
+def deprecated_lessons(conn: sqlite3.Connection) -> list[Lesson]:
+    rows = conn.execute(
+        "SELECT frontmatter FROM lessons WHERE status = 'deprecated' ORDER BY id"
+    ).fetchall()
+    return [parse_yaml(r[0]) for r in rows]
+
+
+def stale_lessons(conn: sqlite3.Connection, months: int) -> list[Lesson]:
+    # 30-day months — good enough for "stale" semantics.
+    threshold = (date.today() - timedelta(days=months * 30)).isoformat()
+    rows = conn.execute(
+        "SELECT frontmatter FROM lessons WHERE last_reviewed <= ? ORDER BY last_reviewed",
+        (threshold,),
+    ).fetchall()
+    return [parse_yaml(r[0]) for r in rows]