:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""Enable the context layer for an organization: scaffold the wiki, then import
existing channel CONTEXT.md documents once.
The legacy ChannelInstructions rows are never deleted, so turning the flag off
restores the old behavior exactly as it was at import time.
"""
from __future__ import annotations
import uuid
from pathlib import Path
from django.db import transaction
from django.utils.text import slugify
import structlog
from posthog.dataclasses import frozen
from posthog.models.scoping import team_scope
from posthog.models.team.team import Team
from products.access_control.backend.models.access_control import AccessControl
from products.context_layer.backend import repo_lint, store
from products.context_layer.backend.legacy_pages import migrate_legacy_channel_pages
from products.context_layer.backend.models import ContextLayerConfig
from products.context_layer.backend.scaffold import AGENTS_MD
from products.tasks.backend.facade import api as tasks_facade
logger = structlog.get_logger(__name__)
def enable_context_layer(
organization_id: uuid.UUID | str,
*,
created_by_id: int | None = None,
) -> ContextLayerConfig:
"""Idempotent: re-enabling scaffolds nothing and re-imports only missing pages."""
_record_restricted_projects(organization_id)
config = store.initialize_repo(organization_id, created_by_id=created_by_id)
import_channel_context(organization_id)
# The import lands its own commit, so the row read before it is already a
# head behind. Callers use this sha as `base_head`, and a stale one costs
# them a spurious conflict on their first write.
config.refresh_from_db()
transaction.on_commit(lambda: _trigger_bootstrap_dream(str(organization_id)), robust=True)
return config
def _record_restricted_projects(organization_id: uuid.UUID | str) -> None:
"""Note when a wiki is enabled for an organization that restricts a project.
The wiki is organization-wide, so this is the moment that project's
synthesized context becomes readable to members it excludes. That trade-off
is deliberate until per-page provenance ships (see PROVENANCE.md), but it
should be answerable afterwards rather than guessed at, so the organizations
carrying it are recorded where they are accepted.
"""
restricted = set(
Team.objects.filter(organization_id=organization_id, access_control=True).values_list("id", flat=True)
)
restricted.update(
int(resource_id)
for resource_id in AccessControl.objects.filter(
team__organization_id=organization_id,
resource="project",
resource_id__isnull=False,
access_level="none",
).values_list("resource_id", flat=True)
if resource_id and resource_id.isdigit()
)
if restricted:
logger.warning(
"context_layer.enabled_with_restricted_projects",
organization_id=str(organization_id),
restricted_project_ids=sorted(restricted),
)
def _trigger_bootstrap_dream(organization_id: str) -> None:
from products.context_layer.backend.temporal.dreaming import ( # noqa: PLC0415, I001 — keeps Temporal off Django's enablement import path
trigger_bootstrap_dream,
)
trigger_bootstrap_dream(organization_id)
def import_channel_context(organization_id: uuid.UUID | str) -> list[str]:
"""Write every public channel under its project, importing CONTEXT.md when present.
A channel is identified by the `channel_id` in its page's frontmatter, not
by its slug: a channel that already has a page anywhere under `projects/`
is never re-imported (later wiki edits win), and a new channel whose name
collides with an existing page gets a suffixed slug instead of being
silently dropped. Personal channels are skipped: their context belongs to
one person, and the wiki is org-visible.
"""
projects: list[tuple[int, str]] = []
candidates: list[tuple[int, str, str, str | None]] = []
# Order the teams so a same-named channel in two projects always resolves its
# slug collision the same way; an unordered scan could swap the pages between runs.
for team_id, team_name in (
Team.objects.filter(organization_id=organization_id).order_by("id").values_list("id", "name")
):
projects.append((team_id, team_name))
# The enable request is org-scoped, so the fail-closed channel models
# need an explicit team scope per team we read from.
with team_scope(team_id):
for channel in tasks_facade.list_channels(team_id, None):
if channel.channel_type != "public":
continue
instructions = tasks_facade.get_channel_instructions(channel.id, team_id, None)
content = (
instructions.content
if instructions is not None and instructions.version > 0 and instructions.content.strip()
else None
)
candidates.append((team_id, str(channel.id), channel.name, content))
if not projects:
return []
written: list[str] = []
def mutate(root: Path) -> None:
written.clear()
agents_path = root / "AGENTS.md"
if not agents_path.is_file() or agents_path.read_text(encoding="utf-8") != AGENTS_MD:
agents_path.write_text(AGENTS_MD, encoding="utf-8")
written.append("AGENTS.md")
written.extend(
migrate_legacy_channel_pages(root, {channel_id: team_id for team_id, channel_id, _, _ in candidates})
)
index = _existing_channel_pages(root)
for team_id, team_name in projects:
overview_path = f"projects/{team_id}/overview.md"
if overview_path not in index.paths:
target = root / overview_path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(_project_page(team_id, team_name), encoding="utf-8")
index.paths.add(overview_path)
written.append(overview_path)
for team_id, channel_id, name, content in candidates:
if channel_id in index.channel_ids:
continue
path = _unique_channel_path(team_id, name, channel_id, index.paths)
index.paths.add(path)
target = root / path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(_channel_page(team_id, channel_id, name, content), encoding="utf-8")
written.append(path)
store.apply_changes(organization_id, message="Import channel context", mutate=mutate)
return sorted(written)
@frozen
class ImportedChannelIndex:
"""Imported channel ids and paths already present in the wiki."""
channel_ids: set[str]
paths: set[str]
def _existing_channel_pages(root: Path) -> ImportedChannelIndex:
channel_ids: set[str] = set()
paths: set[str] = set()
channels_dir = root / "projects"
if channels_dir.is_dir():
for page in channels_dir.rglob("*.md"):
paths.add(str(page.relative_to(root)))
channel_id = _frontmatter_value(page, "channel_id")
if channel_id:
channel_ids.add(channel_id)
return ImportedChannelIndex(channel_ids=channel_ids, paths=paths)
def _frontmatter_value(page: Path, key: str) -> str | None:
lines = page.read_text(encoding="utf-8", errors="replace").splitlines()
if not lines or lines[0].strip() != "---":
return None
for line in lines[1:]:
if line.strip() == "---":
return None
name, separator, value = line.partition(":")
if separator and name.strip() == key:
return value.strip() or None
return None
def _unique_channel_path(team_id: int, name: str, channel_id: str, taken: set[str]) -> str:
slug = slugify(name) or channel_id
path = f"projects/{team_id}/spaces/{slug}.md"
if path in taken:
path = f"projects/{team_id}/spaces/{slug}-{channel_id[:8]}.md"
return path
def _project_page(team_id: int, team_name: str) -> str:
title = " ".join(team_name.split()) or f"Project {team_id}"
return f"---\nproject_id: {team_id}\nproject_name: {title}\nsummary: Context for project {team_id}.\nstatus: active\nsources: project-catalog\n---\n\n# {title} (project {team_id})\n"
def _split_frontmatter(content: str) -> tuple[list[str], str]:
lines = content.splitlines()
if not lines or lines[0].strip() != "---":
return [], content
for index, line in enumerate(lines[1:], start=1):
if line.strip() == "---":
return lines[1:index], "\n".join(lines[index + 1 :])
return [], content
def _top_level_key(line: str) -> str | None:
if not line or line[0].isspace() or line.startswith(("-", "#")):
return None
name, separator, _ = line.partition(":")
return name.strip() if separator else None
def _merge_frontmatter(identity: list[str], imported: list[str], defaults: list[str]) -> list[str]:
# The server binds page writes to a space through `team_id` and `channel_id`, so imported values never replace them.
identity_keys = {_top_level_key(line) for line in identity}
kept = [line for line in imported if _top_level_key(line) not in identity_keys]
kept_keys = {_top_level_key(line) for line in kept}
return [*identity, *kept, *(line for line in defaults if _top_level_key(line) not in kept_keys)]
def _is_lint_clean(frontmatter: list[str]) -> bool:
# The import lints the whole wiki in one change, so one page the lint rejects blocks every page in the
# organization. Accept only frontmatter this check proves clean: `superseded` and `review_after` need
# checks against other pages or dates, so they fall back to the body as well, where the import encodes bad links.
fields = {
key: value.strip()
for key, separator, value in (line.partition(":") for line in frontmatter)
if separator and key and key == key.strip()
}
_, malformed_links = repo_lint._links("\n".join(frontmatter))
return (
not malformed_links
and not repo_lint._lint_frontmatter_lists(frontmatter)
and bool(fields.get("summary"))
and fields.get("status") in {"active", "historical"}
and "review_after" not in fields
)
def _channel_page(team_id: int, channel_id: str, channel_name: str, content: str | None) -> str:
title = " ".join(channel_name.split()) or channel_id
identity = [f"team_id: {team_id}", f"channel_id: {channel_id}"]
if content is None:
frontmatter = [*identity, f"summary: Context for {title}.", "status: active", "sources: channel-catalog"]
body = ""
else:
defaults = [
f"summary: Context imported from {title}.",
"status: active",
"sources: channel-instructions-import",
]
imported_frontmatter, remainder = _split_frontmatter(content.strip())
frontmatter = _merge_frontmatter(identity, imported_frontmatter, defaults)
if not _is_lint_clean(frontmatter):
frontmatter, remainder = [*identity, *defaults], content.strip()
sanitized_content, repaired = _sanitize_imported_context(remainder.strip())
repair_note = (
"\n> **Import note:** Some wiki-link brackets in this imported context were encoded because they were "
"malformed. Review and repair the links.\n"
if repaired
else ""
)
body = f"{repair_note}\n{sanitized_content}\n"
return "---\n" + "\n".join(frontmatter) + f"\n---\n\n# {title} (project {team_id}, Space {channel_id[:8]})\n{body}"
def _sanitize_imported_context(content: str) -> tuple[str, bool]:
parts: list[str] = []
cursor = 0
repaired = False
for match in repo_lint.WIKILINK_RE.finditer(content):
prefix, changed = _encode_wikilink_brackets(content[cursor : match.start()])
parts.append(prefix)
repaired |= changed
if repo_lint._wikilink_target(match.group(1)) is None:
encoded, _ = _encode_wikilink_brackets(match.group(0))
parts.append(encoded)
repaired = True
else:
parts.append(match.group(0))
cursor = match.end()
suffix, changed = _encode_wikilink_brackets(content[cursor:])
parts.append(suffix)
return "".join(parts), repaired or changed
def _encode_wikilink_brackets(content: str) -> tuple[str, bool]:
encoded = content.replace("[[", "[[").replace("]]", "]]")
return encoded, encoded != content