td-ai-tools 1.2.0 → 1.2.2

package/skills/debugging-ios-webkit/references/simulator.md

@@ -0,0 +1,76 @@
+
+# Debugging in the iOS Simulator
+
+Real iOS WebKit + real Safari chrome, scriptable from the terminal. The one
+hard limitation: **you cannot synthesize taps** (`simctl` has no touch API,
+and macOS blocks synthetic clicks without Accessibility permission).
+
+## Quick Start
+
+```bash
+xcrun simctl list devices available            # find a device + UDID
+open -a Simulator --args -CurrentDeviceUDID <UDID>
+xcrun simctl bootstatus <UDID> -b              # wait for boot
+xcrun simctl openurl booted "https://site.example/page"
+xcrun simctl io booted screenshot /tmp/shot.png
+```
+
+## Driving state without touch
+
+- **URL parameters the page already supports** — e.g. many themes open the
+  cart drawer on load with `?cart=open`; check the theme's JS for what it reads.
+- **Temporary debug hooks** — add a query-param-gated script to the page that
+  auto-runs the interaction sequence, sync it to a dev theme, load with the
+  param, screenshot on a timer, then remove the hook:
+
+```js
+if (new URLSearchParams(location.search).has('debug_cycles')) {
+  window.addEventListener('load', async () => {
+    const t = (ms) => new Promise(r => setTimeout(r, ms));
+    // example: cycle whatever component is under test
+    const d = document.querySelector('cart-drawer');
+    await t(2000); d.open(); await t(2500); d.close(); await t(1500); d.open();
+  });
+}
+```
+
+- **App-switch nudge** (forces visibility/viewport recalc):
+  `xcrun simctl launch booted com.apple.Preferences; sleep 2; xcrun simctl launch booted com.apple.mobilesafari`
+
+## Measuring screenshots
+
+Screenshots are 3x scale on Pro-class devices — divide pixels by 3 for CSS px.
+Pixel-scan with PIL rather than eyeballing:
+
+```python
+from PIL import Image
+im = Image.open('/tmp/shot.png').convert('RGB')
+# find rows containing the element's known background colour, measure the band
+```
+
+Comparing the measured painted box against the element's expected border-box
+identifies which box was painted: a background at exactly content-box size
+means padding wasn't painted (stale layer or native form-control painter).
+
+## Calibrating viewport units
+
+The simulator reaches your Mac's `localhost` directly. Serve a test page
+(`python3 -m http.server 8899`) with fixed-position divs of `100svh`,
+`100dvh`, `100lvh`, `100%` height and a `bottom: 0` marker, screenshot, and
+measure where each ends. This settles "which viewport is this unit tracking"
+arguments with data.
+
+## Shopify-specific gotchas
+
+- Preview/development themes show the **Draft bar**, which overlays the
+  bottom ~46pt of the viewport and covers bottom-anchored CTAs — it looks
+  exactly like a layout bug. Append `&pb=0` to hide it before judging.
+- Add items to the cart with
+  `openurl booted ".../cart/add?id=<variant>&quantity=1&return_to=/cart"`
+  (a `/cart/<variant>:1` permalink jumps straight to checkout — not useful).
+
+## When this level is not enough
+
+If the bug needs real touch gestures, device GPU behavior, or you have the
+broken state live on someone's phone, use references/device.md. For fast CSS iteration first, use
+references/playwright.md.

