td-ai-tools 1.0.2

package/skills/record-changes/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: record-changes
+description: Update `docs/changes.md` by summarizing the current branch against the primary development branch. Use when a developer asks to record branch changes, document theme customizations, refresh the project change log, or write a branch summary into `docs/changes.md`. Prefer comparing against `main`, but fall back to `origin/main`, `master`, or `origin/master` when the repository does not have a local `main` branch.
+---
+
+# Record Changes
+
+Update `docs/changes.md` from the current branch diff. Preserve the existing document structure and add a concise, human-readable entry for the branch.
+
+## Workflow
+
+### 1. Collect Branch Context
+
+Run the bundled script first:
+
+```bash
+python3 .agents/skills/record-changes/scripts/branch_diff_context.py
+```
+
+If the developer specifies another comparison branch, pass it explicitly:
+
+```bash
+python3 .agents/skills/record-changes/scripts/branch_diff_context.py --base release/x.y
+```
+
+Read the existing `docs/changes.md` before editing so the new entry matches the current ordering, tone, and section layout.
+
+### 2. Inspect the Actual Code Changes
+
+Use the script output to identify changed files, then inspect the relevant diffs and file contents with `git diff` and targeted file reads.
+
+Prioritize:
+
+- User-facing behavior changes
+- Theme setting/schema changes
+- CSS or markup changes that affect storefront 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.
+
+### 3. Write the Changelog Entry
+
+Add a new entry near the top of `docs/changes.md`, directly under the intro, unless the file already uses another ordering convention.
+
+Follow the existing pattern:
+
+- `## <short title>`
+- `**Date:** YYYY-MM-DD`
+- `### Purpose`
+- `### Files changed`
+- `### Upgrade impact`
+- `### Notes`
+
+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.
+- Mention renamed files explicitly.
+- Keep `Upgrade impact` brief and concrete.
+- Use `Notes` for implementation details, edge cases, or assumptions.
+
+### 4. Verify Before Finishing
+
+Before wrapping up:
+
+- Re-read the new markdown entry in context.
+- Confirm every listed file appears in the diff.
+- Confirm the documented behavior matches the code, not just the branch name.
+- Mention any uncertainty if the diff is too broad to summarize with high confidence.
+
+## Resource
+
+- `scripts/branch_diff_context.py`: Resolve the best available base branch and print a branch summary with file statuses and line counts.

package/skills/record-changes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+    display_name: 'Record Changes'
+    short_description: 'Summarize branch changes into docs/changes.md'
+    default_prompt: 'Use $record-changes to compare this branch to main and update docs/changes.md.'

