uidetox 0.1.0__py3-none-any.whl

uidetox/__init__.py

@@ -0,0 +1,3 @@
+"""UIdetox Python Package"""
+
+__version__ = "0.1.0"

uidetox/analyzer.py

@@ -0,0 +1,227 @@
+"""Static Slop Analyzer: Detects AI anti-patterns via regex/AST rules."""
+
+import os
+import re
+from pathlib import Path
+
+# Directories to always skip during traversal
+IGNORE_DIRS = {
+    ".git", "node_modules", "dist", "build", "out", ".next", 
+    ".nuxt", "coverage", ".uidetox", ".claude", ".cursor", "vendor"
+}
+
+# The Anti-Pattern Rule Catalog
+RULES = [
+    {
+        "id": "TYPOGRAPHY_SLOP",
+        "pattern": re.compile(r'\b(font-(inter|roboto|sans|arial|open-sans)|font-family:\s*(Inter|Roboto|Arial|System-ui))\b', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".css", ".scss", ".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Generic AI Typography detected (Inter/Roboto/sans).",
+        "command": "Swap font family to a distinctive typeface (Geist, Outfit, Satoshi, etc.) and update scale."
+    },
+    {
+        "id": "COLOR_GRADIENT_SLOP",
+        "pattern": re.compile(r'\b(from-(blue|purple|indigo)-[4-6]00.*?to-(purple|blue|indigo)-[4-6]00)\b', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "AI Pipeline Palette (Purple-Blue gradient) detected.",
+        "command": "Replace generic gradient with a high-contrast solid accent color on a neutral base."
+    },
+    {
+        "id": "COLOR_BLACK_SLOP",
+        "pattern": re.compile(r'\b(#000000|bg-black|text-black)\b', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".css", ".scss", ".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Pure black (#000000) detected. Pure black rarely exists in nature.",
+        "command": "Replace true black with tinted dark neutrals (e.g. zinc-950 or slate-900)."
+    },
+    {
+        "id": "ICONOGRAPHY_SLOP",
+        "pattern": re.compile(r'\blucide-react\b', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".ts", ".js"},
+        "description": "Generic 'lucide-react' standard icons detected.",
+        "command": "Swap icon library for Phosphor Icons, Heroicons, or custom SVG to build unique identity."
+    },
+    {
+        "id": "MATERIALITY_RADIUS_SLOP",
+        "pattern": re.compile(r'\b(rounded-2xl|rounded-3xl)\b', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Oversized AI border radii (2xl/3xl) detected outside of modals/avatars.",
+        "command": "Reduce border-radius to tighter bounds (rounded-lg or rounded-xl) for precision."
+    },
+    {
+        "id": "LAYOUT_MATH_SLOP",
+        "pattern": re.compile(r'\b(w-1/3|grid-cols-3)\b', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Generic 3-Column feature card layout detected.",
+        "command": "Refactor into an asymmetrical grid, zig-zag layout, or masonry flow to break predictability."
+    },
+    {
+        "id": "GLASSMORPHISM_SLOP",
+        "pattern": re.compile(r'\b(backdrop-blur|glass-?morphism|bg-white/\d|bg-opacity-)\b', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".css", ".scss", ".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Glassmorphism pattern detected — strong AI fingerprint.",
+        "command": "Replace with solid surfaces, subtle borders, or elevation via shadow hierarchy."
+    },
+    {
+        "id": "SHADOW_SLOP",
+        "pattern": re.compile(r'\b(shadow-2xl|shadow-3xl|shadow-\[0_\d+px)\b', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".css", ".scss", ".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Oversized AI shadow detected (2xl/3xl).",
+        "command": "Use subtle shadows (shadow-sm, shadow-md) or border-based elevation instead."
+    },
+    {
+        "id": "HERO_DASHBOARD_SLOP",
+        "pattern": re.compile(r'\b(stat-?card|metric-?card|dashboard-?hero|stats-?grid|kpi-?card)\b', re.IGNORECASE),
+        "tier": "T3",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Hero metric dashboard pattern detected — cliché AI layout.",
+        "command": "Replace with contextual data visualization or inline metrics woven into the narrative flow."
+    },
+    {
+        "id": "BOUNCE_ANIMATION_SLOP",
+        "pattern": re.compile(r'\b(animate-bounce|animate-pulse|animate-spin)\b', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".css", ".scss", ".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Generic Tailwind animation (bounce/pulse/spin) detected.",
+        "command": "Replace with intentional micro-interactions using CSS transitions or spring physics."
+    },
+    {
+        "id": "GRAY_ON_COLOR_SLOP",
+        "pattern": re.compile(r'text-gray-[3-5]00.*?bg-(blue|purple|green|indigo|violet)-', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Gray text on colored background detected — low contrast AI pattern.",
+        "command": "Use white or high-contrast text on colored backgrounds. Check WCAG AA contrast ratio."
+    },
+    {
+        "id": "MISSING_DARK_MODE",
+        "pattern": re.compile(r'(?:bg-(white|gray|slate|zinc)-[12]00|bg-white)\b(?!.*dark:)', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Light background without dark: variant detected.",
+        "command": "Add dark mode variants (dark:bg-zinc-900) for every light surface color."
+    },
+    {
+        "id": "SPACING_REPETITION_SLOP",
+        "pattern": re.compile(r'(p-4|gap-4|space-y-4)(?:.*\1){4,}', re.DOTALL),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Excessive identical spacing repetition detected (5+ p-4/gap-4).",
+        "command": "Introduce spacing scale variation (mix p-3, p-5, p-6) to create visual rhythm."
+    },
+    {
+        "id": "CSS_GRADIENT_SLOP",
+        "pattern": re.compile(r'linear-gradient\s*\([^)]*(?:purple|indigo|violet).*?(?:blue|cyan|sky)', re.IGNORECASE),
+        "tier": "T1",
+        "exts": {".css", ".scss", ".less", ".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "CSS linear-gradient with purple-to-blue spectrum detected.",
+        "command": "Replace with a single accent color or a more subtle, brand-aligned gradient."
+    },
+    {
+        "id": "GENERIC_COPY_SLOP",
+        "pattern": re.compile(r'\b(Supercharge|Revolutionize|Unlock the power|Seamlessly|Take your .* to the next level|Effortlessly)\b', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue", ".md"},
+        "description": "Generic AI startup marketing copy detected.",
+        "command": "Rewrite copy to be specific, concrete, and human. Describe what the product does, not what it 'unlocks'."
+    },
+    {
+        "id": "MISSING_HOVER_STATES",
+        "pattern": re.compile(r'<button[^>]*(?!hover:)[^>]*className', re.IGNORECASE),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Button element without hover: state detected.",
+        "command": "Add hover:, focus:, and active: states to all interactive elements."
+    },
+    {
+        "id": "EMOJI_HEAVY_SLOP",
+        "pattern": re.compile(r'[\U0001f300-\U0001f9ff](?:.*[\U0001f300-\U0001f9ff]){5,}', re.DOTALL),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Emoji-heavy UI detected (6+ emoji in one file) — common AI pattern.",
+        "command": "Replace decorative emoji with proper iconography or remove entirely. Keep emoji only in user content."
+    },
+    {
+        "id": "OPACITY_ABUSE_SLOP",
+        "pattern": re.compile(r'(?:opacity-\d{1,2}|bg-.*?/\d{1,2})(?:.*(?:opacity-\d{1,2}|bg-.*?/\d{1,2})){4,}', re.DOTALL),
+        "tier": "T2",
+        "exts": {".tsx", ".jsx", ".html", ".svelte", ".vue"},
+        "description": "Excessive opacity/transparency usage detected (glassmorphism cousin).",
+        "command": "Use solid colors. Reserve transparency for overlays and modals only."
+    },
+]
+
+def analyze_file(filepath: Path) -> list[dict]:
+    """Scan a single file against all slop rules."""
+    issues = []
+    ext = filepath.suffix.lower()
+    
+    # Filter rules that apply to this file extension
+    applicable_rules = [r for r in RULES if ext in r["exts"]]
+    if not applicable_rules:
+        return issues
+        
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return issues # Skip binary or unreadable files
+        
+    for rule in applicable_rules:
+        # Prevent spam by only flagging a rule once per file
+        if rule["pattern"].search(content):
+            issues.append({
+                "file": str(filepath.resolve()),
+                "tier": rule["tier"],
+                "issue": rule["description"],
+                "command": rule["command"]
+            })
+            
+    return issues
+
+def analyze_directory(root_path: str = ".", exclude_paths: list[str] | None = None,
+                      zone_overrides: dict[str, str] | None = None) -> list[dict]:
+    """Walk directory and return a flat list of all detected slop issues.
+
+    Args:
+        root_path: Directory to scan.
+        exclude_paths: Additional directory names/paths to skip (from ``uidetox exclude``).
+        zone_overrides: File-to-zone mapping; files in 'vendor' or 'generated' zones are skipped.
+    """
+    all_issues = []
+    root = Path(root_path).resolve()
+
+    # Merge user excludes with built-in ignore list
+    skip_dirs = set(IGNORE_DIRS)
+    if exclude_paths:
+        for ep in exclude_paths:
+            skip_dirs.add(ep.strip("/").split("/")[-1] if "/" in ep else ep)
+
+    # Build a set of absolute paths to skip via zone overrides
+    zone_skip: set[str] = set()
+    if zone_overrides:
+        for fpath, zone in zone_overrides.items():
+            if zone in ("vendor", "generated"):
+                zone_skip.add(str(Path(fpath).resolve()))
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Mutate dirnames in-place to skip IGNORE_DIRS + user excludes
+        dirnames[:] = [d for d in dirnames if d not in skip_dirs and not d.startswith('.')]
+
+        for filename in filenames:
+            file_path = Path(dirpath) / filename
+
+            # Respect zone overrides
+            if zone_skip and str(file_path.resolve()) in zone_skip:
+                continue
+
+            found_issues = analyze_file(file_path)
+            all_issues.extend(found_issues)
+
+    return all_issues

uidetox/cli.py

@@ -0,0 +1,221 @@
+"""CLI entry point for UIdetox."""
+
+import argparse
+import sys
+from importlib import import_module
+from pathlib import Path
+
+
+def _get_version() -> str:
+    """Return package version."""
+    try:
+        from uidetox import __version__
+        return __version__
+    except ImportError:
+        return "0.1.0"
+
+
+def _get_commands_dir() -> Path | None:
+    """Find the commands/ directory next to the package or project root."""
+    try:
+        from uidetox.state import get_project_root
+        cmd_dir = get_project_root() / "commands"
+        if cmd_dir.exists():
+            return cmd_dir
+    except Exception:
+        pass
+    # Fallback: installed package location
+    pkg_root = Path(__file__).resolve().parent.parent
+    cmd_dir = pkg_root / "commands"
+    if cmd_dir.exists():
+        return cmd_dir
+    return None
+
+
+def parse_args(args_list=None):
+    parser = argparse.ArgumentParser(
+        prog="uidetox",
+        description="UIdetox — agent harness to eliminate AI slop and enforce code quality across frontend, backend, and database layers."
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_get_version()}")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Command: setup
+    setup_parser = subparsers.add_parser("setup", help="Gather project design context and configure dials")
+    setup_parser.add_argument("--auto-commit", action="store_true", help="Enable automated git commits for resolved issues")
+    
+    # Command: scan
+    scan_parser = subparsers.add_parser("scan", help="Full diagnostic audit of frontend interface quality")
+    scan_parser.add_argument("--path", default=".", help="Directory to scan")
+
+    # Command: add-issue (For agent use during scan)
+    add_parser = subparsers.add_parser("add-issue", help="Add an issue to the state queue (Agent use)")
+    add_parser.add_argument("--file", required=True, help="File path with the issue")
+    add_parser.add_argument("--tier", required=True, choices=["T1", "T2", "T3", "T4"], help="Severity tier")
+    add_parser.add_argument("--issue", required=True, help="Description of the issue")
+    add_parser.add_argument("--fix-command", required=True, help="Suggested command to fix")
+
+    # Command: next
+    next_parser = subparsers.add_parser("next", help="Picks the next highest-priority issue from the scan queue")
+
+    # Command: resolve
+    resolve_parser = subparsers.add_parser("resolve", help="Mark a specific issue as resolved")
+    resolve_parser.add_argument("issue_id", help="The ID of the issue to resolve (e.g. SCAN-001)")
+    resolve_parser.add_argument("--note", required=True, help="Mandatory explanation of the fix applied")
+
+    # Command: plan
+    plan_parser = subparsers.add_parser("plan", help="Reorder priorities or cluster related issues in the queue")
+    
+    # Command: review
+    review_parser = subparsers.add_parser("review", help="Subjective UX review of the latest changes")
+    
+    # Command: update-skill
+    update_parser = subparsers.add_parser("update-skill", help="Installs UIdetox rules into your agent's configuration")
+    update_parser.add_argument("agent", choices=["claude", "cursor", "gemini", "codex", "windsurf", "copilot"], help="Target AI agent")
+
+    # Command: status
+    status_parser = subparsers.add_parser("status", help="Show project health dashboard with design score")
+    status_parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    # Command: show
+    show_parser = subparsers.add_parser("show", help="Show details of issues, filter by file/tier/ID")
+    show_parser.add_argument("pattern", nargs="?", default=None, help="Filter by issue ID, file path, or tier (T1-T4)")
+
+    # Command: exclude
+    exclude_parser = subparsers.add_parser("exclude", help="Exclude a directory from scanning")
+    exclude_parser.add_argument("path", help="Path to exclude (e.g. node_modules, dist)")
+
+    # Command: autofix
+    autofix_parser = subparsers.add_parser("autofix", help="Batch-apply all safe T1 quick fixes")
+    autofix_parser.add_argument("--dry-run", action="store_true", help="Preview fixes without applying")
+
+    # Command: rescan
+    rescan_parser = subparsers.add_parser("rescan", help="Clear queue and re-scan the project fresh")
+    rescan_parser.add_argument("--path", default=".", help="Directory to rescan")
+
+    # Command: loop
+    loop_parser = subparsers.add_parser("loop", help="Instruct the AI agent to enter an autonomous fix loop")
+    loop_parser.add_argument("--target", type=int, default=95, help="Target design score to reach (default 95)")
+    loop_parser.add_argument("--orchestrator", action="store_true", help="Use sub-agent orchestrator mode (one agent per stage)")
+
+    # Command: subagent
+    sub_parser = subparsers.add_parser("subagent", help="Manage sub-agent sessions and generate stage prompts")
+    sub_parser.add_argument("--stage-prompt", type=str, help="Generate prompt for a stage (observe/diagnose/prioritize/fix/verify)")
+    sub_parser.add_argument("--parallel", type=int, default=1, help="Number of parallel sub-agents to shard the workload across")
+    sub_parser.add_argument("--list", action="store_true", help="List all sub-agent sessions")
+    sub_parser.add_argument("--show", type=str, help="Show details of a session by ID")
+    sub_parser.add_argument("--record", type=str, help="Mark a session as completed")
+    sub_parser.add_argument("--note", type=str, default="", help="Note for --record")
+
+    # Command: history
+    history_parser = subparsers.add_parser("history", help="View run history and score progression")
+    history_parser.add_argument("--full", action="store_true", help="Show full run details")
+
+    # Command: viz
+    viz_parser = subparsers.add_parser("viz", help="Generate an HTML treemap heatmap of codebase issues")
+    viz_parser.add_argument("--path", default=".", help="Directory to visualize")
+    viz_parser.set_defaults(viz_cmd="viz")
+
+    # Command: tree
+    tree_parser = subparsers.add_parser("tree", help="Print a terminal tree of codebase issues")
+    tree_parser.add_argument("--path", default=".", help="Directory to visualize")
+    tree_parser.add_argument("--depth", type=int, default=3, help="Max depth of the tree")
+    tree_parser.set_defaults(viz_cmd="tree")
+
+    # Command: zone
+    zone_parser = subparsers.add_parser("zone", help="Show, set, or clear file classifications (production, test, vendor, etc.)")
+    zone_parser.add_argument("zone_action", nargs="?", choices=["show", "set", "clear"], default="show", help="Action to perform")
+    zone_parser.add_argument("zone_path", nargs="?", help="File path to override")
+    zone_parser.add_argument("zone_value", nargs="?", help="Zone value (production, test, config, generated, script, vendor)")
+
+    # Command: suppress
+    suppress_parser = subparsers.add_parser("suppress", help="Permanently suppress issues matching a pattern")
+    suppress_parser.add_argument("pattern", nargs="?", help="Pattern to suppress (e.g., *vendor/* or 'Uses Inter font')")
+    suppress_parser.add_argument("--remove", action="store_true", help="Remove an existing suppression pattern")
+
+    # Command: memory
+    memory_parser = subparsers.add_parser("memory", help="Read or write to the persistent agent memory bank")
+    memory_parser.add_argument("memory_action", nargs="?", choices=["show", "pattern", "note", "clear"], default="show", help="Action to perform")
+    memory_parser.add_argument("value", nargs="?", help="The pattern or note string to save")
+
+    # Command: detect
+    detect_parser = subparsers.add_parser("detect", help="Auto-detect project tooling (linters, formatters, tsc, backend, db)")
+    detect_parser.add_argument("--path", default=".", help="Project root to scan")
+
+    # Command: check (master: tsc → lint → format)
+    check_parser = subparsers.add_parser("check", help="Run tsc → lint → format in sequence")
+    check_parser.add_argument("--fix", action="store_true", help="Auto-fix lint and format issues")
+
+    # Command: tsc
+    tsc_parser = subparsers.add_parser("tsc", help="Run TypeScript compiler and queue errors")
+    tsc_parser.add_argument("--fix", action="store_true", help="(reserved for future use)")
+
+    # Command: lint
+    lint_parser = subparsers.add_parser("lint", help="Run detected linter and queue errors")
+    lint_parser.add_argument("--fix", action="store_true", help="Auto-fix lint errors")
+
+    # Command: format
+    format_parser = subparsers.add_parser("format", help="Run detected formatter")
+    format_parser.add_argument("--fix", action="store_true", help="Auto-fix formatting")
+
+    # Dynamic Slash Commands (e.g., /audit, /polish) from the commands/ directory
+    cmd_dir = _get_commands_dir()
+    if cmd_dir:
+        for md_file in cmd_dir.glob("*.md"):
+            skill_name = md_file.stem
+            if skill_name not in ["scan", "setup", "fix"]:
+                skill_parser = subparsers.add_parser(skill_name, help=f"Execute the '{skill_name}' UX design skill")
+                skill_parser.add_argument("target", nargs="?", default=".", help="Target file, directory, or component pattern")
+
+    return parser.parse_args(args_list)
+
+def main():
+    args = parse_args()
+    if not args.command:
+        # Just show help
+        parse_args(["--help"])
+        return
+
+    # Dispatch to the specific command module
+    try:
+        # Check dynamic skills
+        cmd_dir = _get_commands_dir()
+        dynamic_skills = []
+        if cmd_dir:
+            dynamic_skills = [f.stem for f in cmd_dir.glob("*.md") if f.stem not in ["scan", "setup", "fix"]]
+            
+        if args.command in dynamic_skills:
+            command_name = "skill_cmd"
+        else:
+            command_name = args.command.replace("-", "_")
+            
+        # Avoid collision with builtins and top-level modules
+        name_map = {
+            "format": "format_cmd", 
+            "subagent": "subagent_cmd", 
+            "history": "history_cmd",
+            "memory": "memory_cmd",
+            "tree": "viz" # route 'tree' to 'viz.py'
+        }
+        command_name = name_map.get(command_name, command_name)
+        module = import_module(f"uidetox.commands.{command_name}")
+        
+        if hasattr(module, "run"):
+            # Pass args to the command runner
+            module.run(args)
+        else:
+            print(f"Error: Command module for '{args.command}' lacks a run() function.", file=sys.stderr)
+            sys.exit(1)
+            
+    except KeyboardInterrupt:
+        print("\n\nInterrupted. Run 'uidetox status' to see where you left off.")
+        sys.exit(130)
+    except ImportError as e:
+        print(f"Error: Command '{args.command}' is not implemented yet. ({e})", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"An error occurred: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

uidetox/commands/__init__.py

@@ -0,0 +1 @@
+"""Commands package initialization."""

uidetox/commands/add_issue.py

@@ -0,0 +1,37 @@
+"""Add issue command."""
+
+import argparse
+import fnmatch
+import uuid
+from uidetox.state import add_issue, load_config
+
+def _is_suppressed(file_path: str, description: str, patterns: list[str]) -> bool:
+    """Check if this issue matches any active suppress pattern."""
+    for pattern in patterns:
+        if fnmatch.fnmatch(file_path, pattern) or fnmatch.fnmatch(file_path, f"*{pattern}*"):
+            return True
+        if fnmatch.fnmatch(description, pattern) or fnmatch.fnmatch(description, f"*{pattern}*"):
+            return True
+        if pattern.lower() in file_path.lower() or pattern.lower() in description.lower():
+            return True
+    return False
+
+def run(args: argparse.Namespace):
+    config = load_config()
+    ignore_patterns = config.get("ignore_patterns", [])
+    
+    if ignore_patterns and _is_suppressed(args.file, args.issue, ignore_patterns):
+        print(f"Suppressed: [{args.tier}] {args.issue} in {args.file} (matches active ignore pattern)")
+        return
+    
+    issue_id = f"SCAN-{str(uuid.uuid4())[:6].upper()}"
+    new_issue = {
+        "id": issue_id,
+        "file": args.file,
+        "tier": args.tier,
+        "issue": args.issue,
+        "command": args.fix_command
+    }
+    add_issue(new_issue)
+    print(f"Added issue {issue_id}: [{args.tier}] {args.issue} in {args.file}")
+

uidetox/commands/autofix.py

@@ -0,0 +1,42 @@
+"""Autofix command: automatically apply safe T1 fixes."""
+
+import argparse
+from uidetox.state import load_state, save_state, load_config
+
+def run(args: argparse.Namespace):
+    state = load_state()
+    issues = state.get("issues", [])
+    
+    t1_issues = [i for i in issues if i.get("tier") == "T1"]
+    
+    if not t1_issues:
+        print("No T1 (quick fix) issues found. Nothing to autofix.")
+        return
+    
+    dry_run = getattr(args, "dry_run", False)
+    
+    print("==============================")
+    print(" UIdetox Autofix")
+    print("==============================")
+    print(f"Found {len(t1_issues)} T1 issue(s) eligible for autofix:\n")
+    
+    for issue in t1_issues:
+        print(f"  [{issue['id']}] {issue['file']}: {issue['issue']}")
+        print(f"    → Fix: {issue.get('command', 'manual')}")
+    
+    if dry_run:
+        print(f"\n[DRY RUN] No changes applied. Remove --dry-run to apply.")
+        return
+    
+    config = load_config()
+    auto_commit = config.get("auto_commit", False)
+
+    print(f"\n[AGENT INSTRUCTION]")
+    print(f"Apply all {len(t1_issues)} T1 fixes listed above. For each:")
+    print(f"  1. Open the file")
+    print(f"  2. Apply the fix described above")
+    print(f"  3. Run `uidetox resolve <issue_id> --note \"what you changed\"` when done")
+    if auto_commit:
+        print(f"\n  📦 AUTO-COMMIT is ON — each `resolve` will atomically commit the fix to git.")
+    print(f"\nThese are safe, mechanical changes (font swaps, color replacements, spacing).")
+    print(f"Apply them all before moving to T2+ issues.")

uidetox/commands/check.py

@@ -0,0 +1,104 @@
+"""Check command: runs tsc → lint → format in sequence."""
+
+import argparse
+import subprocess
+from uidetox.tooling import detect_all
+from uidetox.state import load_config, save_config
+from uidetox.commands import tsc as tsc_cmd
+from uidetox.commands import lint as lint_cmd
+from uidetox.commands import format_cmd
+
+
+def run(args: argparse.Namespace):
+    # First, ensure tooling is detected
+    config = load_config()
+    if not config.get("tooling"):
+        profile = detect_all()
+        config["tooling"] = profile.to_dict()
+        save_config(config)
+        print("Auto-detected project tooling.\n")
+
+    tooling = config.get("tooling", {})
+
+    print("╔══════════════════════════════╗")
+    print("║   UIdetox Mechanical Check   ║")
+    print("╚══════════════════════════════╝")
+    print()
+
+    fix = getattr(args, "fix", False)
+    steps_run = 0
+
+    if fix and (tooling.get("linter") or tooling.get("formatter")):
+        print("━━━ Phase 1: Iterative Auto-Fix ━━━")
+        for iteration in range(1, 4):
+            print(f"Iteration {iteration}...")
+            changed = False
+            
+            if tooling.get("formatter"):
+                cmd = tooling["formatter"].get("fix_cmd")
+                if cmd:
+                    try:
+                        res = subprocess.run(cmd.split(), capture_output=True, text=True, cwd=".")
+                        # If formatter changed files, it usually outputs file names or has exit code
+                        if res.returncode != 0 or "fixed" in res.stdout.lower() or "formatted" in res.stdout.lower():
+                            changed = True
+                    except FileNotFoundError:
+                        print(f"Warning: Formatter command not found ({cmd})")
+
+            if tooling.get("linter"):
+                cmd = tooling["linter"].get("fix_cmd")
+                if cmd:
+                    try:
+                        res = subprocess.run(cmd.split(), capture_output=True, text=True, cwd=".")
+                        # If linter fixed files, it might still have exit code 1 if some remain
+                        # We assume it changed things if the output mentions fixes, or just run max 3 times anyway
+                        if "fixed" in res.stdout.lower() or "fixed" in res.stderr.lower():
+                            changed = True
+                    except FileNotFoundError:
+                        print(f"Warning: Linter command not found ({cmd})")
+            
+            if not changed:
+                print("Code is clean or no more auto-fixes available.\n")
+                break
+        print("Auto-fix phase complete.\n")
+
+    print("━━━ Phase 2: Diagnostic Checks ━━━")
+
+    # Step 1: TypeScript
+    if tooling.get("typescript"):
+        print("  Running TypeScript check...")
+        tsc_args = argparse.Namespace(fix=False)
+        tsc_cmd.run(tsc_args)
+        steps_run += 1
+        print()
+    else:
+        print("  TypeScript: skipped (not detected)\n")
+
+    # Step 2: Lint
+    if tooling.get("linter"):
+        print("  Running Linter check...")
+        lint_args = argparse.Namespace(fix=False)
+        lint_cmd.run(lint_args)
+        steps_run += 1
+        print()
+    else:
+        print("  Linter: skipped (not detected)\n")
+
+    # Step 3: Format
+    if tooling.get("formatter"):
+        print("  Running Formatter check...")
+        fmt_args = argparse.Namespace(fix=False)
+        format_cmd.run(fmt_args)
+        steps_run += 1
+        print()
+    else:
+        print("  Formatter: skipped (not detected)\n")
+
+    if steps_run == 0:
+        print("No tooling detected. Run 'uidetox detect' to configure tooling.")
+        return
+
+    print("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    print(f"Ran {steps_run} mechanical check(s).")
+    print("Run 'uidetox status' to see the updated health score.")
+    print("Run 'uidetox next' to start fixing any queued issues.")