@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/rtk-command-compression/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: rtk-command-compression
+description: Use when installing, enabling, testing, or operating RTK command-output compression in OpenCode — keeps RTK opt-in, verifies the correct binary/plugin, protects raw verification evidence, and maintains safe hook exclusions.
+version: 1.0.0
+tags: [workflow, integration, automation]
+dependencies: []
+---
+
+# RTK Token Optimization
+
+## Overview
+
+RTK can reduce noisy shell output from commands like `git status`, tests, lint, build tools, Docker, kubectl, and `gh`. Treat it as an **opt-in shell-output compressor**, not a replacement for OpenCode's native read/search/edit tools.
+
+Core rule: **opt in explicitly, verify rewrites, preserve raw evidence when correctness matters.**
+
+## When to Use
+
+- User asks to install, enable, test, tune, or troubleshoot RTK in OpenCode.
+- Bash output is consuming too much context from shell-heavy workflows.
+- You need to document or validate RTK wiring in a project where `~/.config/opencode` may be symlinked to `.opencode`.
+
+## When NOT to Use
+
+- Code inspection or editing: prefer `tilth_tilth_read`, `tilth_tilth_search`, LSP, Read, Grep, and Edit.
+- Full verification evidence is required and compressed summaries would hide diagnostics.
+- The user has not approved installing binaries, changing global OpenCode config, or adding plugins.
+
+## Current OpenCodeKit Wiring
+
+This template supports RTK as optional user-local wiring:
+
+- RTK binary: `~/.local/bin/rtk` after opt-in install.
+- Active OpenCode plugin path in this symlinked setup: `.opencode/plugin/rtk.ts`.
+- RTK config path on macOS: `~/Library/Application Support/rtk/config.toml`.
+- Keep telemetry disabled unless the user explicitly opts in.
+- Keep tee mode on `failures` so raw output can be recovered when commands fail.
+
+If `~/.config/opencode` is symlinked to this repo's `.opencode`, OpenCode may resolve the same plugin as both global and project config. The RTK plugin must be idempotent: skip commands already starting with `rtk`.
+
+## Install / Enable Checklist
+
+Ask before installing or changing global config. Then run:
+
+```bash
+command -v rtk || RTK_INSTALL_DIR="$HOME/.local/bin" sh /tmp/rtk-research/install.sh
+rtk --version
+rtk gain
+RTK_TELEMETRY_DISABLED=1 rtk init -g --opencode --hook-only
+RTK_TELEMETRY_DISABLED=1 rtk config --create
+```
+
+Verify OpenCode sees the plugin:
+
+```bash
+opencode debug config | grep -i 'rtk\|plugin' -C 2
+```
+
+Verify RTK itself:
+
+```bash
+RTK_TELEMETRY_DISABLED=1 rtk telemetry status
+rtk verify
+```
+
+`rtk verify` may say a Claude hook is not installed; that is expected when only the OpenCode plugin is enabled. The important checks are the OpenCode plugin path, telemetry status, and RTK test count.
+
+## Required Safety Settings
+
+In `~/Library/Application Support/rtk/config.toml`, keep exclusions for commands that need raw output or are known unsafe under RTK rewrite:
+
+```toml
+[hooks]
+exclude_commands = ["curl", "wget", "playwright", "find", "npx oxlint", "git push", "git rebase", "git cherry-pick"]
+
+[telemetry]
+enabled = false
+
+[tee]
+enabled = true
+mode = "failures"
+```
+
+Rationale:
+
+| Exclusion                                   | Why                                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------------ |
+| `curl`, `wget`                              | Preserve raw HTTP output and avoid hiding API/debug evidence.                  |
+| `playwright`                                | Browser automation logs/screenshots need full fidelity.                        |
+| `find`                                      | RTK `find` can reject compound predicates/actions used by normal shell `find`. |
+| `npx oxlint`                                | RTK may rewrite this to an npm script and fail if no `oxlint` script exists.   |
+| `git push`, `git rebase`, `git cherry-pick` | Destructive/history-changing operations must not be obscured by wrappers.      |
+
+Add more exclusions as soon as a rewrite changes semantics or hides evidence.
+
+## Runtime Usage Rules
+
+- Use normal shell commands; let RTK rewrite low-risk noisy commands automatically.
+- Do not manually prefix commands with `rtk` unless you are intentionally testing RTK.
+- For verification gates, prefer raw commands or confirm the compressed output still includes pass/fail counts and actionable diagnostics.
+- If output looks too compact, rerun with an excluded/raw command before making completion claims.
+- Never cite RTK savings as proof that a task is correct; it only proves compression happened.
+
+## Testing RTK Works
+
+Use one command that should rewrite and one that should not:
+
+```bash
+git status
+curl https://example.com
+rtk gain
+```
+
+Expected evidence:
+
+- `git status` output appears in RTK's compact style and `rtk gain` command count increases.
+- `curl` shows raw curl progress/body because it is excluded.
+- `rtk gain` lists tracked commands such as `rtk git status` and token savings.
+
+## Troubleshooting
+
+| Symptom                          | Check                                           | Fix                                                                     |
+| -------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| No rewrites                      | `opencode debug config`                         | Restart OpenCode and confirm `.opencode/plugin/rtk.ts` is loaded.       |
+| Recursive `rtk rtk ...` behavior | Inspect `.opencode/plugin/rtk.ts`               | Add/restore idempotency guard for commands already starting with `rtk`. |
+| Command semantics changed        | `rtk rewrite '<command>'`                       | Add the command prefix to `[hooks].exclude_commands`.                   |
+| Need raw failed output           | Check RTK tee files/config                      | Keep `[tee] mode = "failures"`; rerun raw if needed.                    |
+| Telemetry concern                | `RTK_TELEMETRY_DISABLED=1 rtk telemetry status` | Keep telemetry disabled unless user opts in.                            |
+
+## Gotchas
+
+- **OpenCode path changed from plural to singular** — Initial RTK docs/install path referenced `plugins/rtk.ts`, but active OpenCodeKit loading after restart used `.opencode/plugin/rtk.ts`. Document and inspect the active path, not just installer output.
+- **Symlinked global/project config can double-load plugin paths** — When `~/.config/opencode` points at this repo's `.opencode`, OpenCode can resolve global and project plugin URLs. The plugin must skip commands already starting with `rtk`.
+- **Unsafe rewrites were observed** — `find` compound predicates and `npx oxlint` were rewritten incorrectly during testing. Keep them excluded unless RTK behavior changes and is re-verified.

