contextbase-plugin-claude-local 0.2.9__py3-none-any.whl

contextbase_plugin_claude_local-0.2.9.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: contextbase-plugin-claude-local
+Version: 0.2.9
+Summary: Claude local plugin for ContextBase
+Author: Alizain Feerasta
+Author-email: Alizain Feerasta <alizain.feerasta@gmail.com>
+Requires-Dist: contextbase-shared-plugins==0.2.9
+Requires-Dist: dagster==1.12.14
+Requires-Dist: dagster-dlt==0.28.14
+Requires-Dist: dlt>=1.26.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Python: >=3.14, <3.15

contextbase_plugin_claude_local-0.2.9.dist-info/RECORD

@@ -0,0 +1,17 @@
+plugin_claude_local/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plugin_claude_local/binding_config.py,sha256=a4cpuKyuUPQVqIqIMCMFy2meKLkk-sZjRcb3b6BOV7A,337
+plugin_claude_local/component.py,sha256=9m-42ISkOrwsx0Jtxa8zVL-dDOSJfaAT4P1DVQN-7Ug,4120
+plugin_claude_local/defs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plugin_claude_local/defs/defs.yaml,sha256=eBgWLlMQShBV205vMyw-mhA6rS9-A4pu8PnBvPsdNbw,61
+plugin_claude_local/models/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+plugin_claude_local/models/ctx.py,sha256=mDOde7jA0IQzD0BMHoPA0CG4ijd3C4MDC1nHhrUrD4M,2605
+plugin_claude_local/models/ingress.py,sha256=9zG4L5wSS3v8I-oeXKskZkuzrw27yQtGAD0RHKwVENs,3843
+plugin_claude_local/models/translators.py,sha256=i9HBM0wBZBWfUkk4HMoa8ad7FwYNOa-87EWMCObgJQo,7506
+plugin_claude_local/plugin.json,sha256=j_wDEBQ05D_7oMz5wXWUZz-BHhjDxMazubGTzATbx6A,85
+plugin_claude_local/sources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plugin_claude_local/sources/snapshot.py,sha256=1MjTA7b3LfjAo2ldvX3DXXBvnBSqMsz8mFHZjX36bfE,3729
+plugin_claude_local/utils/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+plugin_claude_local/utils/parse.py,sha256=d6XtBzUksY-q1thsirmSQhJOUFad2GwRu-S7XMgmTss,12848
+contextbase_plugin_claude_local-0.2.9.dist-info/WHEEL,sha256=i9aSRDivn5iP9LaR1BLQX2GNAuriQWPsFwbbWygTX2k,81
+contextbase_plugin_claude_local-0.2.9.dist-info/METADATA,sha256=00_zPCVDl70-NkhIIHjB5mnbcWSSKmmHGwpVx5J-49U,412
+contextbase_plugin_claude_local-0.2.9.dist-info/RECORD,,

contextbase_plugin_claude_local-0.2.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.15
+Root-Is-Purelib: true
+Tag: py3-none-any

plugin_claude_local/binding_config.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field
+
+from shared_plugins.bindings import BaseBindingConfigModel, ResolvedPath
+
+
+class ClaudeLocalBindingConfig(BaseBindingConfigModel):
+    projects_dir: ResolvedPath = Field(
+        default_factory=lambda: Path.home() / ".claude" / "projects",
+    )

plugin_claude_local/component.py