package/skills/debugging-ios-webkit/scripts/device_eval.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Evaluate JavaScript in a live Safari tab on a USB-connected iOS device.
+
+Usage:
+    python device_eval.py <url-substring> ['<js-expression>']
+
+The expression runs in the page and its return value is printed. Wrap DOM
+reads in an IIFE returning JSON.stringify(...) for structured output.
+Defaults to a generic element diagnostic if no expression is given.
+
+Requires: pip install pymobiledevice3 (Python >= 3.10)
+Phone: Settings -> Safari -> Advanced -> Web Inspector ON, tab foreground,
+screen unlocked, and no other inspector attached (close Mac Safari Develop).
+"""
+import asyncio
+import sys
+import uuid
+
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.services.webinspector import WebinspectorService
+from pymobiledevice3.services.web_protocol.inspector_session import InspectorSession
+from pymobiledevice3.services.web_protocol.session_protocol import SessionProtocol
+
+DEFAULT_EXPR = r"""(() => {
+  return JSON.stringify({
+    href: location.href.slice(0, 120),
+    theme: (window.Shopify && Shopify.theme) ? Shopify.theme : undefined,
+    vv: { h: Math.round(visualViewport.height), ih: innerHeight },
+  });
+})()"""
+
+
+async def attach(inspector, match):
+    pages = await inspector.get_open_application_pages(timeout=2)
+    ap = next((p for p in pages if match in (getattr(p.page, 'web_url', '') or '')), None)
+    if ap is None:
+        urls = [getattr(p.page, 'web_url', None) for p in pages]
+        raise SystemExit(f'no tab matching {match!r}; open tabs: {urls}')
+    session_id = str(uuid.uuid4()).upper()
+    # wait_target=True is required on iOS 17+ (Target-domain wrapped protocol)
+    session = await asyncio.wait_for(
+        InspectorSession.create(
+            SessionProtocol(inspector, session_id, ap.application, ap.page, method_prefix=""),
+            wait_target=True),
+        timeout=10)
+    await session.runtime_enable()
+    return session
+
+
+async def main():
+    match = sys.argv[1] if len(sys.argv) > 1 else 'http'
+    expr = sys.argv[2] if len(sys.argv) > 2 else DEFAULT_EXPR
+    lockdown = await create_using_usbmux()
+    inspector = WebinspectorService(lockdown=lockdown)
+    async with inspector:
+        session = await attach(inspector, match)
+        result = await asyncio.wait_for(session.runtime_evaluate(expr, return_by_value=True), timeout=15)
+        print(result)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

package/skills/debugging-ios-webkit/scripts/device_experiment.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Run stepped repair experiments on a live broken page while a human watches
+the device. Each step is announced with a colored banner injected into the
+page; the watcher reports which step number visually fixed the element.
+
+Usage:
+    python device_experiment.py <url-substring> [target-css-selector]
+
+Edit STEPS for the element/bug at hand. The winning step becomes the
+permanent fix, wired into the code path that precedes the broken state.
+"""
+import asyncio
+import sys
+import uuid
+
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.services.webinspector import WebinspectorService
+from pymobiledevice3.services.web_protocol.inspector_session import InspectorSession
+from pymobiledevice3.services.web_protocol.session_protocol import SessionProtocol
+
+TARGET = sys.argv[2] if len(sys.argv) > 2 else 'body'
+
+STEPS = [
+    ("STEP 1: banner only (sanity)", "void 0"),
+    ("STEP 2: opacity nudge", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        el.style.opacity = '0.99';
+        requestAnimationFrame(() => {{ el.style.opacity = ''; }}); }})()"""),
+    ("STEP 3: own compositing layer", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        el.style.transform = 'translateZ(0)'; }})()"""),
+    ("STEP 4: display rebuild", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        el.style.display = 'none'; void el.offsetHeight; el.style.display = ''; }})()"""),
+    ("STEP 5: reflow via class re-toggle", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        const p = el.parentElement; p.classList.add('td-exp-retoggle');
+        void p.offsetHeight; p.classList.remove('td-exp-retoggle'); }})()"""),
+    ("STEP 6: scroll nudge", """
+      (() => { const s = document.scrollingElement; s.scrollTop += 1; s.scrollTop -= 1; })()"""),
+]
+
+BANNER = """
+(() => {
+  let el = document.getElementById('td-exp-banner');
+  if (!el) {
+    el = document.createElement('div');
+    el.id = 'td-exp-banner';
+    el.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:2147483647;padding:18px;font:bold 24px -apple-system;text-align:center;color:#fff;';
+    document.body.appendChild(el);
+  }
+  el.style.background = COLOR;
+  el.textContent = LABEL;
+})()
+"""
+
+COLORS = ['#c0392b', '#d35400', '#f39c12', '#27ae60', '#2980b9', '#8e44ad']
+
+
+async def main():
+    match = sys.argv[1] if len(sys.argv) > 1 else 'http'
+    lockdown = await create_using_usbmux()
+    inspector = WebinspectorService(lockdown=lockdown)
+    async with inspector:
+        pages = await inspector.get_open_application_pages(timeout=2)
+        ap = next((p for p in pages if match in (getattr(p.page, 'web_url', '') or '')), None)
+        if ap is None:
+            raise SystemExit(f'no tab matching {match!r}')
+        session_id = str(uuid.uuid4()).upper()
+        session = await asyncio.wait_for(
+            InspectorSession.create(
+                SessionProtocol(inspector, session_id, ap.application, ap.page, method_prefix=""),
+                wait_target=True),
+            timeout=10)
+        await session.runtime_enable()
+
+        async def banner(color, label):
+            await session.runtime_evaluate(BANNER.replace('COLOR', repr(color)).replace('LABEL', repr(label)))
+
+        # Lead-in so the watcher can reproduce the broken state first
+        for remaining in range(20, 0, -5):
+            await banner('#111', f'BREAK IT NOW — reproduce the bug. Steps start in {remaining}s')
+            print(f'lead-in {remaining}s', flush=True)
+            await asyncio.sleep(5)
+
+        for i, (label, code) in enumerate(STEPS):
+            await banner(COLORS[i % len(COLORS)], label + ' — fixed?')
+            await session.runtime_evaluate(code)
+            print('ran', label, flush=True)
+            await asyncio.sleep(5)
+
+        await banner('#111', 'DONE — report which step fixed it')
+        await asyncio.sleep(6)
+        await session.runtime_evaluate("document.getElementById('td-exp-banner')?.remove()")
+        print('done', flush=True)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

