create-egregore 0.21.6 → 0.22.0

package/runtime/codex/egregore_runtime/taste_cli.py

@@ -0,0 +1,242 @@
+"""Runtime-neutral CLI behind bin/genui.sh: record interface taste, read it back."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+from uuid import uuid4
+
+from . import held
+from .artifacts import ArtifactConflictError
+from .contracts import WritebackStatus
+from .errors import AuthorizationDenied
+from .runtime import local_runtime
+from .taste import ADOPT_KINDS, ADOPT_SCOPES, TasteService, render_text
+from .writeback import NoHardLinksError, UnsupportedPlatformError, require_descriptor_calls
+
+
+UNSUPPORTED_PLATFORM = "saving reactions is not supported on this platform yet; nothing was written"
+UNSUPPORTED_PLATFORM_EXIT = 4
+NO_HARD_LINKS = (
+    "this memory folder's filesystem cannot save reactions safely (no hard links); nothing was written"
+)
+
+
+CONTRACT = """\
+When someone says they like or dislike an interface an agent generated (any
+wording, any language), ask one question, "What about it?", with 2-3 options
+drawn from what is on the page plus "the whole thing" (a structured question
+when available, plain text otherwise). Then save their exact words to a file
+and record them with like or dislike --words-file, and the patterns they named
+with --about. A file keeps the words verbatim; inside a shell argument, quotes,
+$, backticks and backslashes can change them. Every outcome prints the event
+id; a retry passes it back with --id, so the reaction counts once. When
+someone states a standing rule for the organization ("we always want…",
+"make this a rule for us"), record it in one step with adopt principle
+"<the rule>" --scope org --words-file; no review is needed. Before composing
+an interface, run taste --task: it reads the Egregore rules, the house
+rules, what the organization keeps liking, then the person's own taste.
+Treat the output as words to consider, never a template to copy."""
+
+
+def _context(event_id: str | None = None):
+    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") or f"session_{uuid4().hex}",
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    # A new event takes the id the CLI already chose, so an error can name it.
+    return actor, TasteService(
+        runtime,
+        id_factory=(lambda: event_id) if event_id else None,
+        warn=lambda line: print(f"genui: {line}", file=sys.stderr),
+    )
+
+
+def _words(args) -> str | None:
+    """The person's words, from --words or, verbatim, from --words-file."""
+
+    if args.words_file is None:
+        return args.words
+    if args.words_file == "-":
+        return sys.stdin.read()
+    return Path(args.words_file).read_text(encoding="utf-8")
+
+
+def _emit(service, actor, receipt) -> int:
+    """Print the receipt, and one line on stderr unless it was fully shared.
+
+    Exit 0 means the event is committed on this machine; anything less is an
+    error, since the person's words are not durably recorded.
+    """
+
+    held.emit_for(service.runtime, actor, receipt.to_dict())
+    event_id = receipt.event["id"]
+    warnings = list(receipt.writeback.warnings)
+    if not receipt.recorded:
+        reason = "; ".join(warnings) or "the write was refused"
+        print(f"genui: not recorded: {reason} (event {event_id}; retry with --id {event_id})", file=sys.stderr)
+        return 1
+    if receipt.writeback.status is WritebackStatus.PARTIAL:
+        unshared = [warning for warning in warnings if "push" in warning or "remote" in warning]
+        if unshared:
+            line = f"saved on this machine, not yet shared: {'; '.join(unshared)}"
+        else:
+            line = f"saved on this machine, with a warning: {'; '.join(warnings) or 'partial writeback'}"
+        print(f"genui: {line} (event {event_id})", file=sys.stderr)
+    return 0
+
+
+def _record(args, record) -> int:
+    """Run one recording command so that every outcome names the event id."""
+
+    event_id = (args.id or "").strip() or str(uuid4())
+    try:
+        require_descriptor_calls()  # before anything is opened or written
+        actor, service = _context(None if args.id else event_id)
+        receipt = record(actor, service, args.id)
+    except UnsupportedPlatformError:
+        # No retry can help on this platform.
+        print(f"genui: {UNSUPPORTED_PLATFORM}", file=sys.stderr)
+        return UNSUPPORTED_PLATFORM_EXIT
+    except NoHardLinksError:
+        # Nor on this filesystem: the staged copy is gone, nothing is written.
+        print(f"genui: not recorded: {NO_HARD_LINKS} (event {event_id})", file=sys.stderr)
+        return 1
+    except ArtifactConflictError as exc:
+        # A retry cannot fix a different reaction under a used id.
+        print(f"genui: not recorded: {exc} (event {event_id})", file=sys.stderr)
+        return 1
+    except (AuthorizationDenied, OSError, RuntimeError, ValueError) as exc:
+        print(f"genui: not recorded: {exc} (event {event_id}; retry with --id {event_id})", file=sys.stderr)
+        return 1
+    return _emit(service, actor, receipt)
+
+
+def _react(args) -> int:
+    return _record(args, lambda actor, service, event_id: service.react(
+        actor,
+        "liked" if args.command == "like" else "disliked",
+        args.target,
+        words=_words(args),
+        about=args.about,
+        region=args.region,
+        task=args.task,
+        audience=args.audience,
+        form=args.form,
+        event_id=event_id,
+    ))
+
+
+def _chose(args) -> int:
+    return _record(args, lambda actor, service, event_id: service.choose(
+        actor,
+        args.winner,
+        args.over,
+        words=_words(args),
+        about=args.about,
+        task=args.task,
+        audience=args.audience,
+        form=args.form,
+        event_id=event_id,
+    ))
+
+
+def _adopt(args) -> int:
+    return _record(args, lambda actor, service, event_id: service.adopt(
+        actor, args.kind, args.value, scope=args.scope, words=_words(args), event_id=event_id,
+    ))
+
+
+def _retract(args) -> int:
+    return _record(args, lambda actor, service, event_id: service.retract(
+        actor, args.event_id, words=_words(args), event_id=event_id,
+    ))
+
+
+def _taste(args) -> int:
+    actor, service = _context()
+    summary = service.summary(actor, person=args.person, task=args.task, form=args.form)
+    return held.emit_for(service.runtime, actor, summary, **({} if args.json else {"render": render_text, "end": ""}))
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bin/genui.sh",
+        description="Record what people like in generated interfaces and read it back as words.",
+        epilog=CONTRACT,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    def words(command, *, required: bool) -> None:
+        given = command.add_mutually_exclusive_group(required=required)
+        given.add_argument("--words", help="what the person said, verbatim, as one shell argument")
+        given.add_argument(
+            "--words-file", metavar="PATH",
+            help="a file holding what the person said, kept verbatim; '-' reads standard input",
+        )
+
+    def context(command, *, region: bool = True) -> None:
+        command.add_argument("--about", action="append", default=[], metavar="PATTERN",
+                             help="a pattern the person named; repeat for each")
+        if region:
+            command.add_argument("--region", help="the part of the page, as free text or a selector")
+        command.add_argument("--task", help="what the interface was for")
+        command.add_argument("--audience", help="who it was for")
+        command.add_argument("--form", help="the kind of interface, e.g. cards, scroll, mock, view")
+        command.add_argument("--id", help="event UUID; reuse it when retrying the same event")
+
+    for name, verb in (("like", "liked"), ("dislike", "disliked")):
+        react = commands.add_parser(name, help=f"record that someone {verb} a generated interface")
+        react.add_argument("target", help="registry id, hosted URL, local path or claude.ai artifact link")
+        words(react, required=True)
+        context(react)
+        react.set_defaults(handler=_react)
+
+    chose = commands.add_parser("chose", help="record that someone chose one interface over another")
+    chose.add_argument("winner", help="the interface they chose")
+    chose.add_argument("--over", required=True, help="the interface they passed over")
+    words(chose, required=False)
+    context(chose, region=False)
+    chose.set_defaults(handler=_chose)
+
+    adopt = commands.add_parser(
+        "adopt",
+        help="make a palette or pattern a default, or a principle a standing rule (--scope org: a house rule)",
+    )
+    adopt.add_argument("kind", choices=ADOPT_KINDS)
+    adopt.add_argument("value", help="the palette, pattern or principle, in a few words")
+    adopt.add_argument("--scope", choices=ADOPT_SCOPES, default="person")
+    words(adopt, required=False)
+    adopt.add_argument("--id", help="event UUID; reuse it when retrying the same event")
+    adopt.set_defaults(handler=_adopt)
+
+    retract = commands.add_parser("retract", help="withdraw one of your own taste events")
+    retract.add_argument("event_id")
+    words(retract, required=False)
+    retract.add_argument("--id", help="event UUID; reuse it when retrying the same event")
+    retract.set_defaults(handler=_retract)
+
+    taste = commands.add_parser("taste", help="read back what someone liked, in their words")
+    taste.add_argument("--person", help="a name or actor id; defaults to you")
+    taste.add_argument("--task", help="the work about to be composed; closest reactions come first")
+    taste.add_argument("--form", help="the kind of interface about to be composed")
+    taste.add_argument("--json", action="store_true")
+    taste.set_defaults(handler=_taste)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one command; bin/genui.sh reaches it through bin/lib/genui-entry.py."""
+
+    args = _parser().parse_args(argv)
+    try:
+        return args.handler(args)
+    except (AuthorizationDenied, OSError, RuntimeError, ValueError) as exc:
+        print(f"genui: {exc}", file=sys.stderr)
+        return 1

package/runtime/codex/egregore_runtime/taste_rules.py

@@ -0,0 +1,91 @@
+"""Egregore rules: good design for any reader, whatever the brand.
+
+These ship with the Runtime to every organization and are read first, before
+the organization's house rules, what the organization keeps liking, and one
+person's own taste; later layers win where they conflict. The must-pass
+checks (contrast, accessibility, colours from tokens, sandboxed hosting, no
+internal notes in the outside copy) live in code and always hold.
+
+Each rule says when to skip it and why it exists, so an agent can set it
+aside with a reason instead of following it blindly.
+"""
+
+from __future__ import annotations
+
+EGREGORE_RULES: tuple[dict[str, str], ...] = (
+    {
+        "rule": "Design every page from its content; never ship a stock template.",
+        "skip": "A form the reader already knows and expects, such as a receipt.",
+        "why": "Examples inspire; a skeleton reused as-is makes every page read the same.",
+    },
+    {
+        "rule": "The first view is a complete frame: nothing cut by the fold, nothing overflowing sideways, no controls over content.",
+        "skip": "Never.",
+        "why": "The first screen decides whether the reader continues.",
+    },
+    {
+        "rule": "Give one strong visual room, and keep nothing off-chart: extend the axes, or cut the items and say so.",
+        "skip": "Pages with no visual argument to make.",
+        "why": "A cramped or clipped figure hides the point it exists to show.",
+    },
+    {
+        "rule": "Leave clear space between groups, and check overlaps mechanically, not by eye.",
+        "skip": "Never.",
+        "why": "Crowding reads as noise, and the eye misses overlaps a check catches.",
+    },
+    {
+        "rule": "Choose sections per piece, never because a template lists them.",
+        "skip": "A form whose sections the reader relies on, such as a changelog.",
+        "why": "Standing sections pad a page with headings that say nothing.",
+    },
+    {
+        "rule": "Use plain, established words and the organization's own vocabulary; coin no terms in reader-facing text.",
+        "skip": "A term the organization already uses.",
+        "why": "A coined word is one more thing the reader must learn before understanding.",
+    },
+    {
+        "rule": "Introduce every term before using it, and write for someone who was not there.",
+        "skip": "Pages written for the people who were in the room.",
+        "why": "Pages travel further than the conversation that produced them.",
+    },
+    {
+        "rule": "Reveal depth step by step, but let the page answer its question with no interaction.",
+        "skip": "Tools and forms whose purpose is the interaction.",
+        "why": "A reader who never clicks should still leave with the answer.",
+    },
+    {
+        "rule": "Keep one design system as the chassis and one visual device per element.",
+        "skip": "Never.",
+        "why": "Mixed systems and stacked devices compete for attention.",
+    },
+    {
+        "rule": "Keep geometry honest: one meaning per axis, status readable without colour, every item accounted for.",
+        "skip": "Never.",
+        "why": "A figure that misleads is worse than no figure.",
+    },
+    {
+        "rule": "Move things only to explain them, and respect reduced motion.",
+        "skip": "Never.",
+        "why": "Decorative motion distracts and can make readers unwell.",
+    },
+    {
+        "rule": "Keep minimum craft: no cropped glyphs, labels that fit, focus always visible and styled, never removed.",
+        "skip": "Never.",
+        "why": "Small defects cost trust out of proportion to their size.",
+    },
+    {
+        "rule": "Serve two audiences from one source: mark internal notes and strip them from the outside copy.",
+        "skip": "Pages that never leave the organization.",
+        "why": "One source keeps both copies true; marked notes cannot leak by accident.",
+    },
+    {
+        "rule": "A page may carry its own palette when the content calls for it, if it passes the must-pass checks.",
+        "skip": "An organization with a house palette rule.",
+        "why": "Colour carries meaning; the checks keep it readable.",
+    },
+    {
+        "rule": "Draw no coloured side stripes: mark reading emphasis with a marker, a margin label or type, and status with a quiet panel whose label carries a shape.",
+        "skip": "A rail that connects timeline items.",
+        "why": "A stripe says only 'look here' and fails without colour; a shaped label reads in any theme.",
+    },
+)

package/runtime/codex/egregore_runtime/telemetry.py

@@ -24,6 +24,7 @@ from urllib import request as urllib_request
 from uuid import uuid4
 
 from .contracts import TelemetryEvent
+from .sandbox import state_directory
 
 
 TELEMETRY_SCHEMA_VERSION = "egregore.telemetry/v1"
@@ -138,6 +139,7 @@ class TelemetryStatus:
     storage_path: Path
     local_only: bool = True
     retention: Mapping[str, Any] | None = None
+    warnings: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)
@@ -236,6 +238,8 @@ def validate_event(event: TelemetryEvent) -> None:
 
     for artifact_id in event.artifact_ids:
         _safe_identifier(artifact_id, field="artifact_ids[]", max_length=256)
+        if artifact_id.startswith(("memory/", "/", ".", "~")) or artifact_id.endswith((".md", ".html")):
+            raise TelemetryPrivacyError("artifact_ids[] must be opaque identifiers, never paths")
 
     if event.event_type in {"operation.start", "operation.result"}:
         required = {"operation", "layer", "invocation_id", "harness"}
@@ -368,7 +372,10 @@ class LocalTelemetrySink:
     ``~/.egregore/telemetry/``: on-device, outside canonical repositories, and
     unable to mix multiple Egregore instances. ``EGREGORE_TELEMETRY_DIR`` or
     an explicit ``storage_dir`` may relocate one sink for tests or managed
-    local deployments.
+    local deployments. When that per-user directory refuses writes (a
+    sandboxed session), the buffer moves to the workspace's own
+    ``.egregore/telemetry/``, and ``status()`` names the cause first, and
+    names both failures when that copy is refused too.
     """
 
     def __init__(
@@ -382,6 +389,9 @@ class LocalTelemetrySink:
         instance_root: Path | None = None,
     ) -> None:
         env_dir = os.environ.get("EGREGORE_TELEMETRY_DIR")