@@ -0,0 +1,122 @@
+import dagster as dg
+from dagster import AssetExecutionContext
+from dagster_dlt import DagsterDltResource
+from shared_plugins.automation import non_overlapping_automation_condition
+from shared_plugins.bindings import parse_binding_config
+from shared_plugins.control_plane import ControlPlaneClient
+from shared_plugins.dlt import resolve_partition_binding, run_dlt_pipeline
+from shared_plugins.naming import (
+    dagster_asset_group_name,
+    dagster_asset_tags,
+    dagster_dlt_asset_key,
+    dagster_partition_def_name,
+    dagster_pool_name,
+    dlt_source_name,
+    plugin_id_from_module,
+)
+from shared_plugins.resources import DLT_RESOURCE
+
+from .binding_config import ClaudeLocalBindingConfig
+from .sources.snapshot import claude_local_snapshot_source
+
+PLUGIN_ID = plugin_id_from_module(__file__)
+SNAPSHOT_JOB = "snapshot"
+SNAPSHOT_SOURCE_NAME = dlt_source_name(PLUGIN_ID, SNAPSHOT_JOB)
+
+
+def _build_snapshot_specs(
+    partitions_def: dg.PartitionsDefinition,
+    automation_condition: dg.AutomationCondition,
+) -> list[dg.AssetSpec]:
+    shared = dict(
+        group_name=dagster_asset_group_name(PLUGIN_ID),
+        tags=dagster_asset_tags(PLUGIN_ID),
+        automation_condition=automation_condition,
+        partitions_def=partitions_def,
+    )
+
+    project_key = dagster_dlt_asset_key(SNAPSHOT_SOURCE_NAME, "project")
+    conversation_key = dagster_dlt_asset_key(SNAPSHOT_SOURCE_NAME, "conversation")
+    line_key = dagster_dlt_asset_key(SNAPSHOT_SOURCE_NAME, "line")
+    turn_key = dagster_dlt_asset_key(SNAPSHOT_SOURCE_NAME, "turn")
+
+    return [
+        dg.AssetSpec(
+            key=project_key,
+            **shared,
+        ),
+        dg.AssetSpec(
+            key=conversation_key,
+            deps=[project_key],
+            **shared,
+        ),
+        dg.AssetSpec(
+            key=line_key,
+            deps=[conversation_key],
+            **shared,
+        ),
+        dg.AssetSpec(
+            key=turn_key,
+            deps=[line_key],
+            **shared,
+        ),
+    ]
+
+
+class ClaudeLocalSyncComponent(dg.Component):
+    def build_defs(self, context: dg.ComponentLoadContext) -> dg.Definitions:
+        partitions_def = dg.DynamicPartitionsDefinition(
+            name=dagster_partition_def_name(PLUGIN_ID)
+        )
+
+        snapshot_specs = _build_snapshot_specs(
+            partitions_def=partitions_def,
+            automation_condition=non_overlapping_automation_condition(
+                dg.AutomationCondition.on_missing()
+                | dg.AutomationCondition.on_cron("*/15 * * * *")
+            ),
+        )
+
+        @dg.multi_asset(
+            specs=snapshot_specs,
+            can_subset=True,
+            name="claude_local_snapshot",
+            pool=dagster_pool_name(PLUGIN_ID),
+        )
+        def claude_local_snapshot_assets(
+            context: AssetExecutionContext,
+            dlt_resource: DagsterDltResource,
+            control_plane: dg.ResourceParam[ControlPlaneClient],
+        ):
+            binding = resolve_partition_binding(
+                context=context,
+                control_plane=control_plane,
+                plugin_id=PLUGIN_ID,
+            )
+            binding_id = str(binding.binding_id)
+            cfg = parse_binding_config(binding, ClaudeLocalBindingConfig)
+
+            source = claude_local_snapshot_source(binding_id, cfg)
+            yield from run_dlt_pipeline(
+                context=context,
+                dlt_resource=dlt_resource,
+                source=source,
+                plugin_id=PLUGIN_ID,
+                binding_id=binding_id,
+                job_name=SNAPSHOT_JOB,
+            )
+
+        automation_sensor = dg.AutomationConditionSensorDefinition(
+            name="claude_local_automation_sensor",
+            target=dg.AssetSelection.assets(claude_local_snapshot_assets),
+            default_status=dg.DefaultSensorStatus.RUNNING,
+            minimum_interval_seconds=30,
+        )
+
+        return dg.Definitions(
+            assets=[claude_local_snapshot_assets],
+            sensors=[automation_sensor],
+            resources={
+                "dlt_resource": DLT_RESOURCE,
+            },
+        )

plugin_claude_local/defs/defs.yaml

@@ -0,0 +1 @@
+type: plugin_claude_local.component.ClaudeLocalSyncComponent

plugin_claude_local/models/__init__.py

@@ -0,0 +1 @@
+

plugin_claude_local/models/ctx.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import AwareDatetime
+from shared_plugins.models import CtxModel, IdStr, NonNegativeInt
+
+
+class ProjectRow(CtxModel):
+    encoded_dir: IdStr
+
+
+class ConversationRow(CtxModel):
+    jsonl_stem: IdStr
+    project_dir: IdStr
+    jsonl_parent_dir: str = ""
+    jsonl_path: IdStr
+    jsonl_mtime: AwareDatetime | None = None
+    user_message_count: NonNegativeInt
+    assistant_message_count: NonNegativeInt
+
+
+class LineRow(CtxModel):
+    project_dir: IdStr
+    jsonl_stem: IdStr
+    jsonl_parent_dir: str = ""
+    line_index: NonNegativeInt
+    type: str | None = None
+    subtype: str | None = None
+    uuid: str | None = None
+    parent_uuid: str | None = None
+    timestamp: AwareDatetime | None = None
+    session_id: str | None = None
+    version: str | None = None
+    cwd: str | None = None
+    # Canonical JSONL line text, with trailing CR/LF removed by the parser.
+    raw_line: str
+    # Parsed JSON value for querying. Strings in nested structures may have
+    # embedded null bytes removed before persistence because Postgres rejects
+    # \u0000 in text/jsonb.
+    payload: Any = None
+    parse_error: str | None = None
+    turn_projection_error: str | None = None
+
+
+class TurnRow(CtxModel):
+    # -- file metadata --
+    project_dir: IdStr
+    jsonl_stem: IdStr
+    jsonl_parent_dir: str = ""
+    line_index: NonNegativeInt
+
+    # -- event envelope (union of user + assistant event fields) --
+    type: str
+    uuid: IdStr
+    parent_uuid: str | None = None
+    timestamp: AwareDatetime
+    is_sidechain: bool
+    user_type: str
+    cwd: str
+    session_id: str
+    version: str
+    git_branch: str
+    slug: str | None = None
+    agent_id: str | None = None
+    entrypoint: str | None = None
+
+    # -- user-only fields --
+    prompt_id: str | None = None
+    is_meta: bool | None = None
+    tool_use_result: Any = None  # jsonb: dict | list | str | None
+    source_tool_use_id: str | None = None
+    source_tool_assistant_uuid: str | None = None
+    thinking_metadata: Any = None  # jsonb: dict | None
+    permission_mode: str | None = None
+    todos: Any = None  # jsonb: list | None
+    is_visible_in_transcript_only: bool | None = None
+    is_compact_summary: bool | None = None
+    plan_content: str | None = None
+
+    # -- assistant-only fields --
+    request_id: str | None = None
+    error: str | None = None
+    is_api_error_message: bool | None = None
+    api_error: str | None = None
+
+    # -- message content / top-level drift (jsonb) --
+    message: dict[str, Any]
+    turn_extra: dict[str, Any] | None = None