package/skills/debugging-ios-webkit/scripts/device_snapshot.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Capture a Page.snapshotRect PNG from a live Safari tab on a USB device.
+
+Usage:
+    python device_snapshot.py <url-substring> [out.png] [x y w h]
+
+IMPORTANT: the snapshot repaints from the render tree. If the snapshot looks
+CORRECT while the device screen looks BROKEN, the bug is a stale compositor
+texture (paint bug), not a layout bug — fix with a paint invalidation (e.g.
+opacity nudge), not with CSS.
+"""
+import asyncio
+import base64
+import json
+import sys
+import uuid
+
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.services.webinspector import WebinspectorService
+from pymobiledevice3.services.web_protocol.inspector_session import InspectorSession
+from pymobiledevice3.services.web_protocol.session_protocol import SessionProtocol
+
+
+async def main():
+    match = sys.argv[1] if len(sys.argv) > 1 else 'http'
+    out = sys.argv[2] if len(sys.argv) > 2 else 'snapshot.png'
+    x, y, w, h = (int(a) for a in sys.argv[3:7]) if len(sys.argv) > 6 else (0, 0, 430, 932)
+
+    lockdown = await create_using_usbmux()
+    inspector = WebinspectorService(lockdown=lockdown)
+    async with inspector:
+        pages = await inspector.get_open_application_pages(timeout=2)
+        ap = next((p for p in pages if match in (getattr(p.page, 'web_url', '') or '')), None)
+        if ap is None:
+            raise SystemExit(f'no tab matching {match!r}')
+        session_id = str(uuid.uuid4()).upper()
+        session = await asyncio.wait_for(
+            InspectorSession.create(
+                SessionProtocol(inspector, session_id, ap.application, ap.page, method_prefix=""),
+                wait_target=True),
+            timeout=10)
+
+        mid = await session.send_message_to_target({'method': 'Page.enable', 'params': {}})
+        await asyncio.wait_for(session.receive_response_by_id(mid), timeout=10)
+
+        mid = await session.send_message_to_target(
+            {'method': 'Page.snapshotRect',
+             'params': {'x': x, 'y': y, 'width': w, 'height': h, 'coordinateSystem': 'Viewport'}})
+        res = await asyncio.wait_for(session.receive_response_by_id(mid), timeout=15)
+        # iOS 17+ wraps responses in the Target domain — unwrap
+        if res.get('method') == 'Target.dispatchMessageFromTarget':
+            res = json.loads(res['params']['message'])
+        data = res.get('result', res).get('dataURL', '')
+        if not data.startswith('data:image/png;base64,'):
+            raise SystemExit(f'snapshot failed: {json.dumps(res)[:200]}')
+        with open(out, 'wb') as f:
+            f.write(base64.b64decode(data.split(',', 1)[1]))
+        print('saved', out)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

package/skills/record-changes/SKILL.md

@@ -33,8 +33,8 @@ Use the script output to identify changed files, then inspect the relevant diffs
 Prioritize:
 
 - User-facing behavior changes
-- Theme setting/schema changes
-- CSS or markup changes that affect storefront rendering
+- CMS setting/schema changes
+- CSS or markup changes that affect rendering
 - Renamed files and vendor-theme hotspots
 
 Do not summarize the `docs/changes.md` edit itself as part of the branch work. If the branch contains unrelated skill or tooling files, either omit them from the changelog entry or separate them clearly when they are relevant to the project's maintenance history.
@@ -57,7 +57,7 @@ Guidelines:
 - Make the title describe the feature or fix, not the branch name.
 - Write `Purpose` in plain language with outcome-focused bullets.
 - Use the `Files changed` table to explain why each file matters.
-- Call out non-`td-` theme or vendor files in a separate subsection when they are upgrade-sensitive.
+- Call out non-`td-` theme or vendor files in a separate subsection when in a Shopify project.
 - Mention renamed files explicitly.
 - Keep `Upgrade impact` brief and concrete.
 - Use `Notes` for implementation details, edge cases, or assumptions.

package/skills/shopify-lint/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: shopify-lint
+version: 1.0.0
+description: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on offenses in files modified on the current Git branch. Use when Codex needs to lint a Shopify theme, validate branch-scoped Liquid or theme changes, enforce Theory theme rules, or avoid surfacing pre-existing Theme Check offenses from untouched files.
+---
+
+# Shopify Lint
+
+## Setup
+
+The bundled `theme-check-theory` custom-check package ships as TypeScript source only; its `node_modules` and compiled `dist/` are not committed. Run setup once before the first run (and after upgrading the skill):
+
+```bash
+bash .agents/skills/shopify-lint/scripts/setup.sh
+```
+
+Installing with `td-ai-tools install --setup shopify-lint` runs this automatically. The script:
+
+1. Runs `npm install && npm run build` inside `theme-check-theory/`, producing `dist/index.js` — the CommonJS entry point the root `.theme-check.yml` requires.
+2. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. If one already exists it is left untouched; ensure its `require:` list includes `./.agents/skills/shopify-lint/theme-check-theory`.
+
+Keep these dependencies inside `theme-check-theory/node_modules`; do not install Node dependencies at the theme root.
+
+## Usage
+
+Run the bundled Python script from the Shopify theme root:
+
+```bash
+python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
+```
+
+The script runs `shopify theme check --output json`, identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, and emits only reports whose paths are in that set. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory.
+
+## Workflow
+
+1. Confirm `shopify` and `python3` are available.
+2. Run the bundled script instead of calling `shopify theme check` directly.
+3. Treat exit code `0` as no failing offenses in modified files, `1` as filtered offenses at or above the fail level, and `2` as a Git, CLI, or JSON-processing error.
+4. Fix reported issues and rerun until the command passes. Do not fix offenses in untouched files unless the user expands the scope.
+5. Keep custom-check dependencies inside `theme-check-theory/node_modules`. Do not install Node dependencies at the theme root.
+
+The default base is `origin/HEAD`, then `origin/main`, `main`, `origin/master`, or `master`. Override it when needed:
+
+```bash
+python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path . --base-ref origin/develop
+```
+
+Set `SHOPIFY_LINT_BASE_REF` for the same override in automation. Use `--format json` for machine-readable filtered output and `--fail-level warning` or `--fail-level info` for stricter runs. When passing `--config <path>`, preserve the bundled package's `require` entry or the Theory checks will not load.
+
+Do not use Theme Check auto-correction through this workflow because it can modify untouched files before filtering.

package/skills/shopify-lint/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Shopify Lint"
+  short_description: "Lint modified theme files with Theory checks"
+  default_prompt: "Use $shopify-lint to run Theme Check for files modified on my current branch."

package/skills/shopify-lint/scripts/setup.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shopify-lint setup
+#
+# Run automatically by the installer (`--setup`) from the installed skill
+# directory, or manually with `bash scripts/setup.sh`. It:
+#   1. Builds the bundled `theme-check-theory` custom-check package
+#      (its node_modules and dist/ are intentionally not committed).
+#   2. Writes a `.theme-check.yml` at the project root that wires the bundled
+#      checks into Shopify CLI Theme Check.
+
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PKG_DIR="$SKILL_DIR/theme-check-theory"
+
+# 1. Build the bundled custom-check package.
+echo "shopify-lint setup: building theme-check-theory in $PKG_DIR"
+cd "$PKG_DIR"
+npm install
+npm run build
+
+# 2. Generate the project-root .theme-check.yml.
+#
+# The installed layout is <project>/<.agents|.claude>/skills/shopify-lint, so
+# the project root is three levels above the skill directory. Guard against
+# running outside that layout (e.g. from the catalog repo) to avoid writing the
+# config into an unexpected directory.
+TARGET_DIR="$(cd "$SKILL_DIR/../.." && pwd)"
+TARGET_BASE="$(basename "$TARGET_DIR")"
+if [[ "$TARGET_BASE" != ".agents" && "$TARGET_BASE" != ".claude" ]]; then
+  echo "shopify-lint setup: unrecognized install layout ($TARGET_DIR); skipping .theme-check.yml generation." >&2
+  exit 0
+fi
+
+PROJECT_ROOT="$(dirname "$TARGET_DIR")"
+THEME_CHECK_FILE="$PROJECT_ROOT/.theme-check.yml"
+
+if [[ -f "$THEME_CHECK_FILE" ]]; then
+  echo "shopify-lint setup: $THEME_CHECK_FILE already exists; leaving it unchanged."
+  echo "  Ensure its 'require:' list includes ./.agents/skills/shopify-lint/theme-check-theory"
+  exit 0
+fi
+
+cat > "$THEME_CHECK_FILE" <<'YAML'
+extends:
+  - theme-check:recommended
+
+require:
+  - ./.agents/skills/shopify-lint/theme-check-theory
+
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+YAML
+
+echo "shopify-lint setup: wrote $THEME_CHECK_FILE"