@maccesar/titools 2.0.0

package/skills/alloy-expert/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: alloy-expert
+description: "Titanium Alloy architecture and implementation expert. Use when designing, reviewing, analyzing, or examining Alloy project structure, creating controllers/views/services, choosing models vs collections, implementing communication patterns, handling memory cleanup, testing, auditing code, or migrating legacy apps. Detects Alloy vs Classic projects automatically."
+argument-hint: "[architecture-topic]"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
+---
+
+# Titanium Alloy Expert
+
+Complete architectural and implementation guidance for building scalable, maintainable Titanium Alloy applications with PurgeTSS styling.
+
+## Project Detection
+
+:::info AUTO-DETECTS ALLOY VS CLASSIC PROJECTS
+This skill automatically detects project type when invoked and provides appropriate guidance.
+
+**Detection occurs automatically** - no manual command needed.
+
+**Alloy project indicators:**
+- `app/` folder (MVC structure)
+- `app/views/`, `app/controllers/` folders
+- `alloy.jmk` or `config.json` files
+
+**Classic project indicators:**
+- `Resources/` folder with `app.js` at root
+- No `app/` folder structure
+
+**Behavior based on detection:**
+- **Alloy detected** → Provides Alloy-specific architecture patterns, MVC folder structure, Backbone.js patterns
+- **Classic detected** → Indicates incompatibility, does not suggest Alloy-specific patterns, recommends migration or Classic resources
+- **Unknown** → Asks user to clarify project type
+:::
+
+## Table of Contents
+
+- [Titanium Alloy Expert](#titanium-alloy-expert)
+  - [Project Detection](#project-detection)
+  - [Table of Contents](#table-of-contents)
+  - [Workflow](#workflow)
+  - [Quick Start Example](#quick-start-example)
+  - [Code Standards (Low Freedom)](#code-standards-low-freedom)
+  - [PurgeTSS Rules (Low Freedom)](#purgetss-rules-low-freedom)
+  - [Quick Decision Matrix](#quick-decision-matrix)
+  - [Reference Guides (Progressive Disclosure)](#reference-guides-progressive-disclosure)
+    - [Architecture](#architecture)
+    - [Implementation](#implementation)
+    - [Quality \& Reliability](#quality--reliability)
+    - [Performance \& Security](#performance--security)
+    - [Migration](#migration)
+  - [Specialized Titanium Skills](#specialized-titanium-skills)
+  - [Guiding Principles](#guiding-principles)
+  - [Response Format](#response-format)
+
+---
+
+## Workflow
+
+1. **Architecture**: Define structure (`lib/api`, `lib/services`, `lib/helpers`)
+2. **Data Strategy**: Choose Models (SQLite) or Collections (API)
+3. **Contracts**: Define I/O specs for cross-layer communication
+4. **Implementation**: Write XML views + ES6+ controllers
+5. **Quality**: Testing, error handling, logging, performance
+6. **Cleanup**: Implement `cleanup()` pattern for memory management
+
+## Quick Start Example
+
+Minimal example following all conventions:
+
+**View (views/user/card.xml)**
+```xml
+<Alloy>
+  <View class="m-2 rounded-xl bg-white shadow-md">
+    <View class="horizontal m-3 w-screen">
+      <Label class="fa-solid fa-user text-2xl text-blue-500" />
+      <Label id="name" class="ml-3 text-lg font-bold" />
+    </View>
+    <Button class="mx-3 mb-3 h-10 w-screen rounded-md bg-blue-600 text-white"
+      title="L('view_profile')"
+      onClick="onViewProfile"
+    />
+  </View>
+</Alloy>
+```
+
+**Controller (controllers/user/card.js)**
+```javascript
+const { Navigation } = require('lib/services/navigation')
+
+function init() {
+  const user = $.args.user
+  $.name.text = user.name
+}
+
+function onViewProfile() {
+  Navigation.open('user/profile', { userId: $.args.user.id })
+}
+
+function cleanup() {
+  $.destroy()
+}
+
+$.cleanup = cleanup
+```
+
+**Service (lib/services/navigation.js)**
+```javascript
+exports.Navigation = {
+  open(route, params = {}) {
+    const controller = Alloy.createController(route, params)
+    const view = controller.getView()
+
+    view.addEventListener('close', function() {
+      if (controller.cleanup) controller.cleanup()
+    })
+
+    view.open()
+    return controller
+  }
+}
+```
+
+## Code Standards (Low Freedom)
+
+- **NO SEMICOLONS**: Let ASI handle it
+- **MODERN SYNTAX**: `const/let`, destructuring, template literals
+- **applyProperties()**: Batch UI updates to minimize bridge crossings
+- **MEMORY CLEANUP**: Every controller with global listeners MUST have `$.cleanup = cleanup`
+- **ERROR HANDLING**: Use AppError classes, log with context, never swallow errors
+- **TESTABLE**: Inject dependencies, avoid hard coupling
+
+## PurgeTSS Rules (Low Freedom)
+
+:::danger CRITICAL: Platform-Specific Properties Require Modifiers
+Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties WITHOUT platform modifiers causes cross-platform compilation failures.
+
+**Example of the damage:**
+```tss
+// ❌ WRONG - Adds Ti.UI.iOS to Android project
+"#mainWindow": {
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
+}
+```
+
+**CORRECT - Always use platform modifiers:**
+```tss
+// ✅ CORRECT - Only adds to iOS
+"#mainWindow[platform=ios]": {
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+}
+```
+
+**Properties that ALWAYS require platform modifiers:**
+- iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
+- Android: `actionBar` configuration, any `Ti.UI.Android.*` constant
+
+**Available modifiers:** `[platform=ios]`, `[platform=android]`, `[formFactor=handheld]`, `[formFactor=tablet]`, `[if=Alloy.Globals.customVar]`
+
+**For more platform-specific patterns, see** [Platform Modifiers (purgetss)](skills/purgetss/references/platform-modifiers.md) or [Platform UI guides (ti-ui)](skills/ti-ui/references/platform-ui-ios.md).
+:::
+
+| WRONG                          | CORRECT             | Why                           |
+| ------------------------------ | ------------------- | ----------------------------- |
+| `flex-row`                     | `horizontal`        | Flexbox not supported         |
+| `flex-col`                     | `vertical`          | Flexbox not supported         |
+| `p-4` on View                  | `m-4` on children   | No padding on containers      |
+| `justify-*`                    | margins/positioning | Flexbox not supported         |
+| `items-center` (for centering) | layout + sizing     | Different meaning in Titanium |
+| `rounded-full` (for circle)    | `rounded-full-12`   | Need size suffix (12×4=48px)  |
+| `border-[1px]`                 | `border-(1)`        | Parentheses, not brackets     |
+
+**Note on `w-full` vs `w-screen`:**
+- `w-full` → `width: '100%'` (100% of parent container) - exists and valid
+- `w-screen` → `width: Ti.UI.FILL` (fills all available space) - use for full-width elements
+
+## Quick Decision Matrix
+
+| Question                           | Answer                                                         |
+| ---------------------------------- | -------------------------------------------------------------- |
+| How to create a new Alloy project? | **`ti create -t app --alloy`** (not `--classic` + `alloy new`) |
+| Where does API call go?            | `lib/api/`                                                     |
+| Where does business logic go?      | `lib/services/`                                                |
+| Where do I store auth tokens?      | Keychain (iOS) / KeyStore (Android) via service                |
+| Models or Collections?             | Collections for API data, Models for SQLite persistence        |
+| Ti.App.fireEvent or EventBus?      | **Always EventBus** (Backbone.Events)                          |
+| Direct navigation or service?      | **Always Navigation service** (auto cleanup)                   |
+| Manual TSS or PurgeTSS?            | **Always PurgeTSS utility classes**                            |
+| Controller 100+ lines?             | Extract logic to services                                      |
+
+## Reference Guides (Progressive Disclosure)
+
+### Architecture
+- **[Structure & Organization](references/alloy-structure.md)**: Models vs Collections, folder maps, styling strategies, automatic cleanup
+- **[ControllerAutoCleanup.js](assets/ControllerAutoCleanup.js)**: Drop-in utility for automatic controller cleanup (prevents memory leaks)
+- **[Architectural Patterns](references/patterns.md)**: Repository, Service Layer, Event Bus, Factory, Singleton
+- **[Contracts & Communication](references/contracts.md)**: Layer interaction examples and JSDoc specs
+- **[Anti-Patterns](references/anti-patterns.md)**: Fat controllers, flexbox classes, memory leaks, direct API calls
+
+### Implementation
+- **[Code Conventions](references/code-conventions.md)**: ES6 features, PurgeTSS usage, accessibility
+- **[Controller Patterns](references/controller-patterns.md)**: Templates, animation, dynamic styling
+- **[Examples](references/examples.md)**: API clients, SQL models, full screen examples
+
+### Quality & Reliability
+- **[Testing](references/testing.md)**: Unit testing, mocking patterns, controller testing, test helpers
+- **[Error Handling & Logging](references/error-handling.md)**: AppError classes, Logger service, validation
+
+### Performance & Security
+- **[Performance Patterns](references/performance-patterns.md)**: ListView, bridge optimization, memory management, lazy loading
+- **[Security Patterns](references/security-patterns.md)**: Token storage, certificate pinning, encryption, OWASP
+- **[State Management](references/state-management.md)**: Centralized store, reactive patterns, synchronization
+
+### Migration
+- **[Migration Patterns](references/migration-patterns.md)**: Step-by-step guide for modernizing legacy apps
+
+## Specialized Titanium Skills
+
+For specific feature implementations, defer to these specialized skills:
+
+| Task                                                  | Use This Skill |
+| ----------------------------------------------------- | -------------- |
+| PurgeTSS setup, advanced styling, animations          | `purgetss`     |
+| Location, Maps, Push Notifications, Media APIs        | `ti-howtos`    |
+| UI layouts, ListViews, gestures, platform-specific UI | `ti-ui`        |
+| Alloy CLI, configuration files, debugging             | `alloy-howtos` |
+| Alloy MVC complete reference                          | `alloy-guides` |
+| Hyperloop, native modules, app distribution           | `ti-guides`    |
+
+## Guiding Principles
+
+1. **Thin Controllers**: Max 100 lines. Delegate to services.
+2. **Single Source of Truth**: One state store, not scattered Properties.
+3. **Always Cleanup**: Every listener added = listener removed in `cleanup()`.
+4. **Never Block UI**: All API/DB calls are async with loading states.
+5. **Fail Gracefully**: Centralized error handling with user-friendly messages.
+
+## Response Format
+
+**For Architecture Questions:**
+1. Decision: What should be done
+2. Justification: Technical rationale
+3. Structure: File and folder placement
+4. Contract: Clear I/O specification
+
+**For Implementation Tasks:**
+1. Code First: Show implementation immediately
+2. Minimal Comments: Explain only the "Why" for complex logic
+3. No Explanations: Deliver exactly what was asked concisely

package/skills/alloy-expert/assets/ControllerAutoCleanup.js

@@ -0,0 +1,182 @@
+/**
+ * ControllerAutoCleanup - Automatic Controller Cleanup for Alloy
+ *
+ * Monkey-patches Alloy.createController to automatically cleanup
+ * controllers when their views are closed, preventing memory leaks.
+ *
+ * INSTALLATION:
+ * 1. Copy this file to your app: app/lib/ControllerAutoCleanup.js
+ * 2. Add as first line in alloy.js: require('ControllerAutoCleanup')
+ *
+ * No other code changes needed - cleanup happens automatically.
+ *
+ * @see https://github.com/jasonkneen/AlloyXL original inspiration
+ */
+
+'use strict'
+
+// Logger (optional - remove if not using)
+let log = null
+try {
+  log = require('Logger')?.create('CONTROLLER_CLEANUP')
+} catch (e) {
+  // Fallback simple logger
+  log = {
+    debug: (msg, data) => Ti.API.debug(`[ControllerCleanup] ${msg}`, data),
+    info: (msg, data) => Ti.API.info(`[ControllerCleanup] ${msg}`, data),
+    warn: (msg, data) => Ti.API.warn(`[ControllerCleanup] ${msg}`, data),
+    error: (msg, data) => Ti.API.error(`[ControllerCleanup] ${msg}`, data)
+  }
+}
+
+// Store original Alloy.createController
+const originalCreateController = Alloy.createController
+
+/**
+ * Recursively cleanup a controller and all its child views
+ * @param {Object} controller - Alloy controller to cleanup
+ */
+function cleanupController(controller) {
+  if (!controller) return
+
+  // Cleanup child views first (recursive)
+  if (controller.__views) {
+    Object.values(controller.__views).forEach((childView) => {
+      if (childView && typeof childView === 'object') {
+        cleanupController(childView)
+      }
+    })
+  }
+
+  // Only cleanup actual Alloy controllers (not plain views)
+  if (controller.__iamalloy) {
+    // Remove all Backbone event listeners
+    if (typeof controller.off === 'function') {
+      controller.off()
+    }
+
+    // Call Alloy's destroy method
+    if (typeof controller.destroy === 'function') {
+      controller.destroy()
+    }
+
+    log?.debug('Controller cleaned up', { id: controller.id })
+  }
+
+  // Clear reference
+  controller = null
+}
+
+/**
+ * Enhanced Alloy.createController with automatic cleanup
+ * @param {string} name - Controller name/path
+ * @param {Object} args - Arguments to pass to controller
+ * @returns {Object} Alloy controller
+ */
+function createController(name, args = {}) {
+  try {
+    const controller = originalCreateController(name, args)
+
+    // Only process controllers with views
+    if (!controller.__views || Object.keys(controller.__views).length === 0) {
+      return controller
+    }
+
+    const view = controller.getView()
+    const controllerName = name.split('/').pop() || name
+    const viewId = view?.id
+
+    // Track controllers globally (optional, for debugging)
+    Alloy.Controllers = Alloy.Controllers || {}
+
+    // Warn about controller name conflicts
+    if (Alloy.Controllers[controllerName] && !viewId) {
+      log?.warn('Controller name conflict - consider using unique IDs', {
+        controller: controllerName,
+        path: controller.__controllerPath
+      })
+    }
+
+    // Use view ID as key if available, otherwise controller name
+    const registryKey = viewId || controllerName
+    Alloy.Controllers[registryKey] = controller
+
+    /**
+     * Add `once()` helper - listen to event one time only
+     * @param {string} eventName - Event name
+     * @param {Function} callback - Callback function
+     * @returns {Object} controller for chaining
+     */
+    controller.once = function (eventName, callback) {
+      const wrapper = (...args) => {
+        controller.off(eventName, wrapper)
+        callback(...args)
+      }
+      controller.on(eventName, wrapper)
+      return controller
+    }
+
+    // Only add auto-cleanup to views with addEventListener
+    if (view && typeof view.addEventListener === 'function') {
+      // Window-like views with open() method
+      if (typeof view.open === 'function') {
+        view.addEventListener('open', function onOpen(e) {
+          view.removeEventListener('open', onOpen)
+          controller.trigger('open', e)
+          log?.debug('Controller opened', { name: controllerName })
+        })
+
+        view.addEventListener('close', function onClose() {
+          view.removeEventListener('close', onClose)
+          view = null
+
+          cleanupController(controller)
+          delete Alloy.Controllers[registryKey]
+
+          log?.debug('Controller cleaned up', { name: controllerName })
+        })
+
+        view.addEventListener('postlayout', function onPostLayout(e) {
+          view.removeEventListener('postlayout', onPostLayout)
+          controller.trigger('postlayout', e)
+          log?.debug('Controller layout finished', { name: controllerName })
+        })
+      } else {
+        // View-like views without open() (Widget, etc.)
+        view.addEventListener('postlayout', function onPostLayout(e) {
+          view.removeEventListener('postlayout', onPostLayout)
+          controller.trigger('postlayout', e)
+          log?.debug('View layout finished', { name: controllerName })
+        })
+      }
+    }
+
+    return controller
+
+  } catch (error) {
+    log?.error('Error creating controller', {
+      name,
+      error: error.message,
+      stack: error.stack
+    })
+    throw error
+  }
+}
+
+// Replace Alloy.createController with enhanced version
+Alloy.createController = createController
+
+log?.info('ControllerAutoCleanup loaded - automatic cleanup enabled')
+
+// Export createController for direct use if needed
+exports.createController = createController
+
+/**
+ * USAGE:
+ *
+ * // alloy.js - Load as first line
+ * require('ControllerAutoCleanup')
+ *
+ * // All controllers now auto-cleanup on close
+ * Alloy.createController('profile').getView().open()
+ */