plugin_claude_local/models/ingress.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import AwareDatetime, Field
+from shared_plugins.models import IngressModel
+
+# These key sets define the curated transcript projection boundary.
+# parse.py uses them to split a raw user/assistant record into:
+#   1. first-class turn columns we intentionally promote, and
+#   2. turn_extra for every other top-level key.
+# Add a key here only when we want a durable query column in claude_local.turn.
+COMMON_TRANSCRIPT_SOURCE_KEYS = frozenset(
+    {
+        "type",
+        "uuid",
+        "parentUuid",
+        "timestamp",
+        "message",
+        "isSidechain",
+        "userType",
+        "cwd",
+        "sessionId",
+        "version",
+        "gitBranch",
+        "slug",
+        "agentId",
+        "entrypoint",
+    }
+)
+
+USER_TRANSCRIPT_SOURCE_KEYS = COMMON_TRANSCRIPT_SOURCE_KEYS | frozenset(
+    {
+        "promptId",
+        "isMeta",
+        "toolUseResult",
+        "sourceToolUseID",
+        "sourceToolAssistantUUID",
+        "thinkingMetadata",
+        "permissionMode",
+        "todos",
+        "isVisibleInTranscriptOnly",
+        "isCompactSummary",
+        "planContent",
+    }
+)
+
+ASSISTANT_TRANSCRIPT_SOURCE_KEYS = COMMON_TRANSCRIPT_SOURCE_KEYS | frozenset(
+    {
+        "requestId",
+        "error",
+        "isApiErrorMessage",
+        "apiError",
+    }
+)
+
+
+class ClaudeTranscriptTurnIngress(IngressModel):
+    # This model is intentionally narrower than Claude's full local JSONL schema.
+    # It validates the transcript projection that claude_local.turn promises, not
+    # every nested field Claude may emit in the raw source log.
+    uuid: str
+    parent_uuid: str | None = Field(alias="parentUuid")
+    timestamp: AwareDatetime
+    # Keep the message envelope as raw JSON so future nested drift stays queryable
+    # without forcing ingress model churn for every new Claude field.
+    message: dict[str, Any]
+    is_sidechain: bool = Field(alias="isSidechain")
+    user_type: str = Field(alias="userType")
+    cwd: str
+    session_id: str = Field(alias="sessionId")
+    version: str
+    git_branch: str = Field(alias="gitBranch")
+    slug: str | None = None
+    agent_id: str | None = Field(default=None, alias="agentId")
+    entrypoint: str | None = None
+    # Top-level transcript keys that exist in the raw record but are not promoted
+    # to first-class columns land here so claude_local.turn does not drop them.
+    turn_extra: dict[str, Any] | None = None
+
+
+class ClaudeUserTurnIngress(ClaudeTranscriptTurnIngress):
+    type: Literal["user"]
+    prompt_id: str | None = Field(default=None, alias="promptId")
+    is_meta: bool | None = Field(default=None, alias="isMeta")
+    tool_use_result: dict[str, Any] | list[Any] | str | None = Field(
+        default=None, alias="toolUseResult"
+    )
+    source_tool_use_id: str | None = Field(default=None, alias="sourceToolUseID")
+    source_tool_assistant_uuid: str | None = Field(
+        default=None, alias="sourceToolAssistantUUID"
+    )
+    thinking_metadata: dict[str, Any] | None = Field(
+        default=None, alias="thinkingMetadata"
+    )
+    permission_mode: str | None = Field(default=None, alias="permissionMode")
+    todos: list[Any] | None = None
+    is_visible_in_transcript_only: bool | None = Field(
+        default=None, alias="isVisibleInTranscriptOnly"
+    )
+    is_compact_summary: bool | None = Field(default=None, alias="isCompactSummary")
+    plan_content: str | None = Field(default=None, alias="planContent")
+
+
+class ClaudeAssistantTurnIngress(ClaudeTranscriptTurnIngress):
+    type: Literal["assistant"]
+    request_id: str | None = Field(default=None, alias="requestId")
+    error: str | None = None
+    is_api_error_message: bool | None = Field(default=None, alias="isApiErrorMessage")
+    api_error: str | None = Field(default=None, alias="apiError")