package/skills/record-changes/scripts/branch_diff_context.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+
+DEFAULT_BASE_CANDIDATES = ("main", "origin/main", "master", "origin/master")
+
+
+def run_git(*args: str) -> str:
+    completed = subprocess.run(
+        ["git", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def ref_exists(ref: str) -> bool:
+    completed = subprocess.run(
+        ["git", "rev-parse", "--verify", f"{ref}^{{commit}}"],
+        capture_output=True,
+        text=True,
+    )
+    return completed.returncode == 0
+
+
+def resolve_base_ref(explicit_base: str | None) -> str:
+    if explicit_base:
+        if not ref_exists(explicit_base):
+            raise SystemExit(f"Base ref not found: {explicit_base}")
+        return explicit_base
+
+    for candidate in DEFAULT_BASE_CANDIDATES:
+        if ref_exists(candidate):
+            return candidate
+
+    searched = ", ".join(DEFAULT_BASE_CANDIDATES)
+    raise SystemExit(f"No base ref found. Tried: {searched}")
+
+
+def parse_name_status(output: str) -> list[dict[str, str]]:
+    files = []
+    for line in output.splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        status = parts[0]
+
+        if status.startswith("R") and len(parts) >= 3:
+            files.append(
+                {
+                    "status": status,
+                    "path": parts[2],
+                    "old_path": parts[1],
+                }
+            )
+            continue
+
+        path = parts[1] if len(parts) > 1 else ""
+        files.append({"status": status, "path": path, "old_path": ""})
+    return files
+
+
+def parse_numstat(output: str) -> dict[str, dict[str, str]]:
+    stats = {}
+    for line in output.splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        additions, deletions, path = parts[0], parts[1], parts[2]
+        stats[path] = {"additions": additions, "deletions": deletions}
+    return stats
+
+
+def resolve_stats(
+    numstat: dict[str, dict[str, str]], path: str, old_path: str
+) -> dict[str, str] | None:
+    stats = numstat.get(path)
+    if stats or not old_path:
+        return stats
+
+    path_dir = os.path.dirname(path)
+    old_dir = os.path.dirname(old_path)
+    path_name = os.path.basename(path)
+    old_name = os.path.basename(old_path)
+
+    for candidate_path, candidate_stats in numstat.items():
+        if old_path in candidate_path and path in candidate_path:
+            return candidate_stats
+        if (
+            path_dir == old_dir
+            and path_dir
+            and candidate_path.startswith(f"{path_dir}/")
+            and old_name in candidate_path
+            and path_name in candidate_path
+        ):
+            return candidate_stats
+
+    return None
+
+
+def build_context(base_ref: str) -> dict[str, object]:
+    current_branch = run_git("branch", "--show-current")
+    merge_base = run_git("merge-base", base_ref, "HEAD")
+    shortstat = run_git("diff", "--shortstat", merge_base, "HEAD")
+    name_status = parse_name_status(
+        run_git("diff", "--name-status", "--find-renames", merge_base, "HEAD")
+    )
+    numstat = parse_numstat(run_git("diff", "--numstat", "--find-renames", merge_base, "HEAD"))
+
+    for entry in name_status:
+        stats = resolve_stats(numstat, entry["path"], entry["old_path"])
+        entry["additions"] = stats["additions"] if stats else "?"
+        entry["deletions"] = stats["deletions"] if stats else "?"
+
+    return {
+        "current_branch": current_branch,
+        "base_ref": base_ref,
+        "merge_base": merge_base,
+        "shortstat": shortstat,
+        "files": name_status,
+    }
+
+
+def print_markdown(context: dict[str, object]) -> None:
+    print("# Branch Change Context")
+    print()
+    print(f"- Current branch: `{context['current_branch']}`")
+    print(f"- Base ref: `{context['base_ref']}`")
+    print(f"- Merge base: `{context['merge_base']}`")
+    print(f"- Summary: {context['shortstat'] or 'No changes detected'}")
+    print()
+
+    files = context["files"]
+    if not files:
+        print("No changed files detected.")
+        return
+
+    print("| Status | Path | +/- |")
+    print("|--------|------|-----|")
+
+    for entry in files:
+        status = entry["status"]
+        path = entry["path"]
+        if entry["old_path"]:
+            path = f"{entry['old_path']} -> {entry['path']}"
+        delta = f"+{entry['additions']} / -{entry['deletions']}"
+        print(f"| `{status}` | `{path}` | {delta} |")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve a base branch and print context for documenting branch changes."
+    )
+    parser.add_argument(
+        "--base",
+        help="Explicit base ref to compare against. Defaults to main/origin-main or master/origin-master fallback.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format.",
+    )
+    args = parser.parse_args()
+
+    base_ref = resolve_base_ref(args.base)
+    context = build_context(base_ref)
+
+    if args.format == "json":
+        print(json.dumps(context, indent=2))
+    else:
+        print_markdown(context)
+
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except subprocess.CalledProcessError as error:
+        sys.stderr.write(error.stderr or str(error))
+        raise SystemExit(error.returncode)

package/skills/stylesheet-migration/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: stylesheet-migration
+description: Migrate Shopify Liquid `{% stylesheet %}` blocks into theme CSS assets using bundled Python scripts. Use when moving inline section or snippet stylesheet tags into `assets/*.css`, especially in `sections/` and `snippets/`. By default the scripts only process filenames that start with `td-`, creating `section-<source>.css` for files in `sections/` and `component-<source>.css` for files in `snippets/`, unless the caller specifies a different prefix or disables the prefix filter.
+---
+
+# Stylesheet Migration
+
+Run the bundled CLI from the theme root:
+
+```bash
+python3 .agents/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py --dry-run
+```
+
+Default behavior
+- Scans `sections/*.liquid` and `snippets/*.liquid`.
+- Only considers filenames that start with `td-`.
+- Extracts CSS from each `{% stylesheet %}...{% endstylesheet %}` block.
+- Writes assets to `assets/section-<stem>.css` or `assets/component-<stem>.css`.
+- Inserts `{{ '...' | asset_url | stylesheet_tag }}` at the top of the source file, below any leading doc comment, and removes all stylesheet blocks from the source file.
+
+Common variants
+- Different prefix: `python3 .agents/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py --prefix promo-`
+- Multiple prefixes: `python3 .agents/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py --prefix td- --prefix promo-`
+- No prefix filter: `python3 .agents/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py --no-prefix-filter`
+- Limit the scope to specific files or directories: `python3 .agents/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py sections/td-main-bundle-product.liquid snippets/`
+- Overwrite an existing asset when its contents differ: `python3 .agents/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py --overwrite-assets`
+
+Workflow
+1. Run with `--dry-run` first.
+2. Review the planned asset names and any conflicts.
+3. Re-run without `--dry-run` once the scope is correct.
+
+Notes
+- Files outside `sections/` and `snippets/` are ignored.
+- Existing asset files are preserved unless `--overwrite-assets` is passed.
+- If the Liquid file already includes the generated asset, the script removes the inline stylesheet block without inserting a duplicate include.

package/skills/stylesheet-migration/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Stylesheet Migration"
+  short_description: "Move Liquid stylesheet blocks into theme CSS assets"
+  default_prompt: "Use $stylesheet-migration to move `{% stylesheet %}` blocks from Shopify Liquid files into asset CSS files."
+policy:
+  allow_implicit_invocation: true

package/skills/stylesheet-migration/scripts/liquid_stylesheet_migrator.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+DEFAULT_PREFIXES = ("td-",)
+DEFAULT_SOURCE_DIRS = ("sections", "snippets")
+
+STYLESHEET_BLOCK_RE = re.compile(
+    r"(?P<indent>^[ \t]*)\{%-?\s*stylesheet\s*-?%\}[ \t]*\r?\n?"
+    r"(?P<content>.*?)"
+    r"(?:(?:\r?\n)?(?P=indent))\{%-?\s*endstylesheet\s*-?%\}[ \t]*(?:\r?\n)?",
+    re.DOTALL | re.MULTILINE,
+)
+LIQUID_COMMENT_BLOCK_RE = re.compile(
+    r"\{%-?\s*comment\s*-?%\}.*?\{%-?\s*endcomment\s*-?%\}",
+    re.DOTALL,
+)
+LEADING_COMMENT_RE = re.compile(
+    r"^(?P<comment>\{%-?\s*comment\s*-?%\}.*?\{%-?\s*endcomment\s*-?%\})(?P<spacing>(?:\r?\n)*)",
+    re.DOTALL,
+)
+
+
+@dataclass(frozen=True)
+class MigrationPlan:
+    source_path: Path
+    asset_path: Path
+    asset_name: str
+    asset_content: str
+    updated_source: str
+    block_count: int
+    include_inserted: bool
+
+
+class MigrationError(RuntimeError):
+    """Raised when a source file cannot be migrated safely."""
+
+
+def read_text_preserve_newlines(path: Path) -> str:
+    with path.open("r", encoding="utf-8", newline="") as handle:
+        return handle.read()
+
+
+def write_text_preserve_newlines(path: Path, content: str) -> None:
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        handle.write(content)
+
+
+def detect_newline(text: str) -> str:
+    return "\r\n" if "\r\n" in text else "\n"
+
+
+def is_supported_source(root: Path, path: Path) -> bool:
+    try:
+        relative_path = path.relative_to(root)
+    except ValueError:
+        return False
+
+    return (
+        path.is_file()
+        and path.suffix == ".liquid"
+        and len(relative_path.parts) >= 2
+        and relative_path.parts[0] in DEFAULT_SOURCE_DIRS
+    )
+
+
+def asset_name_for_source(root: Path, source_path: Path) -> str:
+    relative_path = source_path.relative_to(root)
+    source_dir = relative_path.parts[0]
+
+    if source_dir == "sections":
+        prefix = "section-"
+    elif source_dir == "snippets":
+        prefix = "component-"
+    else:
+        raise MigrationError(
+            f"{source_path} must live in sections/ or snippets/ to derive an asset name."
+        )
+
+    return f"{prefix}{source_path.stem}.css"
+
+
+def build_asset_include(asset_name: str, indent: str = "") -> str:
+    return f"{indent}{{{{ '{asset_name}' | asset_url | stylesheet_tag }}}}"
+
+
+def build_asset_include_pattern(asset_name: str) -> re.Pattern[str]:
+    return re.compile(
+        r"\{\{\-?\s*['\"]"
+        + re.escape(asset_name)
+        + r"['\"]\s*\|\s*asset_url\s*\|\s*stylesheet_tag(?:\s*:\s*[^}]*)?\s*\-?\}\}"
+    )
+
+
+def normalize_stylesheet_content(content: str, newline: str) -> str:
+    normalized = content.replace("\r\n", "\n").strip("\n")
+    return normalized.replace("\n", newline)
+
+
+def find_active_stylesheet_matches(source_text: str) -> list[re.Match[str]]:
+    comment_ranges = [
+        (match.start(), match.end()) for match in LIQUID_COMMENT_BLOCK_RE.finditer(source_text)
+    ]
+
+    return [
+        match
+        for match in STYLESHEET_BLOCK_RE.finditer(source_text)
+        if not any(
+            comment_start <= match.start() and match.end() <= comment_end
+            for comment_start, comment_end in comment_ranges
+        )
+    ]
+
+
+def insert_include_at_top(source_text: str, asset_name: str, newline: str) -> str:
+    include = build_asset_include(asset_name)
+    match = LEADING_COMMENT_RE.match(source_text)
+
+    if match:
+        comment = match.group("comment")
+        body = source_text[match.end() :].lstrip("\r\n")
+        return f"{comment}{newline}{newline}{include}{newline}{newline}{body}" if body else (
+            f"{comment}{newline}{newline}{include}{newline}"
+        )
+
+    body = source_text.lstrip("\r\n")
+    return f"{include}{newline}{newline}{body}" if body else f"{include}{newline}"
+
+
+def plan_migration(root: Path, source_path: Path) -> MigrationPlan | None:
+    source_text = read_text_preserve_newlines(source_path)
+    matches = find_active_stylesheet_matches(source_text)
+
+    if not matches:
+        return None
+
+    newline = detect_newline(source_text)
+    asset_name = asset_name_for_source(root, source_path)
+    asset_path = root / "assets" / asset_name
+    asset_include_exists = bool(build_asset_include_pattern(asset_name).search(source_text))
+
+    asset_chunks = [
+        normalize_stylesheet_content(match.group("content"), newline)
+        for match in matches
+        if match.group("content").strip()
+    ]
+    if not asset_chunks:
+        raise MigrationError(f"{source_path} contains only empty stylesheet blocks.")
+
+    updated_parts: list[str] = []
+    cursor = 0
+    include_inserted = False
+    keep_existing_include = asset_include_exists
+
+    for match in matches:
+        updated_parts.append(source_text[cursor : match.start()])
+        cursor = match.end()
+
+    updated_parts.append(source_text[cursor:])
+    updated_source = "".join(updated_parts)
+
+    if not keep_existing_include:
+        updated_source = insert_include_at_top(updated_source, asset_name, newline)
+        include_inserted = True
+
+    asset_content = (f"{newline}{newline}".join(asset_chunks)).rstrip("\r\n") + newline
+
+    return MigrationPlan(
+        source_path=source_path,
+        asset_path=asset_path,
+        asset_name=asset_name,
+        asset_content=asset_content,
+        updated_source=updated_source,
+        block_count=len(matches),
+        include_inserted=include_inserted,
+    )
+
+
+def validate_migration(plan: MigrationPlan, overwrite_assets: bool = False) -> None:
+    if not plan.asset_path.exists():
+        return
+
+    existing_asset = read_text_preserve_newlines(plan.asset_path)
+    if existing_asset != plan.asset_content and not overwrite_assets:
+        raise MigrationError(
+            f"{plan.asset_path} already exists with different contents. "
+            "Re-run with --overwrite-assets to replace it."
+        )
+
+
+def write_migration(plan: MigrationPlan, overwrite_assets: bool = False) -> None:
+    plan.asset_path.parent.mkdir(parents=True, exist_ok=True)
+    validate_migration(plan, overwrite_assets=overwrite_assets)
+
+    if plan.asset_path.exists():
+        existing_asset = read_text_preserve_newlines(plan.asset_path)
+        if existing_asset != plan.asset_content:
+            write_text_preserve_newlines(plan.asset_path, plan.asset_content)
+    else:
+        write_text_preserve_newlines(plan.asset_path, plan.asset_content)
+
+    write_text_preserve_newlines(plan.source_path, plan.updated_source)

package/skills/stylesheet-migration/scripts/migrate_stylesheet_tags.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from liquid_stylesheet_migrator import (
+    DEFAULT_PREFIXES,
+    DEFAULT_SOURCE_DIRS,
+    MigrationError,
+    is_supported_source,
+    plan_migration,
+    validate_migration,
+    write_migration,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Move Shopify Liquid {% stylesheet %} blocks into assets/*.css files. "
+            "By default only files whose names start with td- are processed."
+        )
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="Optional files or directories to scan. Defaults to sections/ and snippets/.",
+    )
+    parser.add_argument(
+        "--root",
+        default=".",
+        help="Theme root directory. Defaults to the current working directory.",
+    )
+    parser.add_argument(
+        "--prefix",
+        action="append",
+        dest="prefixes",
+        help="Filename prefix to include. May be passed multiple times. Defaults to td-.",
+    )
+    parser.add_argument(
+        "--no-prefix-filter",
+        action="store_true",
+        help="Process all supported Liquid files in scope, regardless of filename prefix.",
+    )
+    parser.add_argument(
+        "--overwrite-assets",
+        action="store_true",
+        help="Overwrite an existing generated asset when its contents differ.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the planned migrations without writing any files.",
+    )
+    return parser.parse_args()
+
+
+def resolve_path(root: Path, raw_path: str) -> Path:
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = root / path
+    return path.resolve()
+
+
+def collect_source_paths(root: Path, raw_paths: list[str]) -> tuple[list[Path], list[str]]:
+    discovered: list[Path] = []
+    errors: list[str] = []
+
+    if raw_paths:
+        candidates = [resolve_path(root, raw_path) for raw_path in raw_paths]
+    else:
+        candidates = [root / source_dir for source_dir in DEFAULT_SOURCE_DIRS]
+
+    for candidate in candidates:
+        if not candidate.exists():
+            errors.append(f"{candidate} does not exist.")
+            continue
+
+        if candidate.is_dir():
+            discovered.extend(sorted(candidate.rglob("*.liquid")))
+        elif candidate.is_file():
+            discovered.append(candidate)
+        else:
+            errors.append(f"{candidate} is not a file or directory.")
+
+    unique_paths = sorted({path.resolve() for path in discovered})
+    return unique_paths, errors
+
+
+def matches_prefix(path: Path, prefixes: tuple[str, ...], no_prefix_filter: bool) -> bool:
+    return no_prefix_filter or any(path.name.startswith(prefix) for prefix in prefixes)
+
+
+def summarize_count(count: int, singular: str, plural: str | None = None) -> str:
+    if count == 1:
+        return f"1 {singular}"
+    return f"{count} {plural or singular + 's'}"
+
+
+def main() -> int:
+    args = parse_args()
+    root = Path(args.root).resolve()
+    prefixes = tuple(args.prefixes or DEFAULT_PREFIXES)
+
+    source_paths, collection_errors = collect_source_paths(root, args.paths)
+    for message in collection_errors:
+        print(f"ERROR {message}", file=sys.stderr)
+
+    if not source_paths:
+        if collection_errors:
+            return 1
+        print("No Liquid files found in scope.", file=sys.stderr)
+        return 1
+
+    eligible_paths = [
+        path
+        for path in source_paths
+        if is_supported_source(root, path) and matches_prefix(path, prefixes, args.no_prefix_filter)
+    ]
+
+    ignored_count = len(source_paths) - len(eligible_paths)
+    migrated_count = 0
+    no_block_count = 0
+    error_count = len(collection_errors)
+
+    for source_path in eligible_paths:
+        relative_source = source_path.relative_to(root)
+        try:
+            plan = plan_migration(root, source_path)
+            if plan is None:
+                no_block_count += 1
+                continue
+
+            relative_asset = plan.asset_path.relative_to(root)
+            include_note = "reused existing include" if not plan.include_inserted else "inserted include"
+
+            if args.dry_run:
+                validate_migration(plan, overwrite_assets=args.overwrite_assets)
+                action = "Would migrate"
+            else:
+                write_migration(plan, overwrite_assets=args.overwrite_assets)
+                action = "Migrated"
+
+            print(
+                f"{action} {relative_source} -> {relative_asset} "
+                f"({summarize_count(plan.block_count, 'block')}; {include_note})"
+            )
+
+            migrated_count += 1
+        except MigrationError as exc:
+            print(f"ERROR {relative_source}: {exc}", file=sys.stderr)
+            error_count += 1
+
+    summary = [
+        summarize_count(len(source_paths), "candidate"),
+        summarize_count(len(eligible_paths), "eligible file"),
+        summarize_count(migrated_count, "migration"),
+        summarize_count(no_block_count, "file without a stylesheet block", "files without stylesheet blocks"),
+    ]
+    if ignored_count:
+        summary.append(summarize_count(ignored_count, "ignored file"))
+    if error_count:
+        summary.append(summarize_count(error_count, "error"))
+
+    print("Summary: " + ", ".join(summary))
+    return 1 if error_count else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())