+        # Set when the per-user directory refuses writes: with the workspace
+        # copy in use, or naming why that copy was refused too.
+        self.state_warning: str | None = None
         if storage_dir is not None:
             self.storage_dir = storage_dir
         elif env_dir:
@@ -390,6 +400,16 @@ class LocalTelemetrySink:
             root = instance_root or (state_file.parent if state_file else Path.cwd())
             namespace = hashlib.sha256(str(root.resolve()).encode()).hexdigest()[:20]
             self.storage_dir = Path.home() / ".egregore" / "telemetry" / namespace
+            if state_file is not None:
+                # The state file names the workspace, the one place a
+                # sandboxed session can still write.
+                workspace = state_file.parent
+                self.storage_dir, self.state_warning = state_directory(
+                    self.storage_dir,
+                    workspace / ".egregore" / "telemetry",
+                    workspace=workspace,
+                    home=Path.home(),
+                )
         self.buffer_path = self.storage_dir / "telemetry.jsonl"
         self.lock_path = self.storage_dir / "telemetry.lock"
         self.share_consent_path = self.storage_dir / "telemetry-share-consent.json"
@@ -550,6 +570,7 @@ class LocalTelemetrySink:
             byte_count=byte_count,
             storage_path=self.buffer_path,
             retention=self._retention() if self.retention_path.exists() else None,