plugin_claude_local/models/translators.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from typing import Any
+
+from ..utils.parse import ParsedConversationFile
+from .ctx import ConversationRow, LineRow, ProjectRow, TurnRow
+from .ingress import ClaudeAssistantTurnIngress, ClaudeUserTurnIngress
+
+
+def _strip_null_bytes(value: Any) -> Any:
+    """Recursively strip \\x00 null bytes from strings in a structure.
+
+    Postgres rejects \\u0000 in both text and jsonb columns.
+
+    This is intentionally applied only to structured values that must be written
+    to Postgres text/jsonb columns. It does not change LineRow.raw_line, which
+    remains the canonical decoded JSONL line text for fidelity/debugging.
+    """
+    if isinstance(value, str):
+        return value.replace("\x00", "")
+    if isinstance(value, dict):
+        return {k: _strip_null_bytes(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_strip_null_bytes(item) for item in value]
+    return value
+
+
+def projects_to_ctx_models(
+    *,
+    binding_id: str,
+    project_dirs: Iterable[str],
+) -> Iterator[ProjectRow]:
+    seen_dirs: set[str] = set()
+
+    for encoded_dir in project_dirs:
+        if encoded_dir in seen_dirs:
+            continue
+        seen_dirs.add(encoded_dir)
+
+        yield ProjectRow(
+            ctx_binding_id=binding_id,
+            ctx_source_updated_at=None,
+            encoded_dir=encoded_dir,
+        )
+
+
+def conversations_to_ctx_models(
+    *,
+    binding_id: str,
+    conversations: Iterable[ParsedConversationFile],
+) -> Iterator[ConversationRow]:
+    for conversation in conversations:
+        yield ConversationRow(
+            ctx_binding_id=binding_id,
+            ctx_source_updated_at=conversation.file_mtime,
+            jsonl_stem=conversation.conversation_id,
+            project_dir=conversation.project,
+            jsonl_parent_dir=conversation.parent_conversation_id or "",
+            jsonl_path=conversation.file_path,
+            jsonl_mtime=conversation.file_mtime,
+            user_message_count=conversation.user_message_count,
+            assistant_message_count=conversation.assistant_message_count,
+        )
+
+
+def lines_to_ctx_models(
+    *,
+    binding_id: str,
+    conversations: Iterable[ParsedConversationFile],
+) -> Iterator[LineRow]:
+    for conversation in conversations:
+        for line in conversation.lines:
+            yield LineRow(
+                ctx_binding_id=binding_id,
+                ctx_source_updated_at=line.timestamp,
+                project_dir=conversation.project,
+                jsonl_stem=conversation.conversation_id,
+                jsonl_parent_dir=conversation.parent_conversation_id or "",
+                line_index=line.line_index,
+                type=line.type,
+                subtype=line.subtype,
+                uuid=line.uuid,
+                parent_uuid=line.parent_uuid,
+                timestamp=line.timestamp,
+                session_id=line.session_id,
+                version=line.version,
+                cwd=line.cwd,
+                raw_line=line.raw_line,
+                # payload is the queryable parsed JSON form of the source line, not
+                # a byte-perfect mirror. Keep raw_line when exact decoded line text
+                # matters, especially for malformed JSON or embedded \\u0000 cases.
+                payload=(
+                    _strip_null_bytes(line.payload)
+                    if line.payload is not None
+                    else None
+                ),
+                parse_error=line.parse_error,
+                turn_projection_error=line.turn_projection_error,
+            )
+
+
+def _user_turn_to_ctx_model(
+    *,
+    binding_id: str,
+    conversation: ParsedConversationFile,
+    turn: ClaudeUserTurnIngress,
+    line_index: int,
+) -> TurnRow:
+    # claude_local.turn is a projection, not a source rewrite. Preserve message,
+    # tool_use_result, and turn_extra shapes as-is apart from null-byte stripping.
+    return TurnRow(
+        ctx_binding_id=binding_id,
+        ctx_source_updated_at=turn.timestamp,
+        project_dir=conversation.project,
+        jsonl_stem=conversation.conversation_id,
+        jsonl_parent_dir=conversation.parent_conversation_id or "",
+        line_index=line_index,
+        type=turn.type,
+        uuid=turn.uuid,
+        parent_uuid=turn.parent_uuid,
+        timestamp=turn.timestamp,
+        is_sidechain=turn.is_sidechain,
+        user_type=turn.user_type,
+        cwd=turn.cwd,
+        session_id=turn.session_id,
+        version=turn.version,
+        git_branch=turn.git_branch,
+        slug=turn.slug,
+        agent_id=turn.agent_id,
+        entrypoint=turn.entrypoint,
+        prompt_id=turn.prompt_id,
+        is_meta=turn.is_meta,
+        tool_use_result=_strip_null_bytes(turn.tool_use_result),
+        source_tool_use_id=turn.source_tool_use_id,
+        source_tool_assistant_uuid=turn.source_tool_assistant_uuid,
+        thinking_metadata=_strip_null_bytes(turn.thinking_metadata),
+        permission_mode=turn.permission_mode,
+        todos=_strip_null_bytes(turn.todos),
+        is_visible_in_transcript_only=turn.is_visible_in_transcript_only,
+        is_compact_summary=turn.is_compact_summary,
+        plan_content=turn.plan_content,
+        message=_strip_null_bytes(turn.message),
+        turn_extra=_strip_null_bytes(turn.turn_extra),
+    )
+
+
+def _assistant_turn_to_ctx_model(
+    *,
+    binding_id: str,
+    conversation: ParsedConversationFile,
+    turn: ClaudeAssistantTurnIngress,
+    line_index: int,
+) -> TurnRow:
+    # Keep assistant message/turn_extra structures raw so new nested Claude fields
+    # survive in the curated transcript table without bespoke translator logic.
+    return TurnRow(
+        ctx_binding_id=binding_id,
+        ctx_source_updated_at=turn.timestamp,
+        project_dir=conversation.project,
+        jsonl_stem=conversation.conversation_id,
+        jsonl_parent_dir=conversation.parent_conversation_id or "",
+        line_index=line_index,
+        type=turn.type,
+        uuid=turn.uuid,
+        parent_uuid=turn.parent_uuid,
+        timestamp=turn.timestamp,
+        is_sidechain=turn.is_sidechain,
+        user_type=turn.user_type,
+        cwd=turn.cwd,
+        session_id=turn.session_id,
+        version=turn.version,
+        git_branch=turn.git_branch,
+        slug=turn.slug,
+        agent_id=turn.agent_id,
+        entrypoint=turn.entrypoint,
+        request_id=turn.request_id,
+        error=turn.error,
+        is_api_error_message=turn.is_api_error_message,
+        api_error=turn.api_error,
+        message=_strip_null_bytes(turn.message),
+        turn_extra=_strip_null_bytes(turn.turn_extra),
+    )
+
+
+def turns_to_ctx_models(
+    *,
+    binding_id: str,
+    conversations: Iterable[ParsedConversationFile],
+) -> Iterator[TurnRow]:
+    for conversation in conversations:
+        for validated in conversation.turns:
+            ingress = validated.ingress
+
+            if isinstance(ingress, ClaudeUserTurnIngress):
+                yield _user_turn_to_ctx_model(
+                    binding_id=binding_id,
+                    conversation=conversation,
+                    turn=ingress,
+                    line_index=validated.line_index,
+                )
+            elif isinstance(ingress, ClaudeAssistantTurnIngress):
+                yield _assistant_turn_to_ctx_model(
+                    binding_id=binding_id,
+                    conversation=conversation,
+                    turn=ingress,
+                    line_index=validated.line_index,
+                )

plugin_claude_local/plugin.json

@@ -0,0 +1,7 @@
+{
+	"auth": {
+		"type": "none"
+	},
+	"mode": "dagster",
+	"plugin_id": "claude_local"
+}

plugin_claude_local/sources/snapshot.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+import dlt
+from shared_plugins.naming import (
+    dlt_resource_name,
+    dlt_source_name,
+    plugin_id_from_module,
+)
+from shared_plugins.resources import ctx_dlt_resource
+
+from ..binding_config import ClaudeLocalBindingConfig
+from ..models.ctx import ConversationRow, LineRow, ProjectRow, TurnRow
+from ..models.translators import (
+    conversations_to_ctx_models,
+    lines_to_ctx_models,
+    projects_to_ctx_models,
+    turns_to_ctx_models,
+)
+from ..utils.parse import scan_claude_snapshot
+
+PLUGIN_ID = plugin_id_from_module(__file__)
+JOB = "snapshot"
+MERGE_WRITE_DISPOSITION = {"disposition": "merge", "strategy": "upsert"}
+
+
+@dlt.source(name=dlt_source_name(PLUGIN_ID, JOB))
+def claude_local_snapshot_source(
+    binding_id: str,
+    cfg: ClaudeLocalBindingConfig,
+) -> tuple[Any, ...]:
+    snapshot = scan_claude_snapshot(cfg.projects_dir)
+
+    @ctx_dlt_resource(
+        name=dlt_resource_name("project"),
+        write_disposition=MERGE_WRITE_DISPOSITION,
+        primary_key=("_ctx_binding_id", "encoded_dir"),
+    )
+    def project_resource() -> Iterator[ProjectRow]:
+        yield from projects_to_ctx_models(
+            binding_id=binding_id,
+            project_dirs=snapshot.project_dirs,
+        )
+
+    @ctx_dlt_resource(
+        name=dlt_resource_name("conversation"),
+        write_disposition=MERGE_WRITE_DISPOSITION,
+        primary_key=(
+            "_ctx_binding_id",
+            "project_dir",
+            "jsonl_parent_dir",
+            "jsonl_stem",
+        ),
+    )
+    def conversation_resource() -> Iterator[ConversationRow]:
+        yield from conversations_to_ctx_models(
+            binding_id=binding_id,
+            conversations=snapshot.conversations,
+        )
+
+    @ctx_dlt_resource(
+        name=dlt_resource_name("line"),
+        write_disposition=MERGE_WRITE_DISPOSITION,
+        primary_key=(
+            "_ctx_binding_id",
+            "project_dir",
+            "jsonl_parent_dir",
+            "jsonl_stem",
+            "line_index",
+        ),
+        columns={
+            "payload": {"data_type": "json"},
+            # These columns are correctness-critical but may be all-null on a clean
+            # corpus. Declare them explicitly so dlt does not omit them when it
+            # cannot infer a type from the current load package.
+            "parse_error": {"data_type": "text"},
+            "turn_projection_error": {"data_type": "text"},
+        },
+    )
+    def line_resource() -> Iterator[LineRow]:
+        yield from lines_to_ctx_models(
+            binding_id=binding_id,
+            conversations=snapshot.conversations,
+        )
+
+    @ctx_dlt_resource(
+        name=dlt_resource_name("turn"),
+        write_disposition=MERGE_WRITE_DISPOSITION,
+        primary_key=(
+            "_ctx_binding_id",
+            "project_dir",
+            "jsonl_parent_dir",
+            "jsonl_stem",
+            "line_index",
+        ),
+        columns={
+            # Preserve transcript substructures as JSON so nested Claude drift stays
+            # queryable without creating new relational columns every release.
+            "message": {"data_type": "json"},
+            "tool_use_result": {"data_type": "json"},
+            "thinking_metadata": {"data_type": "json"},
+            "todos": {"data_type": "json"},
+            "turn_extra": {"data_type": "json"},
+        },
+    )
+    def turn_resource() -> Iterator[TurnRow]:
+        yield from turns_to_ctx_models(
+            binding_id=binding_id,
+            conversations=snapshot.conversations,
+        )
+
+    return (
+        project_resource,
+        conversation_resource,
+        line_resource,
+        turn_resource,
+    )

plugin_claude_local/utils/__init__.py

@@ -0,0 +1 @@
+

plugin_claude_local/utils/parse.py

@@ -0,0 +1,420 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+from shared_plugins.models import format_validation_error
+from shared_plugins.values import as_mapping, as_string, parse_utc_datetime_from_str
+
+from ..models.ingress import (
+    ASSISTANT_TRANSCRIPT_SOURCE_KEYS,
+    USER_TRANSCRIPT_SOURCE_KEYS,
+    ClaudeAssistantTurnIngress,
+    ClaudeUserTurnIngress,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ValidatedTurn:
+    line_index: int
+    ingress: ClaudeUserTurnIngress | ClaudeAssistantTurnIngress
+
+
+@dataclass(frozen=True)
+class ParsedLine:
+    line_index: int
+    # The original non-empty JSONL line text with trailing line terminators removed.
+    raw_line: str
+    payload: Any = None
+    parse_error: str | None = None
+    type: str | None = None
+    subtype: str | None = None
+    uuid: str | None = None
+    parent_uuid: str | None = None
+    timestamp: datetime | None = None
+    session_id: str | None = None
+    version: str | None = None
+    cwd: str | None = None
+    turn_projection_error: str | None = None
+    turn: ValidatedTurn | None = None
+
+
+@dataclass(frozen=True)
+class ConversationFileRef:
+    file_path: str
+    project: str
+    conversation_id: str
+    parent_conversation_id: str | None
+
+
+@dataclass(frozen=True)
+class ParsedConversationFile:
+    file_path: str
+    project: str
+    conversation_id: str
+    parent_conversation_id: str | None
+    file_mtime: datetime | None
+    lines: list[ParsedLine]
+    turns: list[ValidatedTurn]
+    user_message_count: int
+    assistant_message_count: int
+
+
+@dataclass(frozen=True)
+class ParsedClaudeSnapshot:
+    project_dirs: list[str]
+    conversations: list[ParsedConversationFile]
+
+
+def parse_json_line(line: str) -> tuple[Any | None, str | None]:
+    try:
+        return json.loads(line), None
+    except json.JSONDecodeError as exc:
+        return None, f"invalid_json: {exc.msg} (column {exc.colno})"
+
+
+def get_file_mtime(file_path: str) -> datetime | None:
+    try:
+        stat_result = Path(file_path).stat()
+    except OSError:
+        return None
+    return datetime.fromtimestamp(stat_result.st_mtime, tz=timezone.utc)
+
+
+def _read_jsonl_lines(file_path: str) -> list[tuple[int, str]] | None:
+    """Read non-empty JSONL lines as text.
+
+    This preserves the original decoded line contents, but strips trailing CR/LF
+    terminators and skips blank lines. It is therefore a canonical JSONL-line
+    capture, not a byte-for-byte file mirror.
+    """
+    lines: list[tuple[int, str]] = []
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as handle:
+            for line_index, raw_line in enumerate(handle):
+                line = raw_line.rstrip("\n").rstrip("\r")
+                if not line.strip():
+                    continue
+                lines.append((line_index, line))
+    except (OSError, UnicodeError):
+        return None
+
+    return lines
+
+
+def _extract_timestamp(value: object) -> datetime | None:
+    timestamp_raw = as_string(value)
+    if timestamp_raw is None:
+        return None
+
+    try:
+        return parse_utc_datetime_from_str(timestamp_raw)
+    except (TypeError, ValueError):
+        return None
+
+
+def _build_projection_payload(
+    raw: dict[str, Any],
+    *,
+    source_keys: frozenset[str],
+) -> dict[str, Any]:
+    # Split the raw transcript line into promoted turn columns and durable
+    # top-level drift. This is the seam that lets ingress stay strict without
+    # pretending Claude's full top-level shape is stable.
+    prepared = {key: value for key, value in raw.items() if key in source_keys}
+    turn_extra = {key: value for key, value in raw.items() if key not in source_keys}
+    if turn_extra:
+        prepared["turn_extra"] = turn_extra
+    return prepared
+
+
+def _validate_projection_model(
+    raw: dict[str, Any],
+    *,
+    file_path: str,
+    line_index: int,
+    source_keys: frozenset[str],
+    model_type: type[ClaudeUserTurnIngress] | type[ClaudeAssistantTurnIngress],
+) -> tuple[ValidatedTurn | None, str | None]:
+    prepared = _build_projection_payload(raw, source_keys=source_keys)
+
+    try:
+        ingress = model_type.model_validate(prepared)
+    except ValidationError as exc:
+        error = format_validation_error(exc)
+        LOGGER.warning(
+            "claude_local.turn_projection_failed type=%s file=%s line=%d error=%s raw=%s",
+            raw.get("type"),
+            file_path,
+            line_index,
+            error,
+            json.dumps(raw, default=str, ensure_ascii=False)[:2000],
+        )
+        return None, error
+
+    return ValidatedTurn(line_index=line_index, ingress=ingress), None
+
+
+def _project_transcript_turn(
+    raw: dict[str, Any],
+    *,
+    file_path: str,
+    line_index: int,
+) -> tuple[ValidatedTurn | None, str | None]:
+    # Only user/assistant lines participate in the curated transcript surface.
+    # Every other top-level Claude line type still lands in claude_local.line.
+    line_type = as_string(raw.get("type"))
+
+    if line_type == "user":
+        return _validate_projection_model(
+            raw,
+            file_path=file_path,
+            line_index=line_index,
+            source_keys=USER_TRANSCRIPT_SOURCE_KEYS,
+            model_type=ClaudeUserTurnIngress,
+        )
+
+    if line_type == "assistant":
+        return _validate_projection_model(
+            raw,
+            file_path=file_path,
+            line_index=line_index,
+            source_keys=ASSISTANT_TRANSCRIPT_SOURCE_KEYS,
+            model_type=ClaudeAssistantTurnIngress,
+        )
+
+    return None, None
+
+
+def _build_line(
+    *,
+    raw_line: str,
+    payload: Any,
+    parse_error: str | None,
+    file_path: str,
+    line_index: int,
+) -> ParsedLine:
+    payload_mapping = as_mapping(payload)
+    line_type = as_string(payload_mapping.get("type")) if payload_mapping else None
+
+    turn: ValidatedTurn | None = None
+    turn_projection_error: str | None = None
+    if payload_mapping is not None:
+        turn, turn_projection_error = _project_transcript_turn(
+            dict(payload_mapping),
+            file_path=file_path,
+            line_index=line_index,
+        )
+
+    return ParsedLine(
+        line_index=line_index,
+        raw_line=raw_line,
+        payload=payload,
+        parse_error=parse_error,
+        type=line_type,
+        subtype=(
+            as_string(payload_mapping.get("subtype")) if payload_mapping else None
+        ),
+        uuid=as_string(payload_mapping.get("uuid")) if payload_mapping else None,
+        parent_uuid=(
+            as_string(payload_mapping.get("parentUuid")) if payload_mapping else None
+        ),
+        timestamp=(
+            _extract_timestamp(payload_mapping.get("timestamp"))
+            if payload_mapping
+            else None
+        ),
+        session_id=(
+            as_string(payload_mapping.get("sessionId")) if payload_mapping else None
+        ),
+        version=as_string(payload_mapping.get("version")) if payload_mapping else None,
+        cwd=as_string(payload_mapping.get("cwd")) if payload_mapping else None,
+        turn_projection_error=turn_projection_error,
+        turn=turn,
+    )
+
+
+def list_project_dirs(projects_dir: Path) -> list[str]:
+    try:
+        if not projects_dir.is_dir():
+            return []
+    except OSError:
+        return []
+
+    project_dirs: list[str] = []
+    try:
+        entries = list(os.scandir(projects_dir))
+    except OSError:
+        return []
+
+    for entry in entries:
+        try:
+            if entry.is_dir(follow_symlinks=False):
+                project_dirs.append(entry.name)
+        except OSError:
+            continue
+
+    project_dirs.sort()
+    return project_dirs
+
+
+def _list_project_conversation_file_refs(
+    projects_path: Path,
+    project: str,
+) -> list[ConversationFileRef]:
+    project_dir = projects_path / project
+
+    try:
+        entries = list(os.scandir(project_dir))
+    except OSError:
+        LOGGER.warning(
+            "claude_local.skipped_project reason=%s project_dir=%s",
+            "unreadable_project_dir",
+            project_dir,
+        )
+        return []
+
+    refs: list[ConversationFileRef] = []
+    parent_candidates: list[str] = []
+
+    for entry in entries:
+        try:
+            if entry.is_file(follow_symlinks=False) and entry.name.lower().endswith(
+                ".jsonl"
+            ):
+                conversation_id = Path(entry.name).stem
+                if not conversation_id:
+                    continue
+                refs.append(
+                    ConversationFileRef(
+                        file_path=entry.path,
+                        project=project,
+                        conversation_id=conversation_id,
+                        parent_conversation_id=None,
+                    )
+                )
+            elif entry.is_dir(follow_symlinks=False):
+                parent_candidates.append(entry.name)
+        except OSError:
+            continue
+
+    for parent_conversation_id in sorted(parent_candidates):
+        subagents_dir = project_dir / parent_conversation_id / "subagents"
+        try:
+            if not subagents_dir.is_dir():
+                continue
+        except OSError:
+            continue
+
+        try:
+            subagent_entries = list(os.scandir(subagents_dir))
+        except OSError:
+            LOGGER.warning(
+                "claude_local.skipped_subagents_dir reason=%s subagents_dir=%s",
+                "unreadable_subagents_dir",
+                subagents_dir,
+            )
+            continue
+
+        for subagent_entry in subagent_entries:
+            try:
+                if not subagent_entry.is_file(follow_symlinks=False):
+                    continue
+                if not subagent_entry.name.lower().endswith(".jsonl"):
+                    continue
+            except OSError:
+                continue
+
+            conversation_id = Path(subagent_entry.name).stem
+            if not conversation_id:
+                continue
+
+            refs.append(
+                ConversationFileRef(
+                    file_path=subagent_entry.path,
+                    project=project,
+                    conversation_id=conversation_id,
+                    parent_conversation_id=parent_conversation_id,
+                )
+            )
+
+    refs.sort(key=lambda ref: ref.file_path)
+    return refs
+
+
+def list_conversation_file_refs(
+    projects_dir: Path,
+    project_dirs: list[str],
+) -> list[ConversationFileRef]:
+    refs: list[ConversationFileRef] = []
+    for project in project_dirs:
+        refs.extend(_list_project_conversation_file_refs(projects_dir, project))
+    refs.sort(key=lambda ref: ref.file_path)
+    return refs
+
+
+def scan_claude_snapshot(projects_dir: Path) -> ParsedClaudeSnapshot:
+    project_dirs = list_project_dirs(projects_dir)
+    file_refs = list_conversation_file_refs(projects_dir, project_dirs)
+
+    conversations: list[ParsedConversationFile] = []
+    for file_ref in file_refs:
+        raw_lines = _read_jsonl_lines(file_ref.file_path)
+        if raw_lines is None:
+            LOGGER.warning(
+                "claude_local.skipped_file reason=%s file_path=%s project=%s conversation_id=%s",
+                "unreadable_file",
+                file_ref.file_path,
+                file_ref.project,
+                file_ref.conversation_id,
+            )
+            continue
+
+        lines: list[ParsedLine] = []
+        turns: list[ValidatedTurn] = []
+        user_message_count = 0
+        assistant_message_count = 0
+
+        for line_index, raw_line in raw_lines:
+            payload, parse_error = parse_json_line(raw_line)
+            line = _build_line(
+                raw_line=raw_line,
+                payload=payload,
+                parse_error=parse_error,
+                file_path=file_ref.file_path,
+                line_index=line_index,
+            )
+            lines.append(line)
+
+            if line.type == "user":
+                user_message_count += 1
+            elif line.type == "assistant":
+                assistant_message_count += 1
+
+            if line.turn is not None:
+                turns.append(line.turn)
+
+        conversations.append(
+            ParsedConversationFile(
+                file_path=file_ref.file_path,
+                project=file_ref.project,
+                conversation_id=file_ref.conversation_id,
+                parent_conversation_id=file_ref.parent_conversation_id,
+                file_mtime=get_file_mtime(file_ref.file_path),
+                lines=lines,
+                turns=turns,
+                user_message_count=user_message_count,
+                assistant_message_count=assistant_message_count,
+            )
+        )
+
+    return ParsedClaudeSnapshot(project_dirs=project_dirs, conversations=conversations)