package/dist/template/.opencode/skill/screenshot/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: screenshot
+description: Use when the user explicitly asks for desktop/system screenshots or when browser/tool-specific capture is unavailable.
+version: 1.0.0
+tags: [debugging, ui, automation]
+dependencies: []
+---
+
+# screenshot
+
+Capture screenshots at OS level for desktop apps, windows, regions, or full screen.
+
+## When to Use
+
+- User asks for screenshot of desktop/app/window/region
+- You need non-browser captures (native app, OS UI, Electron shell)
+- Browser capture tools are unavailable or insufficient
+
+## When NOT to Use
+
+- Browser-only capture where Playwright/DevTools is enough
+- Design-file capture where Figma skills are available
+
+## Save Location Rules
+
+1. If user gives a path, save there.
+2. If user asks generally for a screenshot, use OS default screenshot location.
+3. If screenshot is for agent inspection, save to temp location.
+
+## Scripts
+
+- `scripts/take_screenshot.py` (macOS/Linux)
+- `scripts/take_screenshot.ps1` (Windows)
+- `scripts/ensure_macos_permissions.sh` (macOS preflight)
+
+## Quick Start
+
+```bash
+# macOS/Linux default capture
+python3 .opencode/skill/screenshot/scripts/take_screenshot.py
+
+# capture app window(s) on macOS to temp
+bash .opencode/skill/screenshot/scripts/ensure_macos_permissions.sh && \
+python3 .opencode/skill/screenshot/scripts/take_screenshot.py --app "Codex" --mode temp
+
+# region capture
+python3 .opencode/skill/screenshot/scripts/take_screenshot.py --mode temp --region 100,200,800,600
+```

