← Files ClaraARCHIVED FILE

scripts/clara_studio_archive.py

7.08 KB · Nov 21, 2026 · 00:11 UTC

↓ Download file

See the change to this file →

"""Bind Clara's existing advisory workspace to one shared Archive engagement."""

from __future__ import annotations

import json
import os
import sys
from pathlib import Path
from typing import Any

ROOT = Path(__file__).resolve().parents[1]
COMPONENT = ROOT / "modules/studio-archive"
if not COMPONENT.is_dir():
    COMPONENT = ROOT.parent / "studio-archive"
sys.path.insert(0, str(COMPONENT / "scripts"))

import archive_core as archive
import client_ledger as ledger
from advisor_case_core import initialize_case, load_case_file, validate_case_workspace
from case_store import atomic_text, transaction

__all__ = ["open_case", "main"]
BINDING = "clara_archive_binding.json"


def _read(path: Path) -> dict[str, Any]:
    if path.is_symlink():
        raise ValueError("Archive binding cannot be a symbolic link.")
    value = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(value, dict):
        raise ValueError("Invalid Clara Archive binding.")
    return value


def open_case(
    client_id: str,
    engagement_id: str,
    *,
    case_dir: str | None = None,
    objective: str | None = None,
    audience: str = "Decision maker",
    output_language: str = "it",
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Create or resume one case, preserving existing folders and client ownership."""
    folder = archive.get_studio_client_folder(client_id, state_dir=state_dir)[
        "client_folder"
    ]
    root = Path(folder["client_root"])
    engagement = ledger.load_engagement_manifest(root, engagement_id)
    engagement_root = ledger._engagement_root(root, engagement_id)
    identity = {
        "schema_version": "clara.archive_case.v1",
        "client_id": client_id,
        "engagement_id": engagement_id,
    }
    with transaction(engagement_root):
        pointer = engagement_root / BINDING
        saved = _read(pointer) if pointer.exists() or pointer.is_symlink() else None
        if saved is not None and any(saved.get(k) != v for k, v in identity.items()):
            raise ValueError("Case binding belongs to another client or engagement.")
        if saved is not None:
            stored = Path(saved["case_path"])
            if (
                not stored.is_absolute()
                and ".." not in stored.parts
                and len(stored.parts) >= 4
                and stored.parts[0].casefold() in ledger.PRODUCT_DIRECTORIES
                and stored.parts[1:3] == ("engagements", engagement_id)
            ):
                # Retain the original binding bytes after a verified product move.
                target = engagement_root.joinpath(*stored.parts[3:])
            else:
                target = root / stored if not stored.is_absolute() else stored
            if case_dir is not None and Path(case_dir).resolve() != target.resolve():
                raise ValueError(
                    "This engagement already has a case; preserve its folder."
                )
        elif case_dir is not None:
            target = Path(case_dir)
            if not target.is_absolute():
                raise ValueError("Select an absolute existing case folder.")
            if not (target / "case_manifest.json").is_file():
                raise ValueError("The selected existing case has no case manifest.")
        else:
            target = engagement_root / "clara-case"
        if any(part.is_symlink() for part in (target, *target.parents)):
            raise ValueError("Case folder cannot traverse symbolic links.")
        target = target.resolve()
        # An explicit legacy path is permitted, but never inside another client.
        for parent in (target, *target.parents):
            if (parent / ledger.LEDGER_DIRECTORY / "client.json").exists():
                if ledger.load_client_manifest(parent)["client_id"] != client_id:
                    raise ValueError("Case folder belongs to another Archive client.")
                break
        if saved is not None and not (target / "case_manifest.json").is_file():
            raise ValueError(
                "Bound case folder is unavailable; restore it before resuming."
            )
        is_existing = (target / "case_manifest.json").is_file()
        if not is_existing and not objective:
            raise ValueError("Supply the assignment objective to create a new case.")
        with transaction(target):
            marker = target / BINDING
            if marker.exists() or marker.is_symlink():
                if _read(marker) != identity:
                    raise ValueError(
                        "Case is already bound to another client or engagement."
                    )
            elif saved is not None:
                raise ValueError(
                    "Bound case identity is missing; do not adopt a replacement folder."
                )
            if is_existing:
                errors = validate_case_workspace(target)
                if errors:
                    raise ValueError("; ".join(errors))
                manifest = load_case_file(target, "manifest")
            else:
                if engagement["status"] != "open":
                    raise ValueError("Select an open engagement for a new case.")
                manifest = initialize_case(
                    target,
                    client=folder["display_name"],
                    project=engagement["label"],
                    objective=objective,
                    audience=audience,
                    output_language=output_language,
                )
            atomic_text(marker, json.dumps(identity, indent=2) + "\n")
            try:
                stored_path = str(target.relative_to(root))
            except ValueError:
                stored_path = str(target)
            if saved is None:
                atomic_text(
                    pointer,
                    json.dumps({**identity, "case_path": stored_path}, indent=2) + "\n",
                )
    return {
        "status": "resumed" if is_existing else "created",
        **identity,
        "case_dir": str(target),
        "case_manifest": manifest,
        "case_brief": str(target / "case_brief.md"),
        "data_handling": {
            "local_reads": "Selected client identity, engagement manifest and Clara case state",
            "model_context": "Selected case path and case manifest; source documents are not returned",
            "network_requests": 0,
        },
    }


def main() -> int:
    """Serve one JSON request through the installed local MCP bridge."""
    os.environ["CLARA_ARCHIVE_HOST"] = "1"
    try:
        request = json.load(sys.stdin)
        if not isinstance(request, dict) or "state_dir" in request:
            raise ValueError("Invalid case request.")
        result = open_case(**request)
    except (
        ValueError,
        OSError,
        TypeError,
        KeyError,
        archive.ArchiveError,
        ledger.LedgerError,
    ) as exc:
        sys.stdout.write(
            json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False)
            + "\n"
        )
        return 1
    sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

SHA-256: cd24fa15c2a28892caf9224c5541e262fb3eef5f78a6fa30dd48ca5b46cbf61d