+            warnings=(self.state_warning,) if self.state_warning else (),
         )
 
     def set_enabled(self, enabled: bool) -> None:
@@ -722,11 +743,13 @@ class HttpSharedTelemetrySink:
             "Content-Type": "application/x-ndjson",
             "User-Agent": "egregore-runtime-telemetry/1",
         }
-        if self.bearer_token:
-            headers["Authorization"] = f"Bearer {self.bearer_token}"
         outbound = urllib_request.Request(
             self.endpoint, data=payload, headers=headers, method="POST"
         )
+        if self.bearer_token:
+            # urllib copies only Request.headers to a redirect; the bearer
+            # token stays with this request and never reaches another host.
+            outbound.add_unredirected_header("Authorization", f"Bearer {self.bearer_token}")
         with urllib_request.urlopen(outbound, timeout=self.timeout_seconds) as response:
             body = response.read(4096).decode("utf-8", errors="replace")
             return body or str(response.status)

package/runtime/codex/egregore_runtime/todo_cli.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 import argparse
-import json
 import os
 from pathlib import Path
 from uuid import uuid4
 
+from . import held
 from .contracts import Permission
-from .policy import scope_allows_path
+from .policy import action_for, check
 from .runtime import local_runtime
 from .todos import CanonicalTodoService
 