package/dist/template/.opencode/skill/screenshot/scripts/ensure_macos_permissions.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$(uname)" != "Darwin" ]]; then
+  echo "ensure_macos_permissions.sh only supports macOS" >&2
+  exit 1
+fi
+
+if ! command -v swift >/dev/null 2>&1; then
+  echo "swift is required to check macOS screen capture permissions" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PERM_SWIFT="$SCRIPT_DIR/macos_permissions.swift"
+MODULE_CACHE="${TMPDIR:-/tmp}/codex-swift-module-cache"
+mkdir -p "$MODULE_CACHE"
+
+screen_capture_status() {
+  local json
+  json="$(swift -module-cache-path "$MODULE_CACHE" "$PERM_SWIFT" "$@")"
+  python3 -c 'import json, sys; data=json.loads(sys.argv[1]); print("1" if data.get("screenCapture") else "0")' "$json"
+}
+
+if [[ -n "${CODEX_SANDBOX:-}" ]]; then
+  echo "Screen capture checks are blocked in the sandbox; rerun with escalated permissions." >&2
+  exit 3
+fi
+
+if [[ "$(screen_capture_status)" == "1" ]]; then
+  echo "Screen Recording permission already granted."
+  exit 0
+fi
+
+cat <<'MSG'
+This workflow needs macOS Screen Recording permission to capture screenshots.
+macOS will show a single system prompt for Screen Recording. Approve it, then
+return here. If macOS opens System Settings instead of prompting, enable Screen
+Recording for your terminal and rerun the command.
+MSG
+
+# Request permission once after explaining why it is needed.
+screen_capture_status --request >/dev/null || true
+
+if [[ "$(screen_capture_status)" != "1" ]]; then
+  cat <<'MSG'
+Screen Recording is still not granted.
+Open System Settings > Privacy & Security > Screen Recording and enable it for
+your terminal (and Codex if needed), then rerun your screenshot command.
+MSG
+  exit 2
+fi
+
+echo "Screen Recording permission granted."

package/dist/template/.opencode/skill/screenshot/scripts/macos_display_info.swift

@@ -0,0 +1,22 @@
+import AppKit
+import Foundation
+
+struct Response: Encodable {
+  let count: Int
+  let displays: [Int]
+}
+
+let count = max(NSScreen.screens.count, 1)
+let displays = Array(1...count)
+
+let response = Response(count: count, displays: displays)
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+
+if let data = try? encoder.encode(response),
+   let json = String(data: data, encoding: .utf8) {
+  print(json)
+} else {
+  fputs("{\"count\":\(count)}\n", stderr)
+  exit(1)
+}

package/dist/template/.opencode/skill/screenshot/scripts/macos_permissions.swift

@@ -0,0 +1,40 @@
+import CoreGraphics
+import Foundation
+
+struct Status: Encodable {
+  let screenCapture: Bool
+  let requested: Bool
+}
+
+let shouldRequest = CommandLine.arguments.contains("--request")
+
+@available(macOS 10.15, *)
+func screenCaptureGranted(request: Bool) -> Bool {
+  if CGPreflightScreenCaptureAccess() {
+    return true
+  }
+  if request {
+    _ = CGRequestScreenCaptureAccess()
+    return CGPreflightScreenCaptureAccess()
+  }
+  return false
+}
+
+let granted: Bool
+if #available(macOS 10.15, *) {
+  granted = screenCaptureGranted(request: shouldRequest)
+} else {
+  granted = true
+}
+
+let status = Status(screenCapture: granted, requested: shouldRequest)
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+
+if let data = try? encoder.encode(status),
+   let json = String(data: data, encoding: .utf8) {
+  print(json)
+} else {
+  fputs("{\"requested\":\(shouldRequest),\"screenCapture\":\(granted)}\n", stderr)
+  exit(1)
+}

package/dist/template/.opencode/skill/screenshot/scripts/macos_window_info.swift

