@gotcos/glasses-server 6.55.0 → 6.56.0

package/work-task-runtime/task_checkout.py

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""Atomic task / file lock manager. Store: COS/.task_locks.json (v19 §1b.2)."""
+
+from __future__ import annotations
+from runtime_io import open_lock
+
+import argparse
+import fcntl
+import json
+import os
+import sys
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEFAULT_LOCKS_FILE = (
+    Path.home() / "Library" / "Application Support" / "COS" / ".task_locks.json"
+)
+LOCKS_FILE = Path(os.environ.get("COS_TASK_LOCK_STORE") or DEFAULT_LOCKS_FILE)
+DEFAULT_TIMEOUT_MINUTES = 30
+CORRUPT_NAME = ".task_locks.json.corrupt"
+
+
+class LockStoreCorrupt(Exception):
+    """Lock file has no recoverable JSON object prefix."""
+
+
+@dataclass
+class CheckoutResult:
+    success: bool
+    task_id: str
+    user: str
+    conflict: bool = False
+    locked_by: Optional[str] = None
+    locked_at: Optional[str] = None
+    expires_at: Optional[str] = None
+    message: str = ""
+
+
+@dataclass
+class LockEntry:
+    task_id: str
+    user: str
+    locked_at: str
+    expires_at: str
+
+    def is_expired(self) -> bool:
+        # Unknown expiry is unknown ownership, never permission to steal a lock.
+        try:
+            locked = datetime.fromisoformat(self.locked_at)
+            expires = datetime.fromisoformat(self.expires_at)
+            if locked.tzinfo is None or expires.tzinfo is None or expires < locked:
+                raise ValueError("Invalid lock timestamp ordering or timezone")
+            return datetime.now(timezone.utc) > expires
+        except (ValueError, TypeError) as exc:
+            raise LockStoreCorrupt("Lock timestamps are invalid; repair required") from exc
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "LockEntry":
+        known = {"task_id", "user", "locked_at", "expires_at"}
+        if not isinstance(d, dict) or set(d) != known or any(not isinstance(d[k], str) or not d[k].strip() for k in known):
+            raise LockStoreCorrupt("Lock entry schema is invalid; repair required")
+        return cls(**d)
+
+
+def _entries_from_payload(data: dict) -> Dict[str, LockEntry]:
+    if not isinstance(data, dict):
+        raise LockStoreCorrupt("Lock store must be an object")
+    locks: Dict[str, LockEntry] = {}
+    for key, value in data.items():
+        entry = LockEntry.from_dict(value)
+        if not isinstance(key, str) or not key or entry.task_id != key:
+            raise LockStoreCorrupt("Lock key and task identity disagree; repair required")
+        if not entry.is_expired():
+            locks[key] = entry
+    return locks
+
+
+def _unique_lock_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise LockStoreCorrupt("Duplicate lock JSON key; repair required")
+        result[key] = value
+    return result
+
+
+def _decode_store(raw: bytes) -> tuple[Optional[dict], bool]:
+    """Return (payload, corrupt). Empty bytes are a fresh store, not corrupt."""
+    if not raw:
+        return {}, False
+    text = raw.decode("utf-8", errors="surrogateescape")
+    stripped = text.lstrip()
+    if "{" not in stripped:
+        return None, True
+    try:
+        obj, _end = json.JSONDecoder(object_pairs_hook=_unique_lock_object).raw_decode(stripped)
+    except json.JSONDecodeError:
+        return None, True
+    if not isinstance(obj, dict):
+        return None, True
+    return obj, False
+
+
+class TaskCheckoutManager:
+    """Manages atomic task checkouts with file-based locking."""
+
+    def __init__(
+        self,
+        locks_file: Path = LOCKS_FILE,
+        timeout_minutes: int = DEFAULT_TIMEOUT_MINUTES,
+    ):
+        self.locks_file = Path(locks_file)
+        self.timeout_minutes = timeout_minutes
+        self._quarantined: set[tuple[int, int]] = set()
+
+    def _ensure_parent(self) -> None:
+        pass  # Parent was securely opened by the portable wrapper
+
+    def _quarantine(self, raw: bytes) -> None:
+        dest = self.locks_file.parent / CORRUPT_NAME
+        raise LockStoreCorrupt("Portable lock store is corrupt; repair required")
+
+    def _persist(self, f, locks: Dict[str, LockEntry]) -> None:
+        out = {k: v.to_dict() for k, v in locks.items()}
+        encoded = json.dumps(out, indent=2).encode("utf-8") + b"\n"
+        f.seek(0)
+        f.write(encoded)
+        f.flush()
+        os.fsync(f.fileno())
+        f.truncate(len(encoded))
+
+    def _with_file_lock(
+        self,
+        fn: Callable,
+        *,
+        fail_closed: bool = False,
+        readonly: bool = False,
+    ):
+        """Same-fd flock. See plan v19 §1b.2.
+
+        Write path creates the store. Readonly never creates. Empty size is
+        a fresh map. A torn UTF-8 tail with a dict prefix is kept; only a
+        missing dict prefix quarantines.
+        """
+        if not readonly:
+            self._ensure_parent()
+
+        if readonly:
+            try:
+                fd = open_lock(self.locks_file, os.O_RDONLY)
+            except FileNotFoundError:
+                return fn({})
+        else:
+            fd = open_lock(self.locks_file, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600)
+
+        f = os.fdopen(fd, "rb+")
+        try:
+            fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+            raw = f.read(1_048_577)
+            if len(raw) > 1_048_576: raise LockStoreCorrupt("Lock store exceeds supported size")
+            payload, corrupt = _decode_store(raw)
+            if corrupt:
+                stamp = (0, 0)
+                try:
+                    st = os.fstat(f.fileno())
+                    stamp = (st.st_mtime_ns, st.st_size)
+                except OSError:
+                    pass
+                if stamp not in self._quarantined:
+                    self._quarantine(raw)
+                    self._quarantined.add(stamp)
+                locks = {}
+                if fail_closed or not readonly:
+                    # Never clear unknown ownership as a side effect of admission.
+                    # Otherwise the next retry steals every lock in the corrupt store.
+                    raise LockStoreCorrupt(str(self.locks_file))
+            else:
+                locks = _entries_from_payload(payload or {})
+
+            result = fn(locks)
+
+            if not readonly:
+                self._persist(f, locks)
+            return result
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+            f.close()
+
+    def _purge_expired(self, locks: Dict[str, LockEntry]) -> int:
+        expired = [k for k, v in locks.items() if v.is_expired()]
+        for key in expired:
+            del locks[key]
+        return len(expired)
+
+    def _ttl(self, timeout_minutes: Optional[int]) -> int:
+        return self.timeout_minutes if timeout_minutes is None else timeout_minutes
+
+    def checkout(
+        self,
+        task_id: str,
+        user: str,
+        *,
+        exclusive: bool = False,
+        timeout_minutes: Optional[int] = None,
+    ) -> CheckoutResult:
+        ttl = self._ttl(timeout_minutes)
+
+        def _do_checkout(locks: Dict[str, LockEntry]) -> CheckoutResult:
+            self._purge_expired(locks)
+
+            if task_id in locks:
+                existing = locks[task_id]
+                if existing.user == user and not exclusive:
+                    now = datetime.now(timezone.utc)
+                    existing.locked_at = now.isoformat()
+                    existing.expires_at = (now + timedelta(minutes=ttl)).isoformat()
+                    return CheckoutResult(
+                        success=True, task_id=task_id, user=user,
+                        message=f"Lock extended for {user}",
+                    )
+                return CheckoutResult(
+                    success=False, task_id=task_id, user=user,
+                    conflict=True,
+                    locked_by=existing.user,
+                    locked_at=existing.locked_at,
+                    expires_at=existing.expires_at,
+                    message=f"Task {task_id} is checked out by {existing.user}",
+                )
+
+            now = datetime.now(timezone.utc)
+            locks[task_id] = LockEntry(
+                task_id=task_id,
+                user=user,
+                locked_at=now.isoformat(),
+                expires_at=(now + timedelta(minutes=ttl)).isoformat(),
+            )
+            return CheckoutResult(
+                success=True, task_id=task_id, user=user,
+                message=f"Checked out {task_id} for {user}",
+            )
+
+        return self._with_file_lock(
+            _do_checkout, fail_closed=task_id.startswith("file:")
+        )
+
+    def release(self, task_id: str, user: str) -> CheckoutResult:
+        def _do_release(locks: Dict[str, LockEntry]) -> CheckoutResult:
+            self._purge_expired(locks)
+            if task_id not in locks:
+                return CheckoutResult(
+                    success=True, task_id=task_id, user=user,
+                    message=f"Task {task_id} was not locked",
+                )
+            existing = locks[task_id]
+            if existing.user != user:
+                return CheckoutResult(
+                    success=False, task_id=task_id, user=user,
+                    conflict=True, locked_by=existing.user,
+                    message=f"Cannot release — locked by {existing.user}, not {user}",
+                )
+            del locks[task_id]
+            return CheckoutResult(
+                success=True, task_id=task_id, user=user,
+                message=f"Released {task_id}",
+            )
+
+        return self._with_file_lock(
+            _do_release, fail_closed=task_id.startswith("file:")
+        )
+
+    def force_release(self, task_id: str) -> CheckoutResult:
+        def _do_force(locks: Dict[str, LockEntry]) -> CheckoutResult:
+            self._purge_expired(locks)
+            if task_id in locks:
+                old_user = locks[task_id].user
+                del locks[task_id]
+                return CheckoutResult(
+                    success=True, task_id=task_id, user="admin",
+                    message=f"Force-released {task_id} (was held by {old_user})",
+                )
+            return CheckoutResult(
+                success=True, task_id=task_id, user="admin",
+                message=f"Task {task_id} was not locked",
+            )
+
+        return self._with_file_lock(_do_force)
+
+    def status(self) -> List[LockEntry]:
+        def _do_status(locks: Dict[str, LockEntry]):
+            self._purge_expired(locks)
+            return list(locks.values())
+
+        return self._with_file_lock(_do_status, readonly=True)
+
+    def is_locked(self, task_id: str) -> Optional[LockEntry]:
+        def _do_check(locks: Dict[str, LockEntry]):
+            self._purge_expired(locks)
+            return locks.get(task_id)
+
+        return self._with_file_lock(_do_check, readonly=True)
+
+
+def doctor(locks_file: Path, *, confirm: bool) -> int:
+    corrupt = locks_file.parent / CORRUPT_NAME
+    print(f"store: {locks_file}")
+    print(f"corrupt: {corrupt}")
+    if not confirm:
+        print("pass --confirm to recreate an empty store")
+        return 0
+    locks_file.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    locks_file.write_text("{}\n")
+    print("rewrote empty store")
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Task Checkout Manager")
+    subparsers = parser.add_subparsers(dest="command")
+
+    co = subparsers.add_parser("checkout", help="Check out a task")
+    co.add_argument("task_id")
+    co.add_argument("user")
+
+    rel = subparsers.add_parser("release", help="Release a checkout")
+    rel.add_argument("task_id")
+    rel.add_argument("user")
+
+    fr = subparsers.add_parser("force-release", help="Force release (admin)")
+    fr.add_argument("task_id")
+
+    subparsers.add_parser("status", help="Show all active locks")
+
+    doc = subparsers.add_parser("doctor", help="Inspect / recreate the lock store")
+    doc.add_argument("--confirm", action="store_true")
+
+    args = parser.parse_args()
+    mgr = TaskCheckoutManager()
+
+    if args.command == "checkout":
+        result = mgr.checkout(args.task_id, args.user)
+        if result.conflict:
+            print(f"CONFLICT: {result.message}")
+            print(f"  Locked by: {result.locked_by}")
+            print(f"  Since: {result.locked_at}")
+            print(f"  Expires: {result.expires_at}")
+            sys.exit(1)
+        print(f"OK: {result.message}")
+    elif args.command == "release":
+        result = mgr.release(args.task_id, args.user)
+        if result.success:
+            print(f"OK: {result.message}")
+        else:
+            print(f"DENIED: {result.message}")
+            sys.exit(1)
+    elif args.command == "force-release":
+        print(f"OK: {mgr.force_release(args.task_id).message}")
+    elif args.command == "status":
+        locks = mgr.status()
+        if not locks:
+            print("No active locks.")
+            return
+        print(f"\n{'Task ID':<20} {'User':<15} {'Locked At':<25} {'Expires At'}")
+        print("-" * 80)
+        for lock in locks:
+            print(f"{lock.task_id:<20} {lock.user:<15} {lock.locked_at:<25} {lock.expires_at}")
+        print()
+    elif args.command == "doctor":
+        sys.exit(doctor(LOCKS_FILE, confirm=args.confirm))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

package/work-task-runtime/task_commands.py

@@ -0,0 +1,275 @@
+"""Extracted canonical task handlers only; see manifest provenance."""
+import json, re, sys
+
+def cmd_task_rows(args):
+    from task_rows import full_domains, cmd_task_rows as emit_rows
+
+    domain = args[0] if args and not args[0].startswith("-") else None
+    day = None
+    if "--day" in args:
+        idx = args.index("--day")
+        if idx + 1 < len(args):
+            day = args[idx + 1]
+    if domain not in full_domains():
+        print(json.dumps({
+            "error": {
+                "code": "invalid_domain",
+                "message": f"full domain required, got {domain!r}",
+            }
+        }))
+        return
+    if not day or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", day):
+        print(json.dumps({
+            "error": {
+                "code": "day_required",
+                "message": "--day YYYY-MM-DD is required",
+            }
+        }))
+        return
+    print(json.dumps(emit_rows(domain, day)))
+
+def _bridge_error(code: str, message: str) -> None:
+    print(json.dumps({"error": {"code": code, "message": message}}))
+
+def _bridge_flag(args, name: str):
+    if name in args:
+        idx = args.index(name)
+        if idx + 1 < len(args):
+            return args[idx + 1]
+    return None
+
+def _bridge_domain(args):
+    from task_rows import full_domains
+
+    domain = args[0] if args and not args[0].startswith("-") else None
+    if domain not in full_domains():
+        _bridge_error("invalid_domain", f"full domain required, got {domain!r}")
+        return None
+    return domain
+
+def _bridge_write(fn):
+    from task_write import LockLost, TaskFileLocked, TaskRunning
+    from task_work_metadata import WorkMetadataError
+
+    try:
+        return fn()
+    except TaskFileLocked as exc:
+        _bridge_error("task_file_locked", str(exc))
+    except TaskRunning as exc:
+        _bridge_error("task_running", str(exc))
+    except LockLost as exc:
+        _bridge_error("lock_lost", str(exc))
+    except WorkMetadataError as exc:
+        _bridge_error(exc.code, str(exc))
+    except ValueError as exc:
+        _bridge_error("invalid_section", str(exc))
+    return None
+
+def cmd_task_capture(args):
+    from task_write import capture
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    section = _bridge_flag(args, "--section")
+    if not section:
+        _bridge_error("section_required", "--section is required")
+        return
+    text = sys.stdin.read().strip()
+    if not text:
+        _bridge_error("text_required", "task text required on STDIN")
+        return
+    result = _bridge_write(lambda: capture(
+        domain,
+        text,
+        section=section,
+        run_at=_bridge_flag(args, "--run-at"),
+        purge_before=_bridge_flag(args, "--purge-before"),
+    ))
+    if result is not None:
+        print(json.dumps(result))
+
+def cmd_task_set_run_at(args):
+    from task_write import set_run_at
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) < 3:
+        _bridge_error("argv_required", "usage: task-set-run-at <domain> <id> <YYYY-MM-DD HH:MM>|--clear")
+        return
+    task_id = args[1]
+    raw = args[2]
+    run_at = None if raw == "--clear" else raw
+    ok = _bridge_write(lambda: set_run_at(domain, task_id, run_at))
+    if ok is None:
+        return
+    if ok is False:
+        _bridge_error("task_not_found", f"no task {task_id} in {domain}")
+        return
+    print(json.dumps({"ok": True}))
+
+def cmd_task_set_text(args):
+    """Rewrite a task's words. Text arrives on STDIN so it needs no quoting."""
+    from task_write import set_text
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) < 2:
+        _bridge_error("argv_required", "usage: task-set-text <domain> <id>  (text on STDIN)")
+        return
+    task_id = args[1]
+    text = sys.stdin.read().strip()
+    if not text:
+        _bridge_error("text_required", "task text required on STDIN")
+        return
+    ok = _bridge_write(lambda: set_text(domain, task_id, text))
+    if ok is None:
+        return
+    if ok is False:
+        _bridge_error("task_not_found", f"no task {task_id} in {domain}")
+        return
+    print(json.dumps({"ok": True}))
+
+def cmd_task_work_write(args, *, linking=False):
+    from task_write import set_work_stage, link_meeting
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) != (2 if linking else 3):
+        _bridge_error("argv_required", "Expected domain, task ID, and phase for stage writes.")
+        return
+    try:
+        raw = sys.stdin.read(32_769)
+        if len(raw.encode()) > 32_768:
+            raise ValueError()
+        body = json.loads(raw)
+        if not isinstance(body, dict) or not isinstance(body.get("expectedText"), str) or not isinstance(body.get("expectedRevision"), str):
+            raise ValueError()
+        allowed = {"expectedText", "expectedRevision", "meeting", "removeRecordId"} if linking else {"expectedText", "expectedRevision"}
+        if set(body) - allowed:
+            raise ValueError()
+    except (ValueError, TypeError):
+        _bridge_error("invalid_work_request", "Bounded JSON with expectedText and expectedRevision is required.")
+        return
+    if linking:
+        ok = _bridge_write(lambda: link_meeting(domain, args[1], expected_text=body["expectedText"], expected_revision=body["expectedRevision"], meeting=body.get("meeting"), remove_record_id=body.get("removeRecordId")))
+    else:
+        ok = _bridge_write(lambda: set_work_stage(domain, args[1], args[2], expected_text=body["expectedText"], expected_revision=body["expectedRevision"]))
+    if ok is False:
+        _bridge_error("task_not_found", "Task not found in this domain.")
+    elif ok is not None:
+        print(json.dumps({"ok": True}))
+
+def cmd_task_set_stage(args):
+    """Move a task between board stages. Clearing returns it to planning, which
+    is the unmarked default, so the marker is removed rather than written."""
+    from task_write import set_stage
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) < 3:
+        _bridge_error("argv_required", "usage: task-set-stage <domain> <id> planning|active|review|--clear")
+        return
+    # Validated HERE, not via except: _bridge_write catches ValueError itself and
+    # reports it as invalid_section, so a try/except around it never fires.
+    stage = args[2]
+    if stage not in ("--clear", "planning", "active", "review"):
+        _bridge_error("invalid_stage", f"invalid stage: {stage}")
+        return
+    ok = _bridge_write(lambda: set_stage(domain, task_id=args[1], stage=stage))
+    if ok is None:
+        return
+    if ok is False:
+        _bridge_error("task_not_found", f"no task {args[1]} in {domain}")
+        return
+    print(json.dumps({"ok": True}))
+
+def cmd_task_set_done_when(args):
+    """Set or clear the finish line. Text arrives on STDIN so it needs no
+    quoting; an empty body clears it. A dispatch is refused while it is empty."""
+    from task_write import set_done_when
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) < 2:
+        _bridge_error("argv_required", "usage: task-set-done-when <domain> <id>  (text on STDIN, empty clears)")
+        return
+    text = sys.stdin.read().strip()
+    if "\n" in text or "**" in text:
+        _bridge_error("invalid_done_when", "done_when must be a single line without ** markup")
+        return
+    ok = _bridge_write(lambda: set_done_when(domain, task_id=args[1], text=text))
+    if ok is None:
+        return
+    if ok is False:
+        _bridge_error("task_not_found", f"no task {args[1]} in {domain}")
+        return
+    print(json.dumps({"ok": True}))
+
+def cmd_task_set_marker(args):
+    from task_write import set_marker
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) < 3:
+        _bridge_error("argv_required", "usage: task-set-marker <domain> <id> running|done:<N>|failed:<N>|failed|--clear")
+        return
+    marker = None if args[2] == "--clear" else args[2]
+    ok = _bridge_write(lambda: set_marker(domain, task_id=args[1], marker=marker))
+    if ok is None:
+        return
+    if ok is False:
+        _bridge_error("task_not_found", f"no task {args[1]} in {domain}")
+        return
+    print(json.dumps({"ok": True}))
+
+def cmd_task_move(args):
+    from task_write import move
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    if len(args) < 2:
+        _bridge_error("argv_required", "usage: task-move <domain> <id> --section <section>")
+        return
+    section = _bridge_flag(args, "--section")
+    if not section:
+        _bridge_error("section_required", "--section is required")
+        return
+    ok = _bridge_write(lambda: move(
+        domain, args[1], section, purge_before=_bridge_flag(args, "--purge-before")
+    ))
+    if ok is None:
+        return
+    if ok is False:
+        _bridge_error("task_not_found", f"no task {args[1]} in {domain}")
+        return
+    print(json.dumps({"ok": True}))
+
+def cmd_task_check(args):
+    from task_write import check
+
+    domain = _bridge_domain(args)
+    if domain is None:
+        return
+    text = _bridge_flag(args, "--text")
+    task_id = None
+    if len(args) >= 2 and not args[1].startswith("-"):
+        task_id = args[1]
+    if not task_id and not text:
+        _bridge_error("argv_required", "usage: task-check <domain> <id>|--text <…> [--uncheck]")
+        return
+    status = _bridge_write(lambda: check(
+        domain, task_id, text=text, uncheck="--uncheck" in args
+    ))
+    if status is None:
+        return
+    if status != "ok":
+        _bridge_error(status, status.replace("_", " "))
+        return
+    print(json.dumps({"ok": True}))

package/work-task-runtime/task_dedup.py

@@ -0,0 +1,11 @@
+import string
+class TaskDeduplicator:
+    @staticmethod
+    def normalize(text: str) -> str:
+            """Normalize text for comparison."""
+            from task_rows import strip_markers
+            text, _ = strip_markers(text)
+            text = text.lower()
+            text = text.translate(str.maketrans('', '', string.punctuation))
+            text = ' '.join(text.split())
+            return text