@@ -40,22 +40,25 @@ def _require(
     decision = runtime.authorize(actor, permission, (resource,))
     if not decision.allowed:
         raise PermissionError("; ".join(decision.reasons) or f"todo {permission.value} denied")
-    if canonical_path and not scope_allows_path(canonical_path, decision.scopes):
+    if not canonical_path:
+        return decision, None
+    verdict = check(decision, canonical_path, action_for(decision.permission), root=runtime.canonical_root)
+    if not verdict.allowed:
         raise PermissionError("todo path is outside the actor's authorized scope")
-    return decision
+    return decision, verdict.resolved  # readers open the path the predicate resolved
 
 
 def _list(args):
     runtime, actor, service, default_person = _context()
     person = args.person or default_person
-    _require(
+    decision, source = _require(
         runtime,
         actor,
         Permission.READ,
         f"todos:{person}",
         canonical_path=service.canonical_path(person),
     )
-    snapshot = service.read(person)
+    snapshot = service.read(person, source=source)
     rows = list(snapshot.todos)
     if not args.all:
         rows = [row for row in rows if row.get("status") in {"open", "blocked", "deferred"}]
@@ -63,8 +66,8 @@ def _list(args):
         key=lambda row: (int(row.get("priority") or 0), str(row.get("created") or "")),
         reverse=True,
     )
-    print(json.dumps({"person": snapshot.person, "todos": rows}, ensure_ascii=False))
-    return 0
+    return held.emit(decision, {"person": snapshot.person, "todos": rows}, root=runtime.canonical_root,
+                     paths=(service.canonical_path(person),))
 
 
 def _add(args):
@@ -84,8 +87,8 @@ def _add(args):
         priority=args.priority,
         quest=args.quest,
     )