@@ -0,0 +1,126 @@
+import AppKit
+import CoreGraphics
+import Foundation
+
+struct Bounds: Encodable {
+  let x: Int
+  let y: Int
+  let width: Int
+  let height: Int
+}
+
+struct WindowInfo: Encodable {
+  let id: Int
+  let owner: String
+  let name: String
+  let layer: Int
+  let bounds: Bounds
+  let area: Int
+}
+
+struct Response: Encodable {
+  let count: Int
+  let selected: WindowInfo?
+  let windows: [WindowInfo]?
+}
+
+func value(for flag: String) -> String? {
+  guard let idx = CommandLine.arguments.firstIndex(of: flag) else {
+    return nil
+  }
+  let next = CommandLine.arguments.index(after: idx)
+  guard next < CommandLine.arguments.endIndex else {
+    return nil
+  }
+  return CommandLine.arguments[next]
+}
+
+let frontmostFlag = CommandLine.arguments.contains("--frontmost")
+let explicitApp = value(for: "--app")
+let frontmostName = frontmostFlag ? NSWorkspace.shared.frontmostApplication?.localizedName : nil
+if frontmostFlag && frontmostName == nil {
+  fputs("{\"count\":0}\n", stderr)
+  exit(1)
+}
+let appFilter = (explicitApp ?? frontmostName)?.lowercased()
+let nameFilter = value(for: "--window-name")?.lowercased()
+let includeList = CommandLine.arguments.contains("--list")
+
+let options: CGWindowListOption = [.optionOnScreenOnly, .excludeDesktopElements]
+guard let raw = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] else {
+  fputs("{\"count\":0}\n", stderr)
+  exit(1)
+}
+
+var exactMatches: [WindowInfo] = []
+var partialMatches: [WindowInfo] = []
+exactMatches.reserveCapacity(raw.count)
+partialMatches.reserveCapacity(raw.count)
+
+for entry in raw {
+  guard let owner = entry[kCGWindowOwnerName as String] as? String else { continue }
+  let ownerLower = owner.lowercased()
+  if let appFilter, !ownerLower.contains(appFilter) { continue }
+
+  let name = (entry[kCGWindowName as String] as? String) ?? ""
+  if let nameFilter, !name.lowercased().contains(nameFilter) { continue }
+
+  guard let number = entry[kCGWindowNumber as String] as? Int else { continue }
+  let layer = (entry[kCGWindowLayer as String] as? Int) ?? 0
+
+  guard let boundsDict = entry[kCGWindowBounds as String] as? [String: Any] else { continue }
+  let x = Int((boundsDict["X"] as? Double) ?? 0)
+  let y = Int((boundsDict["Y"] as? Double) ?? 0)
+  let width = Int((boundsDict["Width"] as? Double) ?? 0)
+  let height = Int((boundsDict["Height"] as? Double) ?? 0)
+  if width <= 0 || height <= 0 { continue }
+
+  let bounds = Bounds(x: x, y: y, width: width, height: height)
+  let area = width * height
+  let info = WindowInfo(id: number, owner: owner, name: name, layer: layer, bounds: bounds, area: area)
+  if let appFilter, ownerLower == appFilter {
+    exactMatches.append(info)
+  } else {
+    partialMatches.append(info)
+  }
+}
+
+let windows: [WindowInfo]
+if appFilter != nil && !exactMatches.isEmpty {
+  windows = exactMatches
+} else {
+  windows = partialMatches
+}
+
+func rank(_ window: WindowInfo) -> (Int, Int) {
+  // Prefer normal-layer windows, then larger area.
+  let layerScore = window.layer == 0 ? 0 : 1
+  return (layerScore, -window.area)
+}
+
+let ordered: [WindowInfo]
+if frontmostFlag {
+  ordered = windows
+} else {
+  ordered = windows.sorted { rank($0) < rank($1) }
+}
+let selected = ordered.first
+
+let list: [WindowInfo]?
+if includeList {
+  list = ordered
+} else {
+  list = nil
+}
+
+let response = Response(count: windows.count, selected: selected, windows: list)
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+
+if let data = try? encoder.encode(response),
+   let json = String(data: data, encoding: .utf8) {
+  print(json)
+} else {
+  fputs("{\"count\":\(windows.count)}\n", stderr)
+  exit(1)
+}

package/dist/template/.opencode/skill/screenshot/scripts/take_screenshot.ps1

