msdev 0.9.0__py3-none-any.whl

msdev/session/__init__.py

@@ -0,0 +1,13 @@
+"""Safe logging and export of explicit msdev CLI sessions."""
+
+from .export import iter_events, list_sessions, render_markdown
+from .log import CliOperationLogger, CliSession, begin_session
+
+__all__ = [
+    "CliOperationLogger",
+    "CliSession",
+    "begin_session",
+    "iter_events",
+    "list_sessions",
+    "render_markdown",
+]

msdev/session/export.py

@@ -0,0 +1,190 @@
+"""Discovery and Markdown export for CLI operation sessions."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Iterator, Mapping, Sequence
+
+from .log import (
+    MAX_LOG_LINE_BYTES,
+    SCHEMA_VERSION,
+    session_directory,
+    session_path,
+)
+
+
+@dataclass(frozen=True)
+class SessionInfo:
+    name: str
+    size: int
+    mtime_ns: int
+    path: Path
+
+
+def session_log_location(
+    environ: Mapping[str, str] | None = None,
+) -> Path:
+    return session_directory(environ)
+
+
+def list_sessions(state_dir: str | os.PathLike[str]) -> list[SessionInfo]:
+    directory = Path(state_dir)
+    if not directory.is_dir():
+        return []
+    result = []
+    for path in directory.glob("*.jsonl"):
+        try:
+            info = path.stat()
+        except OSError:
+            continue
+        if path.is_symlink() or not path.is_file():
+            continue
+        result.append(SessionInfo(path.stem, info.st_size, info.st_mtime_ns, path))
+    return sorted(result, key=lambda item: (item.mtime_ns, item.name), reverse=True)
+
+
+def resolve_session_sources(
+    *,
+    latest: bool,
+    inputs: Sequence[Path],
+    session_id: str | None = None,
+    state_dir: Path | None = None,
+) -> list[Path]:
+    if inputs:
+        return [Path(path).expanduser().resolve(strict=True) for path in inputs]
+    if latest:
+        sessions = list_sessions(state_dir or session_log_location())
+        if not sessions:
+            raise ValueError("no CLI session logs found")
+        return [sessions[0].path]
+    if session_id:
+        path = session_path(session_id)
+        if not path.is_file():
+            raise ValueError(f"unknown msdev session: {session_id}")
+        return [path]
+    raise ValueError("select --input, --latest, or --session-id")
+
+
+def reject_output_alias(output: Path, sources: Sequence[Path]) -> None:
+    candidate = output.expanduser().resolve(strict=False)
+    if any(candidate == source.resolve(strict=True) for source in sources):
+        raise ValueError("output must not overwrite an input session log")
+
+
+def write_markdown_atomic(output: Path, chunks: Iterable[str]) -> None:
+    destination = output.expanduser()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(
+        prefix=f".{destination.name}.",
+        dir=destination.parent,
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            for chunk in chunks:
+                handle.write(chunk)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, destination)
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _valid_event(value: Any) -> bool:
+    return (
+        isinstance(value, dict)
+        and value.get("schema_version") == SCHEMA_VERSION
+        and isinstance(value.get("session_id"), str)
+        and isinstance(value.get("operation_id"), str)
+        and isinstance(value.get("command"), str)
+        and isinstance(value.get("argv"), list)
+        and all(isinstance(item, str) for item in value["argv"])
+        and isinstance(value.get("exit_code"), int)
+        and not isinstance(value.get("exit_code"), bool)
+    )
+
+
+def iter_events(sources: Sequence[Path]) -> Iterator[dict[str, Any]]:
+    for source in sources:
+        with source.open("rb") as handle:
+            for raw in handle:
+                if len(raw) > MAX_LOG_LINE_BYTES:
+                    continue
+                try:
+                    value = json.loads(raw)
+                except (UnicodeDecodeError, json.JSONDecodeError):
+                    continue
+                if _valid_event(value):
+                    yield value
+
+
+def _command(event: dict[str, Any]) -> str:
+    return "msdev " + shlex.join(event["argv"])
+
+
+def _entry(event: dict[str, Any], detail: str) -> Iterator[str]:
+    intent = event.get("intent") if isinstance(event.get("intent"), dict) else {}
+    summary = intent.get("summary") or event["command"]
+    yield f"### {summary}\n"
+    preview = event.get("preview")
+    if isinstance(preview, str):
+        yield f"{preview}\n\n"
+    yield "```bash\n"
+    yield _command(event) + "\n"
+    yield "```\n"
+    yield (
+        f"Exit: `{event['exit_code']}`; elapsed: "
+        f"`{event.get('elapsed_ms', 0)} ms`.\n\n"
+    )
+    if detail == "full":
+        yield "```json\n"
+        yield json.dumps(event, ensure_ascii=False, indent=2, sort_keys=True)
+        yield "\n```\n\n"
+
+
+def render_markdown(
+    events: Iterable[dict[str, Any]],
+    detail: str,
+) -> Iterator[str]:
+    if detail not in {"brief", "normal", "full"}:
+        raise ValueError(f"unsupported detail: {detail}")
+    groups: dict[str, list[dict[str, Any]]] = {
+        "execution": [],
+        "verification": [],
+        "other": [],
+    }
+    for event in events:
+        intent = event.get("intent")
+        kind = intent.get("kind") if isinstance(intent, dict) else None
+        if kind == "execution":
+            groups["execution"].append(event)
+        elif kind == "verification":
+            groups["verification"].append(event)
+        else:
+            groups["other"].append(event)
+
+    yield "# msdev CLI session runbook\n\n"
+    sections = (
+        ("Core reproduction steps", groups["execution"]),
+        ("Optional verification", groups["verification"]),
+        ("Diagnostics and exploration", groups["other"]),
+    )
+    for title, values in sections:
+        if not values:
+            continue
+        yield f"## {title}\n\n"
+        if detail == "brief":
+            for event in values:
+                yield f"- `{_command(event)}` (exit {event['exit_code']})\n"
+            yield "\n"
+        else:
+            for event in values:
+                yield from _entry(event, detail)

msdev/session/log.py

@@ -0,0 +1,269 @@
+"""Secure, process-safe CLI operation session logging."""
+
+from __future__ import annotations
+
+import datetime as dt
+import fcntl
+import json
+import os
+import re
+import shlex
+import time
+import urllib.parse
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+
+SCHEMA_VERSION = 1
+MAX_LOG_LINE_BYTES = 16 * 1024
+INTENT_KINDS = frozenset(
+    {"execution", "verification", "diagnostic", "exploration"}
+)
+_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+_SENSITIVE_RE = re.compile(
+    r"(?:token|password|passwd|secret|api[_-]?key|authorization|credential)",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class CliSession:
+    session_id: str
+    path: Path
+
+
+def session_directory(
+    environ: Mapping[str, str] | None = None,
+) -> Path:
+    env = os.environ if environ is None else environ
+    state_home = env.get("XDG_STATE_HOME")
+    base = (
+        Path(state_home).expanduser()
+        if state_home
+        else Path(env.get("HOME", "~")).expanduser() / ".local" / "state"
+    )
+    return base / "msdev" / "sessions"
+
+
+def validate_session_id(value: str) -> str:
+    if not isinstance(value, str) or not _SESSION_ID_RE.fullmatch(value):
+        raise ValueError(
+            "session_id must use 1-128 ASCII letters, digits, '.', '_' or '-'"
+        )
+    return value
+
+
+def session_path(
+    session_id: str,
+    *,
+    environ: Mapping[str, str] | None = None,
+) -> Path:
+    return session_directory(environ) / f"{validate_session_id(session_id)}.jsonl"
+
+
+def _slug(value: str | None) -> str:
+    normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", (value or "session")).strip(
+        ".-"
+    )
+    return (normalized or "session")[:48]
+
+
+def begin_session(
+    name: str | None = None,
+    *,
+    environ: Mapping[str, str] | None = None,
+) -> CliSession:
+    timestamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    session_id = f"{timestamp}-{_slug(name)}-{uuid.uuid4().hex[:8]}"
+    path = session_path(session_id, environ=environ)
+    path.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(path, flags, 0o600)
+    os.close(descriptor)
+    return CliSession(session_id, path)
+
+
+def _clip(value: Any, maximum: int) -> str:
+    raw = str(value).encode("utf-8", errors="replace")[:maximum]
+    return raw.decode("utf-8", errors="ignore")
+
+
+def _sanitize_argument(value: str) -> str:
+    if "=" in value:
+        key, separator, item = value.partition("=")
+        if separator and _SENSITIVE_RE.search(key):
+            return f"{key}=<redacted>"
+        if key and key.upper() == key and len(key) <= 128:
+            return f"{key}=<redacted>"
+    if "://" in value:
+        try:
+            parsed = urllib.parse.urlsplit(value)
+            hostname = parsed.hostname or ""
+            if parsed.port is not None:
+                hostname = f"{hostname}:{parsed.port}"
+            return urllib.parse.urlunsplit(
+                (parsed.scheme, hostname, parsed.path, "", "")
+            )
+        except ValueError:
+            return "<redacted-url>"
+    return _clip(value, 1024)
+
+
+def sanitize_argv(argv: Sequence[str]) -> list[str]:
+    retained: list[str] = []
+    redact_next = False
+    for raw in list(argv)[:256]:
+        value = str(raw)
+        if redact_next:
+            if "=" in value:
+                key = value.partition("=")[0]
+                retained.append(f"{key}=<redacted>")
+            else:
+                retained.append("<redacted>")
+            redact_next = False
+            continue
+        retained.append(_sanitize_argument(value))
+        flag = value.lstrip("-").replace("-", "_")
+        if value in {"--env-var", "--content"} or _SENSITIVE_RE.search(flag):
+            redact_next = True
+    return retained
+
+
+def sanitize_intent(value: Mapping[str, Any] | None) -> dict[str, str] | None:
+    if not value:
+        return None
+    kind = value.get("kind")
+    if kind not in INTENT_KINDS:
+        raise ValueError(f"invalid intent kind: {kind!r}")
+    result = {"kind": str(kind)}
+    for key, limit in (("summary", 256), ("phase", 64), ("step_id", 64)):
+        item = value.get(key)
+        if item is not None:
+            if not isinstance(item, str) or not item.strip():
+                raise ValueError(f"intent {key} must be a non-empty string")
+            text = _clip(item.strip(), limit)
+            text = re.sub(
+                r"(?i)(token|password|secret|api[_-]?key)\s*=\s*\S+",
+                r"\1=<redacted>",
+                text,
+            )
+            result[key] = text
+    return result
+
+
+def _preview(
+    command: str,
+    argv: list[str],
+    node: str | None,
+    environment: str | None,
+    workspace: str | None,
+    intent: dict[str, str] | None,
+) -> str:
+    subject = environment or node or workspace or "-"
+    summary = intent.get("summary", "未提供意图") if intent else "未提供意图"
+    kind = intent["kind"] if intent else "unspecified"
+    detail = shlex.join(argv)
+    return _clip(
+        f"【{command} · {subject}】【{summary}】【{kind}】 {detail}",
+        1024,
+    )
+
+
+class CliOperationLogger:
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        environ: Mapping[str, str] | None = None,
+    ):
+        self.session_id = validate_session_id(session_id)
+        self.path = session_path(session_id, environ=environ)
+        if not self.path.is_file():
+            raise FileNotFoundError(f"unknown msdev session: {session_id}")
+
+    def record(
+        self,
+        *,
+        argv: Sequence[str],
+        command: str,
+        exit_code: int,
+        elapsed_ms: float,
+        node: str | None = None,
+        environment: str | None = None,
+        workspace: str | None = None,
+        intent: Mapping[str, Any] | None = None,
+    ) -> str:
+        operation_id = uuid.uuid4().hex
+        safe_argv = sanitize_argv(argv)
+        safe_intent = sanitize_intent(intent)
+        event: dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "timestamp": dt.datetime.now(dt.timezone.utc)
+            .isoformat(timespec="milliseconds")
+            .replace("+00:00", "Z"),
+            "session_id": self.session_id,
+            "operation_id": operation_id,
+            "command": _clip(command, 128),
+            "argv": safe_argv,
+            "preview": _preview(
+                command,
+                safe_argv,
+                node,
+                environment,
+                workspace,
+                safe_intent,
+            ),
+            "exit_code": int(exit_code),
+            "elapsed_ms": max(0.0, round(float(elapsed_ms), 3)),
+        }
+        if node:
+            event["node"] = _clip(node, 128)
+        if environment:
+            event["environment"] = _clip(environment, 128)
+        if workspace:
+            event["workspace"] = _clip(workspace, 128)
+        if safe_intent:
+            event["intent"] = safe_intent
+        line = (
+            json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
+        ).encode("utf-8")
+        if len(line) > MAX_LOG_LINE_BYTES:
+            event["truncated"] = True
+            for count in (16, 8, 4, 0):
+                event["argv"] = safe_argv[:count]
+                line = (
+                    json.dumps(
+                        event,
+                        ensure_ascii=False,
+                        separators=(",", ":"),
+                    )
+                    + "\n"
+                ).encode("utf-8")
+                if len(line) <= MAX_LOG_LINE_BYTES:
+                    break
+            else:
+                raise ValueError("CLI operation log event exceeds byte budget")
+        flags = os.O_WRONLY | os.O_APPEND
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        descriptor = os.open(self.path, flags)
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX)
+            offset = 0
+            while offset < len(line):
+                offset += os.write(descriptor, line[offset:])
+        finally:
+            try:
+                fcntl.flock(descriptor, fcntl.LOCK_UN)
+            finally:
+                os.close(descriptor)
+        return operation_id
+
+
+def monotonic_ms(started: float) -> float:
+    return (time.monotonic() - started) * 1000.0