create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/prime/egregore_runtime/issue_cli.py

@@ -0,0 +1,305 @@
+"""Runtime-neutral CLI for canonical issues and explicit external sharing."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import UTC, datetime, timedelta
+import hashlib
+import json
+import os
+from pathlib import Path
+import secrets
+import subprocess
+import sys
+from uuid import uuid4
+
+from .contracts import Permission
+from .issues import CanonicalIssueService, IssueSnapshot
+from .policy import scope_allows_path
+from .runtime import local_runtime
+
+
+SHARE_CONSENT_SECONDS = 600
+
+
+def _context():
+    root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
+    runtime = local_runtime(root, push_remote=os.environ.get("EGREGORE_NO_PUSH") != "1")
+    actor = runtime.resolve_actor(
+        session_id=os.environ.get("EGREGORE_SESSION_ID", f"session_{uuid4().hex}"),
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    service = CanonicalIssueService(
+        memory_root=(root / "memory").resolve(),
+        write_document=runtime.write_document,
+    )
+    return root, runtime, actor, service
+
+
+def _require(runtime, actor, permission: Permission, *resources: str):
+    decision = runtime.authorize(actor, permission, tuple(resources))
+    if not decision.allowed:
+        raise PermissionError(
+            "; ".join(decision.reasons) or f"issue {permission.value} denied"
+        )
+    return decision
+
+
+def _require_issue_path(runtime, actor, permission: Permission, issue: IssueSnapshot):
+    decision = _require(
+        runtime, actor, permission, issue.document.artifact.artifact_id
+    )
+    if not scope_allows_path(f"memory/{issue.canonical_path}", decision.scopes):
+        raise PermissionError("issue path is outside the actor's authorized scope")
+    return decision
+
+
+def _snapshot(runtime, actor, service, permission: Permission = Permission.READ):
+    _require(runtime, actor, Permission.DISCOVER, "issues")
+    decision = _require(runtime, actor, permission, "issues")
+    return service.snapshot(actor, authorized_scopes=decision.scopes), decision
+
+
+def _resolve(runtime, actor, service, reference: str) -> IssueSnapshot:
+    rows, _ = _snapshot(runtime, actor)
+    return service.resolve(rows, reference)
+
+
+def _write_result(issue: IssueSnapshot, receipt) -> int:
+    print(json.dumps({"issue": issue.to_dict(), "writeback": receipt.to_dict()}, ensure_ascii=False))
+    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+
+
+def _list(args):
+    _, runtime, actor, service = _context()
+    rows, _ = _snapshot(runtime, actor)
+    selected = rows if args.status == "all" else tuple(
+        row for row in rows if row.status == args.status
+    )
+    print(json.dumps({"issues": [row.to_dict() for row in selected]}, ensure_ascii=False))
+    return 0
+
+
+def _show(args):
+    _, runtime, actor, service = _context()
+    issue = _resolve(runtime, actor, service, args.reference)
+    print(json.dumps({"issue": issue.to_dict(include_body=True)}, ensure_ascii=False))
+    return 0
+
+
+def _search(args):
+    _, runtime, actor, service = _context()
+    rows, _ = _snapshot(runtime, actor)
+    terms = tuple(part for part in args.term.casefold().split() if part)
+
+    def matches(row: IssueSnapshot) -> bool:
+        haystack = " ".join((row.issue_id, row.title, row.body, *row.topics)).casefold()
+        return all(term in haystack for term in terms)
+
+    selected = [row.to_dict() for row in rows if matches(row)][: args.limit]
+    print(json.dumps({"issues": selected}, ensure_ascii=False))
+    return 0
+
+
+def _create(args):
+    _, runtime, actor, service = _context()
+    date = datetime.now(UTC).date().isoformat()
+    prospective = f"memory/knowledge/issues/{date}-{args.title}.md"
+    decision = _require(runtime, actor, Permission.WRITE, "issues:new")
+    if not scope_allows_path(prospective, decision.scopes):
+        # Policies commonly authorize the directory rather than a pre-slugged
+        # filename; test the canonical directory as the stable resource.
+        if not scope_allows_path("memory/knowledge/issues/", decision.scopes):
+            raise PermissionError("issue path is outside the actor's authorized scope")
+    issue, receipt = service.create(
+        actor,
+        title=args.title,
+        description=args.description,
+        recipient=args.recipient,
+        topics=args.topic,
+        context=args.context,
+        suggested_fix=args.suggested_fix,
+    )
+    return _write_result(issue, receipt)
+
+
+def _close(args):
+    _, runtime, actor, service = _context()
+    issue = _resolve(runtime, actor, service, args.reference)
+    _require_issue_path(runtime, actor, Permission.WRITE, issue)
+    closed, receipt = service.close(actor, issue, reason=args.reason)
+    return _write_result(closed, receipt)
+
+
+def _share_state_path(root: Path) -> Path:
+    return root / ".egregore" / "runtime" / "issues" / "share-consent.json"
+
+
+def _share_payload(issue: IssueSnapshot, *, action: str, repo: str | None) -> dict[str, str]:
+    if action == "create":
+        if not repo or "/" not in repo:
+            raise ValueError("GitHub create requires --repo owner/name")
+        return {
+            "action": "create",
+            "destination": f"github:{repo}",
+            "artifact_id": issue.document.artifact.artifact_id,
+            "title": issue.title,
+            "body": issue.body.rstrip(),
+        }
+    if not issue.github_url:
+        raise ValueError("canonical issue has no linked GitHub issue")
+    return {
+        "action": "close",
+        "destination": issue.github_url,
+        "artifact_id": issue.document.artifact.artifact_id,
+        "title": issue.title,
+        "body": "Close the linked GitHub issue.",
+    }
+
+
+def _payload_hash(payload: dict[str, str]) -> str:
+    raw = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _share_preview(args):
+    root, runtime, actor, service = _context()
+    issue = _resolve(runtime, actor, service, args.reference)
+    _require_issue_path(runtime, actor, Permission.SHARE, issue)
+    payload = _share_payload(issue, action=args.action, repo=args.repo)
+    now = datetime.now(UTC)
+    token = secrets.token_hex(24)
+    state = {
+        "token_hash": hashlib.sha256(token.encode("utf-8")).hexdigest(),
+        "payload_hash": _payload_hash(payload),
+        "expires_at": (now + timedelta(seconds=SHARE_CONSENT_SECONDS)).isoformat(),
+        "payload": payload,
+    }
+    path = _share_state_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.parent.chmod(0o700)
+    path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    print(json.dumps({
+        "share_preview": payload,
+        "confirmation_token": token,
+        "expires_at": state["expires_at"],
+        "notice": "No external action has occurred. Confirm this exact unchanged payload separately.",
+    }, ensure_ascii=False))
+    return 0
+
+
+def _confirmed_payload(root: Path, token: str) -> dict[str, str]:
+    path = _share_state_path(root)
+    if not path.is_file():
+        raise PermissionError("share preview is missing; prepare a new preview")
+    state = json.loads(path.read_text(encoding="utf-8"))
+    token_hash = hashlib.sha256(token.encode("utf-8")).hexdigest()
+    if not secrets.compare_digest(str(state.get("token_hash") or ""), token_hash):
+        raise PermissionError("share confirmation token is invalid")
+    expires = datetime.fromisoformat(str(state["expires_at"]).replace("Z", "+00:00"))
+    if datetime.now(UTC) > expires:
+        raise PermissionError("share confirmation expired; prepare a new preview")
+    payload = state.get("payload")
+    if not isinstance(payload, dict) or _payload_hash(payload) != state.get("payload_hash"):
+        raise PermissionError("share payload changed; prepare a new preview")
+    return {str(key): str(value) for key, value in payload.items()}
+
+
+def _share_confirm(args):
+    root, runtime, actor, service = _context()
+    payload = _confirmed_payload(root, args.confirm)
+    issue = _resolve(runtime, actor, service, payload["artifact_id"])
+    _require_issue_path(runtime, actor, Permission.SHARE, issue)
+    if payload["action"] == "create":
+        # Do not perform the external action unless its canonical provenance
+        # link can also be recorded after GitHub succeeds.
+        _require_issue_path(runtime, actor, Permission.WRITE, issue)
+    # Rebuild from current canonical state so the consent cannot outlive a
+    # changed title/body/link.
+    repo = payload["destination"].removeprefix("github:") if payload["action"] == "create" else None
+    current = _share_payload(issue, action=payload["action"], repo=repo)
+    if _payload_hash(current) != _payload_hash(payload):
+        raise PermissionError("canonical issue changed; prepare a new share preview")
+    if payload["action"] == "create":
+        command = [
+            "gh", "issue", "create", "--repo", repo or "",
+            "--title", payload["title"], "--body", payload["body"],
+        ]
+    else:
+        command = ["gh", "issue", "close", payload["destination"]]
+    result = subprocess.run(command, check=False, text=True, capture_output=True)
+    if result.returncode != 0:
+        raise OSError(result.stderr.strip() or "GitHub issue action failed")
+    output = result.stdout.strip()
+    receipt = None
+    if payload["action"] == "create":
+        github_url = next(
+            (line.strip() for line in output.splitlines() if line.strip().startswith("https://github.com/")),
+            output,
+        )
+        issue, receipt = service.link_github(actor, issue, github_url)
+    _share_state_path(root).unlink(missing_ok=True)
+    response: dict[str, object] = {
+        "shared": True,
+        "action": payload["action"],
+        "destination": payload["destination"],
+        "github_output": output,
+        "issue": issue.to_dict(),
+    }
+    if receipt is not None:
+        response["writeback"] = receipt.to_dict()
+    print(json.dumps(response, ensure_ascii=False))
+    return 0
+
+
+def _parser():
+    parser = argparse.ArgumentParser(prog="egregore-issue")
+    commands = parser.add_subparsers(dest="command", required=True)
+    listing = commands.add_parser("list")
+    listing.add_argument("--status", choices=("open", "closed", "all"), default="open")
+    listing.set_defaults(handler=_list)
+    show = commands.add_parser("show")
+    show.add_argument("reference")
+    show.set_defaults(handler=_show)
+    search = commands.add_parser("search")
+    search.add_argument("term")
+    search.add_argument("--limit", type=int, default=10)
+    search.set_defaults(handler=_search)
+    create = commands.add_parser("create")
+    create.add_argument("--title", required=True)
+    create.add_argument("--description", required=True)
+    create.add_argument("--recipient", default="just memory")
+    create.add_argument("--topic", action="append", default=[])
+    create.add_argument("--context")
+    create.add_argument("--suggested-fix")
+    create.set_defaults(handler=_create)
+    close = commands.add_parser("close")
+    close.add_argument("reference")
+    close.add_argument("--reason")
+    close.set_defaults(handler=_close)
+    preview = commands.add_parser("share-preview")
+    preview.add_argument("reference")
+    preview.add_argument("--action", choices=("create", "close"), default="create")
+    preview.add_argument("--repo")
+    preview.set_defaults(handler=_share_preview)
+    confirm = commands.add_parser("share-github")
+    confirm.add_argument("--confirm", required=True)
+    confirm.set_defaults(handler=_share_confirm)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (OSError, PermissionError, ValueError) as exc:
+        print(f"issue: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc

package/runtime/prime/egregore_runtime/issues.py

@@ -0,0 +1,359 @@
+"""Canonical issue lifecycle shared by every harness and deployment mode.
+
+Issue Markdown is authoritative. Graph projection, GitHub publication, and
+notifications consume canonical receipts and never participate in issue state
+resolution.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime
+from pathlib import Path
+import re
+from typing import Any, Callable, Iterable, Sequence
+
+from .artifacts import (
+    ARTIFACT_SCHEMA_VERSION,
+    CanonicalDocument,
+    content_digest,
+    parse_canonical_markdown,
+    split_frontmatter,
+)
+from .contracts import ActorContext, CanonicalArtifact, SourceProvenance, WritebackEvent
+from .policy import scope_allows_path
+
+
+ISSUE_SCHEMA_VERSION = "egregore-issue/v1"
+ISSUE_STATUSES = frozenset({"open", "closed"})
+
+
+def _slug(value: str) -> str:
+    result = re.sub(r"[^a-z0-9]+", "-", value.casefold()).strip("-")[:72]
+    if not result:
+        raise ValueError("issue title must contain a letter or number")
+    return result
+
+
+def _strings(value: Any) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return tuple(part.strip() for part in value.split(",") if part.strip())
+    if isinstance(value, Sequence):
+        return tuple(str(item).strip() for item in value if str(item).strip())
+    raise ValueError("issue topics must be a string or list")
+
+
+@dataclass(frozen=True, slots=True)
+class IssueSnapshot:
+    issue_id: str
+    title: str
+    status: str
+    recipient: str
+    topics: tuple[str, ...]
+    reported_by: str
+    reported_by_actor_id: str | None
+    created_at: str
+    closed_at: str | None
+    github_url: str | None
+    canonical_path: str
+    body: str
+    document: CanonicalDocument
+
+    def to_dict(self, *, include_body: bool = False) -> dict[str, object]:
+        row: dict[str, object] = {
+            "id": self.issue_id,
+            "artifact_id": self.document.artifact.artifact_id,
+            "title": self.title,
+            "status": self.status,
+            "recipient": self.recipient,
+            "topics": list(self.topics),
+            "reported_by": self.reported_by,
+            "reported_by_actor_id": self.reported_by_actor_id,
+            "created_at": self.created_at,
+            "closed_at": self.closed_at,
+            "github_url": self.github_url,
+            "canonical_path": f"memory/{self.canonical_path}",
+        }
+        if include_body:
+            row["body"] = self.body
+        return row
+
+
+def parse_issue_markdown(
+    markdown: str,
+    *,
+    canonical_path: str,
+    org_id: str,
+) -> IssueSnapshot:
+    fields, _ = split_frontmatter(markdown)
+    document = parse_canonical_markdown(
+        markdown,
+        canonical_path=canonical_path,
+        default_org_id=org_id,
+    )
+    status = str(fields.get("status") or document.artifact.status or "open").casefold()
+    if status not in ISSUE_STATUSES:
+        raise ValueError(f"unsupported issue status: {status}")
+    path_id = Path(canonical_path).stem
+    issue_id = str(fields.get("issue_id") or path_id)
+    return IssueSnapshot(
+        issue_id=issue_id,
+        title=document.artifact.title,
+        status=status,
+        recipient=str(fields.get("recipient") or "just memory"),
+        topics=_strings(fields.get("topics")),
+        reported_by=str(fields.get("author") or fields.get("reported_by") or document.artifact.created_by),
+        reported_by_actor_id=(
+            str(fields["reported_by_actor_id"])
+            if fields.get("reported_by_actor_id")
+            else None
+        ),
+        created_at=document.artifact.created_at.isoformat(),
+        closed_at=str(fields["closed_at"]) if fields.get("closed_at") else (
+            str(fields["closed"]) if fields.get("closed") else None
+        ),
+        github_url=str(fields["github_url"]) if fields.get("github_url") else None,
+        canonical_path=canonical_path,
+        body=document.body,
+        document=document,
+    )
+
+
+class CanonicalIssueService:
+    """Resolve and mutate issue state from one authorized canonical snapshot."""
+
+    def __init__(
+        self,
+        *,
+        memory_root: Path,
+        write_document,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        self.memory_root = memory_root.resolve()
+        self.write_document = write_document
+        self.clock = clock or (lambda: datetime.now(UTC))
+
+    def _paths(self) -> Iterable[Path]:
+        directory = self.memory_root / "knowledge" / "issues"
+        if not directory.is_dir():
+            return ()
+        return tuple(sorted(directory.glob("*.md"), reverse=True))
+
+    def snapshot(
+        self,
+        actor: ActorContext,
+        *,
+        authorized_scopes: tuple[str, ...],
+    ) -> tuple[IssueSnapshot, ...]:
+        """Read each authorized canonical source at most once for this operation."""
+
+        rows: list[IssueSnapshot] = []
+        for path in self._paths():
+            relative = path.relative_to(self.memory_root).as_posix()
+            canonical = f"memory/{relative}"
+            if not scope_allows_path(canonical, authorized_scopes):
+                continue
+            rows.append(
+                parse_issue_markdown(
+                    path.read_text(encoding="utf-8"),
+                    canonical_path=relative,
+                    org_id=actor.profile.org_id,
+                )
+            )
+        return tuple(rows)
+
+    @staticmethod
+    def resolve(rows: Sequence[IssueSnapshot], reference: str) -> IssueSnapshot:
+        term = reference.strip().casefold()
+        if not term:
+            raise ValueError("issue reference is required")
+        exact = [
+            row for row in rows
+            if term in {
+                row.issue_id.casefold(),
+                row.document.artifact.artifact_id.casefold(),
+                row.canonical_path.casefold(),
+                f"memory/{row.canonical_path}".casefold(),
+            }
+        ]
+        if len(exact) == 1:
+            return exact[0]
+        matches = [
+            row for row in rows
+            if term in row.issue_id.casefold() or term in row.title.casefold()
+        ]
+        if len(matches) != 1:
+            qualifier = "missing" if not matches else "ambiguous"
+            raise ValueError(f"issue reference is {qualifier}: {reference}")
+        return matches[0]
+
+    def create(
+        self,
+        actor: ActorContext,
+        *,
+        title: str,
+        description: str,
+        recipient: str = "just memory",
+        topics: Sequence[str] = (),
+        context: str | None = None,
+        suggested_fix: str | None = None,
+    ) -> tuple[IssueSnapshot, WritebackEvent]:
+        if not title.strip() or not description.strip():
+            raise ValueError("issue title and description are required")
+        now = self.clock().astimezone(UTC)
+        issue_id = f"{now.date().isoformat()}-{_slug(title)}"
+        relative = f"knowledge/issues/{issue_id}.md"
+        if (self.memory_root / relative).exists():
+            raise ValueError(f"issue already exists: {issue_id}")
+        sections = [f"# {title.strip()}", "", "## Description", "", description.strip()]
+        if context and context.strip():
+            sections.extend(("", "## Context", "", context.strip()))
+        if suggested_fix and suggested_fix.strip():
+            sections.extend(("", "## Suggested Fix", "", suggested_fix.strip()))
+        body = "\n".join(sections) + "\n"
+        digest = content_digest(body)
+        artifact = CanonicalArtifact(
+            schema_version=ARTIFACT_SCHEMA_VERSION,
+            artifact_id=f"issue:{issue_id}",
+            org_id=actor.profile.org_id,
+            artifact_type="issue",
+            title=title.strip(),
+            created_at=now,
+            created_by=actor.actor.actor_id,
+            status="open",
+            canonical_path=relative,
+            revision=f"sha256:{digest[:16]}",
+            content_hash=digest,
+            workstream="issue-tracking",
+            provenance=(
+                SourceProvenance(
+                    source_type="session",
+                    source_id=actor.session_id,
+                    revision=actor.profile.revision,
+                    content_hash=digest,
+                    observed_at=now,
+                    imported_by=actor.actor.actor_id,
+                ),
+            ),
+        )
+        legacy = {
+            "issue_schema": ISSUE_SCHEMA_VERSION,
+            "issue_id": issue_id,
+            "date": now.date().isoformat(),
+            "author": actor.actor.display_name,
+            "reported_by_actor_id": actor.actor.actor_id,
+            "category": "issue",
+            "recipient": recipient.strip() or "just memory",
+            "topics": list(dict.fromkeys(topic.strip() for topic in topics if topic.strip())),
+            "lifecycle_events": [{
+                "action": "created",
+                "actor_id": actor.actor.actor_id,
+                "occurred_at": now.isoformat().replace("+00:00", "Z"),
+            }],
+        }
+        document = CanonicalDocument(
+            artifact=artifact,
+            body=body,
+            policy_hints={"internal": True},
+            legacy_fields=legacy,
+        )
+        receipt = self.write_document(actor, document)
+        return parse_issue_markdown(
+            self._rendered_markdown(document),
+            canonical_path=relative,
+            org_id=actor.profile.org_id,
+        ), receipt
+
+    @staticmethod
+    def _rendered_markdown(document: CanonicalDocument) -> str:
+        # Parsing a newly prepared document only needs its body/envelope fields;
+        # use the shared serializer to avoid a second filesystem read.
+        from .artifacts import render_canonical_markdown
+
+        return render_canonical_markdown(document)
+
+    def close(
+        self,
+        actor: ActorContext,
+        issue: IssueSnapshot,
+        *,
+        reason: str | None = None,
+    ) -> tuple[IssueSnapshot, WritebackEvent]:
+        if issue.status != "open":
+            raise ValueError("only open issues can be closed")
+        now = self.clock().astimezone(UTC)
+        source = issue.document
+        fields = dict(source.legacy_fields)
+        events = list(fields.get("lifecycle_events") or [])
+        events.append({
+            "action": "closed",
+            "actor_id": actor.actor.actor_id,
+            "occurred_at": now.isoformat().replace("+00:00", "Z"),
+            **({"reason": reason.strip()} if reason and reason.strip() else {}),
+        })
+        fields.update({
+            "issue_schema": ISSUE_SCHEMA_VERSION,
+            "issue_id": issue.issue_id,
+            "reported_by_actor_id": issue.reported_by_actor_id or source.artifact.created_by,
+            "closed_at": now.isoformat().replace("+00:00", "Z"),
+            "lifecycle_events": events,
+        })
+        digest = content_digest(source.body)
+        artifact = replace(
+            source.artifact,
+            artifact_type="issue",
+            status="closed",
+            revision=f"sha256:{digest[:16]}:closed",
+            content_hash=digest,
+        )
+        document = CanonicalDocument(
+            artifact=artifact,
+            body=source.body,
+            policy_hints=source.policy_hints,
+            legacy_fields=fields,
+            migrated_from=source.migrated_from,
+            warnings=source.warnings,
+        )
+        receipt = self.write_document(actor, document)
+        return parse_issue_markdown(
+            self._rendered_markdown(document),
+            canonical_path=issue.canonical_path,
+            org_id=actor.profile.org_id,
+        ), receipt
+
+    def link_github(
+        self,
+        actor: ActorContext,
+        issue: IssueSnapshot,
+        github_url: str,
+    ) -> tuple[IssueSnapshot, WritebackEvent]:
+        """Record a separately authorized publication as canonical provenance."""
+
+        if not github_url.strip().startswith("https://github.com/"):
+            raise ValueError("GitHub issue URL is invalid")
+        source = issue.document
+        fields = dict(source.legacy_fields)
+        fields["github_url"] = github_url.strip()
+        events = list(fields.get("lifecycle_events") or [])
+        events.append({
+            "action": "github_linked",
+            "actor_id": actor.actor.actor_id,
+            "occurred_at": self.clock().astimezone(UTC).isoformat().replace("+00:00", "Z"),
+        })
+        fields["lifecycle_events"] = events
+        document = CanonicalDocument(
+            artifact=source.artifact,
+            body=source.body,
+            policy_hints=source.policy_hints,
+            legacy_fields=fields,
+            migrated_from=source.migrated_from,
+            warnings=source.warnings,
+        )
+        receipt = self.write_document(actor, document)
+        return parse_issue_markdown(
+            self._rendered_markdown(document),
+            canonical_path=issue.canonical_path,
+            org_id=actor.profile.org_id,
+        ), receipt