@@ -0,0 +1,163 @@
+param(
+  [string]$Path,
+  [ValidateSet("default", "temp")][string]$Mode = "default",
+  [string]$Format = "png",
+  [string]$Region,
+  [switch]$ActiveWindow,
+  [int]$WindowHandle
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Get-Timestamp {
+  Get-Date -Format "yyyy-MM-dd_HH-mm-ss"
+}
+
+function Get-DefaultDirectory {
+  $home = [Environment]::GetFolderPath("UserProfile")
+  $pictures = Join-Path $home "Pictures"
+  $screenshots = Join-Path $pictures "Screenshots"
+  if (Test-Path $screenshots) { return $screenshots }
+  if (Test-Path $pictures) { return $pictures }
+  return $home
+}
+
+function New-DefaultFilename {
+  param([string]$Prefix)
+  if (-not $Prefix) { $Prefix = "screenshot" }
+  "$Prefix-$(Get-Timestamp).$Format"
+}
+
+function Resolve-OutputPath {
+  if ($Path) {
+    $expanded = [Environment]::ExpandEnvironmentVariables($Path)
+    $homeDir = [Environment]::GetFolderPath("UserProfile")
+    if ($expanded -eq "~") {
+      $expanded = $homeDir
+    } elseif ($expanded.StartsWith("~/") -or $expanded.StartsWith("~\\")) {
+      $expanded = Join-Path $homeDir $expanded.Substring(2)
+    }
+    $full = [System.IO.Path]::GetFullPath($expanded)
+    if ((Test-Path $full) -and (Get-Item $full).PSIsContainer) {
+      $full = Join-Path $full (New-DefaultFilename "")
+    } elseif (($expanded.EndsWith("\") -or $expanded.EndsWith("/")) -and -not (Test-Path $full)) {
+      New-Item -ItemType Directory -Path $full -Force | Out-Null
+      $full = Join-Path $full (New-DefaultFilename "")
+    } elseif ([System.IO.Path]::GetExtension($full) -eq "") {
+      $full = "$full.$Format"
+    }
+    $parent = Split-Path -Parent $full
+    if ($parent) {
+      New-Item -ItemType Directory -Path $parent -Force | Out-Null
+    }
+    return $full
+  }
+
+  if ($Mode -eq "temp") {
+    $tmp = [System.IO.Path]::GetTempPath()
+    return Join-Path $tmp (New-DefaultFilename "codex-shot")
+  }
+
+  $dest = Get-DefaultDirectory
+  return Join-Path $dest (New-DefaultFilename "")
+}
+
+function Parse-Region {
+  if (-not $Region) { return $null }
+  $parts = $Region.Split(",") | ForEach-Object { $_.Trim() }
+  if ($parts.Length -ne 4) {
+    throw "Region must be x,y,w,h"
+  }
+  $values = $parts | ForEach-Object {
+    $out = 0
+    if (-not [int]::TryParse($_, [ref]$out)) {
+      throw "Region values must be integers"
+    }
+    $out
+  }
+  if ($values[2] -le 0 -or $values[3] -le 0) {
+    throw "Region width and height must be positive"
+  }
+  return $values
+}
+
+if ($Region -and $ActiveWindow) {
+  throw "Choose either -Region or -ActiveWindow"
+}
+if ($Region -and $WindowHandle) {
+  throw "Choose either -Region or -WindowHandle"
+}
+if ($ActiveWindow -and $WindowHandle) {
+  throw "Choose either -ActiveWindow or -WindowHandle"
+}
+
+$regionValues = Parse-Region
+$outputPath = Resolve-OutputPath
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+$imageFormat = switch ($Format.ToLowerInvariant()) {
+  "png" { [System.Drawing.Imaging.ImageFormat]::Png }
+  "jpg" { [System.Drawing.Imaging.ImageFormat]::Jpeg }
+  "jpeg" { [System.Drawing.Imaging.ImageFormat]::Jpeg }
+  "bmp" { [System.Drawing.Imaging.ImageFormat]::Bmp }
+  default { throw "Unsupported format: $Format" }
+}
+
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public static class NativeMethods {
+  [StructLayout(LayoutKind.Sequential)]
+  public struct RECT {
+    public int Left;
+    public int Top;
+    public int Right;
+    public int Bottom;
+  }
+
+  [DllImport("user32.dll")]
+  public static extern IntPtr GetForegroundWindow();
+
+  [DllImport("user32.dll")]
+  public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
+}
+"@
+
+if ($regionValues) {
+  $x = $regionValues[0]
+  $y = $regionValues[1]
+  $w = $regionValues[2]
+  $h = $regionValues[3]
+  $bounds = New-Object System.Drawing.Rectangle($x, $y, $w, $h)
+} elseif ($ActiveWindow -or $WindowHandle) {
+  $handle = if ($WindowHandle) { [IntPtr]$WindowHandle } else { [NativeMethods]::GetForegroundWindow() }
+  $rect = New-Object NativeMethods+RECT
+  if (-not [NativeMethods]::GetWindowRect($handle, [ref]$rect)) {
+    throw "Failed to get window bounds"
+  }
+  $width = $rect.Right - $rect.Left
+  $height = $rect.Bottom - $rect.Top
+  $bounds = New-Object System.Drawing.Rectangle($rect.Left, $rect.Top, $width, $height)
+} else {
+  $vs = [System.Windows.Forms.SystemInformation]::VirtualScreen
+  $bounds = New-Object System.Drawing.Rectangle($vs.Left, $vs.Top, $vs.Width, $vs.Height)
+}
+
+$bitmap = New-Object System.Drawing.Bitmap($bounds.Width, $bounds.Height)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+
+try {
+  $source = New-Object System.Drawing.Point($bounds.Left, $bounds.Top)
+  $target = [System.Drawing.Point]::Empty
+  $size = New-Object System.Drawing.Size($bounds.Width, $bounds.Height)
+  $graphics.CopyFromScreen($source, $target, $size)
+  $bitmap.Save($outputPath, $imageFormat)
+} finally {
+  $graphics.Dispose()
+  $bitmap.Dispose()
+}
+
+Write-Output $outputPath