-    print(json.dumps({"todo": row, "writeback": receipt.to_dict()}, ensure_ascii=False))
-    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+    return held.emit_for(runtime, actor, {"todo": row, "writeback": receipt.to_dict()}) or (
+        0 if receipt.status.value in {"accepted", "partial"} else 1)
 
 
 def _transition(args):
@@ -104,8 +107,8 @@ def _transition(args):
         todo_id=args.id,
         status=args.command,
     )
-    print(json.dumps({"todo": row, "writeback": receipt.to_dict()}, ensure_ascii=False))
-    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+    return held.emit_for(runtime, actor, {"todo": row, "writeback": receipt.to_dict()}) or (
+        0 if receipt.status.value in {"accepted", "partial"} else 1)
 
 
 def _parser():

package/runtime/codex/egregore_runtime/todos.py

@@ -159,8 +159,9 @@ class CanonicalTodoService:
     def canonical_path(person: str) -> str:
         return f"memory/todos/{_slug(person)}.md"
 
-    def read(self, person: str) -> TodoSnapshot:
-        path = self._path(person)
+    def read(self, person: str, *, source: Path | None = None) -> TodoSnapshot:
+        """Read a person's todos; a read surface passes the ``source`` the predicate resolved."""
+        path = source or self._path(person)
         if not path.exists():
             return TodoSnapshot(_slug(person), False, ())
         return parse_todo_markdown(path.read_text(encoding="utf-8"), person=person)