opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/swiftui-expert-skill/scripts/instruments_parser/xml_utils.py

@@ -0,0 +1,224 @@
+"""Streaming XML helpers for xctrace export output.
+
+Instruments XML deduplicates repeated values with `id`/`ref` attributes that
+can span the whole document, so we stream rows with iterparse while keeping
+a global id cache for later ref lookups.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Column:
+    mnemonic: str          # e.g. "time", "weight", "stack"
+    engineering_type: str  # e.g. "sample-time", "weight", "tagged-backtrace"
+
+
+class RowStream:
+    """Iterate <row> elements of a single <table> schema export.
+
+    Yields `dict[str, Element]` keyed by column mnemonic. Elements inside a
+    yielded row are live ET elements (rooted in the id cache where applicable
+    so ref resolution via `resolve()` remains valid after the row is yielded).
+    """
+
+    def __init__(self, xml_bytes: bytes):
+        self._xml = xml_bytes
+        self.columns: list[Column] = []
+        self._id_cache: dict[str, ET.Element] = {}
+
+    def resolve(self, element: ET.Element) -> ET.Element:
+        """If the element is a ref, return the referenced element; else self."""
+        ref = element.get("ref")
+        if ref is None:
+            return element
+        target = self._id_cache.get(ref)
+        if target is None:
+            return element  # unresolved; return the ref element itself
+        return target
+
+    def __iter__(self) -> Iterator[dict[str, ET.Element]]:
+        # iterparse fires `end` events once an element is fully parsed, so ids
+        # are visible to descendants via the cache. We only need `end` events;
+        # row bodies are reconstructed from the end element itself in _row_dict.
+        #
+        # NOTE: we intentionally don't call `elem.clear()` after yielding a row.
+        # Instruments' XML is a single shared doc where any row can `ref` an
+        # `id` defined earlier (threads, processes, stacks, metadata), and
+        # clearing would break those later lookups. The tradeoff is peak RAM
+        # ≈ document size. That's fine for typical traces up to a few hundred
+        # MB; very large exports may need a smarter pass that first indexes
+        # referenced ids and only retains those.
+        schema_seen = False
+
+        context = ET.iterparse(_bytes_to_file(self._xml), events=("end",))
+        for _event, elem in context:
+            eid = elem.get("id")
+            if eid is not None:
+                self._id_cache[eid] = elem
+
+            if elem.tag == "schema" and not schema_seen:
+                self.columns = _parse_columns(elem)
+                schema_seen = True
+                continue
+
+            if elem.tag == "row":
+                yield _row_dict(elem, self.columns)
+                # Do not clear elem — children referenced via id may still be needed.
+
+
+def _parse_columns(schema_el: ET.Element) -> list[Column]:
+    cols: list[Column] = []
+    for col in schema_el.findall("col"):
+        mnemonic = (col.findtext("mnemonic") or "").strip()
+        etype = (col.findtext("engineering-type") or "").strip()
+        if mnemonic:
+            cols.append(Column(mnemonic=mnemonic, engineering_type=etype))
+    return cols
+
+
+def _row_dict(row_el: ET.Element, cols: list[Column]) -> dict[str, ET.Element]:
+    # Row children map positionally to columns. <sentinel/> marks a missing
+    # optional value for that column.
+    result: dict[str, ET.Element] = {}
+    children = list(row_el)
+    for idx, child in enumerate(children):
+        if idx >= len(cols):
+            break
+        if child.tag == "sentinel":
+            continue
+        result[cols[idx].mnemonic] = child
+    return result
+
+
+def _bytes_to_file(data: bytes):
+    import io
+    return io.BytesIO(data)
+
+
+# --- Extraction helpers ---------------------------------------------------
+
+def int_text(elem: ET.Element | None) -> int | None:
+    if elem is None or elem.text is None:
+        return None
+    try:
+        return int(elem.text)
+    except ValueError:
+        return None
+
+
+def str_text(elem: ET.Element | None) -> str | None:
+    if elem is None or elem.text is None:
+        return None
+    return elem.text
+
+
+def fmt_attr(elem: ET.Element | None) -> str | None:
+    """Return the human-readable `fmt` attribute if present."""
+    if elem is None:
+        return None
+    return elem.get("fmt")
+
+
+def extract_thread(thread_el: ET.Element, stream: RowStream) -> dict:
+    """Parse a <thread> element into name, tid, process dict.
+
+    Handles ref-style threads by resolving through the stream's id cache.
+    """
+    resolved = stream.resolve(thread_el)
+    name = resolved.get("fmt", "")
+    tid_el = resolved.find("tid")
+    process_el = resolved.find("process")
+    process = extract_process(process_el, stream) if process_el is not None else None
+    return {
+        "name": name,
+        "tid": int_text(tid_el),
+        "process": process,
+        "is_main": name.startswith("Main Thread") if name else False,
+    }
+
+
+def extract_process(process_el: ET.Element, stream: RowStream) -> dict:
+    resolved = stream.resolve(process_el)
+    name = resolved.get("fmt", "")
+    pid_el = resolved.find("pid")
+    return {
+        "name": _clean_process_name(name),
+        "pid": int_text(pid_el),
+    }
+
+
+def _clean_process_name(fmt: str) -> str:
+    # "NowPlaying Gigs (28401)" -> "NowPlaying Gigs"
+    if " (" in fmt and fmt.endswith(")"):
+        return fmt.rsplit(" (", 1)[0]
+    return fmt
+
+
+def extract_backtrace(
+    bt_el: ET.Element, stream: RowStream, max_frames: int = 20
+) -> list[dict]:
+    """Return a list of frame dicts from a <tagged-backtrace> or <backtrace>.
+
+    Frames are ordered leaf-first (top of stack first), matching Instruments'
+    display order.
+    """
+    resolved = stream.resolve(bt_el)
+    inner = resolved.find("backtrace")
+    if inner is None:
+        inner = resolved
+    frames: list[dict] = []
+    for frame_el in inner.findall("frame"):
+        f = stream.resolve(frame_el)
+        frames.append({
+            "name": f.get("name") or "",
+            "addr": f.get("addr") or "",
+        })
+        if len(frames) >= max_frames:
+            break
+    return frames
+
+
+def top_symbol(frames: list[dict]) -> str:
+    """Pick the leaf symbol, falling back to addr if unsymbolicated."""
+    if not frames:
+        return "<empty-stack>"
+    first = frames[0]
+    return first.get("name") or first.get("addr") or "<unknown>"
+
+
+def first_present(row: dict, *keys: str) -> ET.Element | None:
+    """Return the first row column whose key exists.
+
+    `row[key] or row[other_key]` is unsafe here: Element is falsy when it has
+    no children (a common case for leaf <event-time>, <start-time>, etc.), so
+    `or` short-circuits past valid leaf elements. This walks keys explicitly.
+    """
+    for key in keys:
+        el = row.get(key)
+        if el is not None:
+            return el
+    return None
+
+
+def in_window(time_ns: int | None, window: tuple[int, int] | None) -> bool:
+    """Return True if time_ns is inside [start, end] (inclusive), or window is None."""
+    if window is None:
+        return True
+    if time_ns is None:
+        return False
+    start, end = window
+    return start <= time_ns <= end
+
+
+def event_overlaps_window(
+    start_ns: int, end_ns: int, window: tuple[int, int] | None
+) -> bool:
+    """Return True if [start, end] overlaps [window.start, window.end]."""
+    if window is None:
+        return True
+    w_start, w_end = window
+    return not (end_ns < w_start or start_ns > w_end)

package/bundled-skills/swiftui-expert-skill/scripts/record_trace.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Record an Xcode Instruments .trace file via `xctrace record`.
+
+Three modes:
+  (default)          Start a recording. Stops on Ctrl+C, stop-file, or time limit.
+  --list-devices     Enumerate connected devices + simulators as JSON.
+  --list-templates   Enumerate available Instruments templates as JSON.
+
+Attach vs launch vs all-processes is mutually exclusive and passed straight
+through to xctrace. The default template is "SwiftUI" (matches the
+SwiftUI template in Xcode 26+ — change with --template).
+
+Manual stop options, most to least automated:
+  * Send SIGINT (Ctrl+C) to this script — forwarded to xctrace, which
+    finalises the trace before exiting.
+  * Pass --stop-file PATH; when that file appears on disk, this script
+    sends SIGINT to xctrace. Useful for `Bash run_in_background`
+    workflows where there's no interactive terminal.
+  * Pass --time-limit 30s / 5m / etc. — xctrace stops itself.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Record an Instruments .trace file.")
+    list_mode = parser.add_mutually_exclusive_group()
+    list_mode.add_argument("--list-devices", action="store_true",
+                           help="List devices and simulators as JSON, then exit.")
+    list_mode.add_argument("--list-templates", action="store_true",
+                           help="List template names as JSON, then exit.")
+
+    parser.add_argument("--template", default="SwiftUI",
+                        help="Template name (default: SwiftUI).")
+    parser.add_argument("--device", default=None,
+                        help="Device name or UDID. Defaults to the host.")
+    parser.add_argument("--output", type=Path, default=None,
+                        help="Output .trace path. Defaults to ./<template>-<timestamp>.trace.")
+    parser.add_argument("--time-limit", default=None,
+                        help="Cap recording duration (e.g. 30s, 5m, 1h). Optional.")
+    parser.add_argument("--stop-file", type=Path, default=None,
+                        help="When this path appears on disk, stop the recording.")
+    parser.add_argument("--env", action="append", default=[],
+                        metavar="KEY=VALUE",
+                        help="Env var for the launched process. Can repeat. Launch mode only.")
+    parser.add_argument("--instrument", action="append", default=[],
+                        help="Extra --instrument flag passthrough (can repeat).")
+    parser.add_argument("--run-name", default=None)
+
+    target = parser.add_mutually_exclusive_group()
+    target.add_argument("--launch", metavar="APP",
+                        help="Launch this .app path and record it.")
+    target.add_argument("--attach", metavar="PID_OR_NAME",
+                        help="Attach to a running process by pid or name.")
+    target.add_argument("--all-processes", action="store_true",
+                        help="Record every process (system-wide).")
+
+    args = parser.parse_args(argv)
+
+    if args.list_devices:
+        _print_devices()
+        return 0
+    if args.list_templates:
+        _print_templates()
+        return 0
+
+    if not (args.launch or args.attach or args.all_processes):
+        print("error: need one of --launch, --attach, or --all-processes.",
+              file=sys.stderr)
+        return 2
+
+    if args.env and not args.launch:
+        # xctrace silently ignores --env outside launch mode; surfacing this
+        # explicitly saves agents a confusing "why didn't my env var apply?".
+        print("error: --env only applies to --launch; remove it or switch target mode.",
+              file=sys.stderr)
+        return 2
+
+    output = args.output or Path.cwd() / _default_trace_name(args.template)
+    if output.exists():
+        print(f"error: output already exists: {output}", file=sys.stderr)
+        return 2
+
+    cmd = _build_xctrace_cmd(args, output)
+
+    # Tell the user (and an agent reading stdout) what's happening + how to stop.
+    print("[record] starting xctrace record", flush=True)
+    print(f"[record]   template: {args.template}", flush=True)
+    print(f"[record]   device:   {args.device or '(host)'}", flush=True)
+    print(f"[record]   target:   {_describe_target(args)}", flush=True)
+    print(f"[record]   output:   {output}", flush=True)
+    stop_hints = ["Ctrl+C"]
+    if args.stop_file:
+        stop_hints.append(f"`touch {args.stop_file}`")
+    if args.time_limit:
+        stop_hints.append(f"after {args.time_limit}")
+    print(f"[record] stop via: {', '.join(stop_hints)}", flush=True)
+    print(f"[record] cmd: {' '.join(_shell_quote(c) for c in cmd)}", flush=True)
+
+    # Start xctrace in its own process group so we can signal cleanly.
+    proc = subprocess.Popen(cmd, start_new_session=True)
+
+    try:
+        _wait_with_stop(proc, args.stop_file)
+    except KeyboardInterrupt:
+        _forward_sigint(proc)
+
+    # Give xctrace up to 60s to finalise after SIGINT — large traces take time.
+    try:
+        rc = proc.wait(timeout=60)
+    except subprocess.TimeoutExpired:
+        print("[record] xctrace did not exit within 60s after stop; killing.",
+              file=sys.stderr)
+        proc.kill()
+        rc = proc.wait()
+
+    if output.exists():
+        print(f"[record] done. trace written: {output}", flush=True)
+    else:
+        print("[record] done but output file not found — did xctrace error?",
+              file=sys.stderr)
+        return rc or 1
+    return rc
+
+
+def _build_xctrace_cmd(args, output: Path) -> list[str]:
+    cmd = ["xctrace", "record", "--template", args.template, "--output", str(output)]
+    if args.device:
+        cmd += ["--device", args.device]
+    if args.time_limit:
+        cmd += ["--time-limit", args.time_limit]
+    if args.run_name:
+        cmd += ["--run-name", args.run_name]
+    for inst in args.instrument:
+        cmd += ["--instrument", inst]
+    for env in args.env:
+        cmd += ["--env", env]
+    # Target must come last — --launch consumes the remainder.
+    if args.attach:
+        cmd += ["--attach", args.attach]
+    elif args.all_processes:
+        cmd += ["--all-processes"]
+    elif args.launch:
+        cmd += ["--launch", "--", args.launch]
+    return cmd
+
+
+def _describe_target(args) -> str:
+    if args.launch:
+        return f"launch {args.launch}"
+    if args.attach:
+        return f"attach {args.attach}"
+    if args.all_processes:
+        return "all processes"
+    return "(none)"
+
+
+def _default_trace_name(template: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9]+", "-", template).strip("-").lower() or "trace"
+    ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+    return f"{safe}-{ts}.trace"
+
+
+def _wait_with_stop(proc: subprocess.Popen, stop_file: Path | None) -> None:
+    """Poll until xctrace exits or stop_file appears; then send SIGINT."""
+    while True:
+        rc = proc.poll()
+        if rc is not None:
+            return
+        if stop_file and stop_file.exists():
+            print(f"[record] stop-file detected ({stop_file}); stopping xctrace.",
+                  flush=True)
+            _forward_sigint(proc)
+            return
+        time.sleep(0.5)
+
+
+def _forward_sigint(proc: subprocess.Popen) -> None:
+    try:
+        # Signal the whole group so child instruments tools also get SIGINT.
+        os.killpg(os.getpgid(proc.pid), signal.SIGINT)
+    except ProcessLookupError:
+        pass
+
+
+def _print_devices() -> None:
+    out = subprocess.run(
+        ["xctrace", "list", "devices"], capture_output=True, text=True, check=True
+    ).stdout
+    devices: list[dict] = []
+    section = None
+    # Device lines end with "(UDID)"; real iOS devices also have "(OS version)"
+    # before the UDID. The host (macOS) line has only "(UDID)".
+    line_re = re.compile(r"^(.+?)(?:\s+\(([^()]+)\))?\s+\(([0-9A-Fa-f-]{20,})\)\s*$")
+    for line in out.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("==") and stripped.endswith("=="):
+            section = stripped.strip("= ").strip().lower()
+            continue
+        m = line_re.match(stripped)
+        if not m:
+            continue
+        name, os_ver, udid = m.group(1).strip(), m.group(2), m.group(3)
+        devices.append({
+            "kind": section or "unknown",
+            "name": name,
+            "os": os_ver,
+            "udid": udid,
+        })
+    print(json.dumps({"devices": devices}, indent=2))
+
+
+def _print_templates() -> None:
+    out = subprocess.run(
+        ["xctrace", "list", "templates"], capture_output=True, text=True, check=True
+    ).stdout
+    groups: dict[str, list[str]] = {}
+    section = "unknown"
+    for line in out.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("==") and stripped.endswith("=="):
+            section = stripped.strip("= ").strip().lower()
+            groups.setdefault(section, [])
+            continue
+        groups.setdefault(section, []).append(stripped)
+    # Flat convenience list + structured by section.
+    flat = [name for items in groups.values() for name in items]
+    print(json.dumps({"templates": flat, "by_section": groups}, indent=2))
+
+
+def _shell_quote(s: str) -> str:
+    if re.match(r"^[A-Za-z0-9_./:=@-]+$", s):
+        return s
+    return "'" + s.replace("'", "'\\''") + "'"
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundled-skills/technical-tutorials/README.md

@@ -0,0 +1,90 @@
+# technical-tutorials
+
+**Step-by-step guides that actually work.**
+
+## What It Does
+
+Guides you through creating tutorials, quickstarts, and code walkthroughs. Covers prerequisites, progressive complexity, copy-paste friendly code, troubleshooting sections, and "it works!" moments.
+
+## When to Use
+
+- Creating a quickstart guide
+- Writing a step-by-step tutorial
+- Building a code walkthrough
+- When you say "tutorial," "quickstart," "getting started guide," or "how to guide"
+
+## Quick Start
+
+```
+/technical-tutorials
+
+Create a quickstart for our Python SDK.
+Target: Python developers new to our API.
+Goal: First successful API call in 5 minutes.
+```
+
+The skill will:
+1. Load your developer audience context
+2. Structure prerequisites clearly
+3. Build progressive complexity
+4. Add checkpoints and troubleshooting
+5. Ensure code is copy-paste ready
+
+## Key Frameworks
+
+### Tutorial Types
+
+| Type | Time | Purpose |
+|------|------|---------|
+| Quickstart | 5-10 min | First success ASAP |
+| Tutorial | 20-45 min | Learn a concept deeply |
+| Workshop | 1-3 hours | Comprehensive project |
+
+### Progressive Complexity (Layer Cake)
+
+1. Skeleton (minimum viable code)
+2. Core feature (primary functionality)
+3. Real data (replace hardcoded values)
+4. Error handling (production patterns)
+5. Polish (logging, config, tests)
+
+### Copy-Paste Checklist
+
+Every code block must:
+- Run standalone
+- Include all imports
+- Have no undefined variables
+- Work cross-platform
+- Explain why, not what
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `SKILL.md` | Full skill instructions with templates |
+
+## Templates Included
+
+- Quickstart template (5-10 min)
+- Full tutorial template (20-45 min)
+- Troubleshooting section format
+- Prerequisites section format
+
+## Quality Checklist
+
+- [ ] Every code block runs
+- [ ] Prerequisites are explicit
+- [ ] Time estimate is accurate
+- [ ] Checkpoints every 3-5 steps
+- [ ] Troubleshooting covers likely errors
+
+## Tools
+
+- **[Octolens](https://octolens.com)** — Find common questions for troubleshooting content
+- **Replit/CodeSandbox** — Embed runnable examples
+- **Excalidraw** — Architecture diagrams
+
+## Related Skills
+
+- `developer-audience-context` — Understand skill level
+- `devrel-content` — General technical writing