@maccesar/titools 2.0.7 → 2.2.0

package/skills/{alloy-expert → ti-expert}/SKILL.md

@@ -1,13 +1,13 @@
 ---
-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."
+name: ti-expert
+description: "Titanium SDK architecture and implementation expert. Use when designing, reviewing, analyzing, or examining Titanium project structure (Alloy or Classic), creating controllers/views/services, choosing models vs collections, implementing communication patterns, handling memory cleanup, testing, auditing code, or migrating legacy apps. Automatically identifies project type."
 argument-hint: "[architecture-topic]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 ---
 
-# Titanium Alloy Expert
+# Titanium Expert
 
-Complete architectural and implementation guidance for building scalable, maintainable Titanium Alloy applications with PurgeTSS styling.
+Complete architectural and implementation guidance for building scalable, maintainable Titanium SDK applications (Alloy & Classic).
 
 ## Project Detection
 
@@ -31,28 +31,6 @@ This skill automatically detects project type when invoked and provides appropri
 - **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`)
@@ -69,12 +47,12 @@ 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 id="cardContainer">
+    <View id="headerRow">
+      <ImageView id="userIcon" image="/images/user.png" />
+      <Label id="name" />
     </View>
-    <Button class="mx-3 mb-3 h-10 w-screen rounded-md bg-blue-600 text-white"
+    <Button id="viewProfileBtn"
       title="L('view_profile')"
       onClick="onViewProfile"
     />
@@ -82,9 +60,18 @@ Minimal example following all conventions:
 </Alloy>
 ```
 
+**Styles (styles/user/card.tss)**
+```tss
+"#cardContainer": { left: 8, right: 8, top: 8, height: Ti.UI.SIZE, borderRadius: 12, backgroundColor: '#fff' }
+"#headerRow": { layout: 'horizontal', left: 12, right: 12, top: 12, height: Ti.UI.SIZE, width: Ti.UI.FILL }
+"#userIcon": { width: 32, height: 32 }
+"#name": { left: 12, font: { fontSize: 18, fontWeight: 'bold' } }
+"#viewProfileBtn": { left: 12, right: 12, bottom: 12, height: 40, width: Ti.UI.FILL, borderRadius: 6, backgroundColor: '#2563eb', color: '#fff' }
+```
+
 **Controller (controllers/user/card.js)**
 ```javascript
-const { Navigation } = require('lib/services/navigation')
+const { Navigation } = require('services/navigation')
 
 function init() {
   const user = $.args.user
@@ -128,7 +115,7 @@ exports.Navigation = {
 - **ERROR HANDLING**: Use AppError classes, log with context, never swallow errors
 - **TESTABLE**: Inject dependencies, avoid hard coupling
 
-## PurgeTSS Rules (Low Freedom)
+## Titanium Style Sheets 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.
@@ -155,58 +142,63 @@ Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties WITHOUT platform modifiers c
 
 **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).
+**For more platform-specific patterns, see the `ti-ui` skill.**
 :::
 
-| 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     |
+**Titanium layout system:**
+- Three layout modes: `layout: 'horizontal'`, `layout: 'vertical'`, and composite (default — no `layout` needed)
+- No padding on container Views — use margins on children instead
+- `width: Ti.UI.FILL` fills available space (preferred), `width: '100%'` = 100% of parent
+- `height: Ti.UI.SIZE` wraps content, `height: Ti.UI.FILL` fills available space
+
+## Alloy Builtins Quick Reference
+
+Key builtins: `OS_IOS`/`OS_ANDROID` (compile-time), `Alloy.CFG` (config.json), `Alloy.Globals` (shared state), `$.args` (controller params), `$.destroy()` (cleanup bindings), `platform="ios"` / `formFactor="tablet"` (XML conditionals).
 
-**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
+For the complete reference with examples, see **[Alloy Builtins & Globals](references/alloy-builtins.md)**.
 
 ## Quick Decision Matrix
 
 | Question                           | Answer                                                         |
 | ---------------------------------- | -------------------------------------------------------------- |
 | How to create a new Alloy project? | **`ti create -t app --alloy`** (not `--classic` + `alloy new`) |
+| Fastest way to build?              | **`tn <recipe>`** (using TiNy CLI wrapper)                     |
 | 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**                            |
+| Inline styles or TSS files?        | **Always TSS files** (per-controller + `app.tss` for global)   |
 | 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
+- **[CLI Expert & TiNy](references/cli-expert.md)**: Advanced build workflows, LiveView, and TiNy (`tn`) recipes
+- **[Structure & Organization](references/alloy-structure.md)**: Models vs Collections, folder maps, widget patterns, automatic cleanup
+- **[Alloy Builtins & Globals](references/alloy-builtins.md)**: OS_IOS/OS_ANDROID, Alloy.CFG, Alloy.Globals, $.args, compiler directives
 - **[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
+- **[Anti-Patterns](references/anti-patterns.md)**: Fat controllers, memory leaks, inline styling, direct API calls
 
 ### Implementation
-- **[Code Conventions](references/code-conventions.md)**: ES6 features, PurgeTSS usage, accessibility
+- **[Code Conventions](references/code-conventions.md)**: ES6 features, TSS design system, accessibility
+- **[Theming & Dark Mode](references/theming.md)**: Theme system, Alloy.Globals palette, runtime switching, design tokens
 - **[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
+- **[Unit & Integration Testing](references/testing-unit.md)**: Unit testing, mocking patterns, controller testing, test helpers
+- **[E2E Testing & CI/CD](references/testing-e2e-ci.md)**: Appium, WebdriverIO, GitHub Actions, Fastlane
 - **[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
+- **[ListView & ScrollView Performance](references/performance-listview.md)**: ListView templates, data binding, image caching, ScrollView optimization
+- **[Performance Optimization](references/performance-optimization.md)**: Bridge crossings, memory management, animations, debounce/throttle, database
+- **[Security Fundamentals](references/security-fundamentals.md)**: Token storage, certificate pinning, encryption, HTTPS, OWASP
+- **[Device Security](references/security-device.md)**: Biometric auth, deep link validation, jailbreak/root detection
 - **[State Management](references/state-management.md)**: Centralized store, reactive patterns, synchronization
 
 ### Migration
@@ -218,7 +210,6 @@ 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` |

package/skills/ti-expert/references/alloy-builtins.md

@@ -0,0 +1,387 @@
+# Alloy Builtins & Globals
+
+## Compiler Directives
+
+Alloy provides compile-time constants that are replaced with `true`/`false` during build. Use them for platform-specific code without runtime cost.
+
+### OS_IOS / OS_ANDROID
+
+```javascript
+// These are compile-time constants — dead code is removed at build
+if (OS_IOS) {
+  $.window.applyProperties({
+    largeTitleEnabled: true,
+    largeTitleDisplayMode: Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_ALWAYS
+  })
+}
+
+if (OS_ANDROID) {
+  $.window.activity.onCreateOptionsMenu = (e) => {
+    const menu = e.menu
+    menu.add({ title: L('settings'), showAsAction: Ti.Android.SHOW_AS_ACTION_NEVER })
+  }
+}
+```
+
+:::warning These are NOT runtime checks
+`OS_IOS` and `OS_ANDROID` are replaced by the Alloy compiler with literal `true`/`false`. The opposite platform's code is completely removed from the build output. This is different from `Ti.Platform.osname === 'iphone'` which remains in the code.
+
+**Use for:** Platform-specific APIs, platform-specific UI configuration
+**Do NOT use for:** Logic that should be testable on both platforms
+:::
+
+### ENV_DEV / ENV_TEST / ENV_PRODUCTION
+
+```javascript
+if (ENV_DEV) {
+  Ti.API.info('Debug mode: API URL = ' + Alloy.CFG.apiUrl)
+}
+
+if (ENV_PRODUCTION) {
+  // Enable crash reporting
+  crashReporter.init()
+}
+```
+
+Set environment during build:
+```bash
+ti build -p ios -T simulator -D development
+ti build -p ios -T dist-appstore -D production
+```
+
+---
+
+## Alloy.Globals
+
+Shared state and utilities accessible from any controller or lib file. Set in `alloy.js`, available everywhere.
+
+### Common Patterns
+
+```javascript
+// alloy.js
+const Backbone = require('alloy/backbone')
+
+// --- Theme / Design Tokens ---
+Alloy.Globals.theme = {
+  primary: '#2563eb',
+  bg: '#ffffff',
+  text: '#111827'
+}
+
+// --- Device Info (cached once) ---
+Alloy.Globals.isTablet = Alloy.isTablet
+Alloy.Globals.screenWidth = Ti.Platform.displayCaps.platformWidth
+Alloy.Globals.screenHeight = Ti.Platform.displayCaps.platformHeight
+Alloy.Globals.density = Ti.Platform.displayCaps.dpi
+
+// --- App State Flags ---
+Alloy.Globals.isLoggedIn = false
+Alloy.Globals.currentUserId = null
+
+// --- Collections ---
+Alloy.Collections.products = new Backbone.Collection()
+Alloy.Collections.notifications = new Backbone.Collection()
+```
+
+### Access from Anywhere
+
+```javascript
+// In any controller
+const theme = Alloy.Globals.theme
+$.label.color = theme.primary
+
+// In TSS (evaluated at compile time for controller creation)
+"#header": {
+  backgroundColor: Alloy.Globals.theme.primary
+}
+
+// In XML with conditional binding
+// <View if="Alloy.Globals.isLoggedIn">
+```
+
+### Globals vs Services
+
+| Use `Alloy.Globals` for            | Use a Service for             |
+| ---------------------------------- | ----------------------------- |
+| Static config (theme, device info) | Business logic                |
+| Simple flags (isLoggedIn)          | Complex state with listeners  |
+| Values set once in `alloy.js`      | Values that change frequently |
+| Read-only data                     | Data with side effects        |
+
+---
+
+## Alloy.CFG
+
+Values from `app/config.json`, automatically resolved by environment and platform.
+
+```javascript
+// config.json
+{
+  "global": { "appName": "MyApp" },
+  "env:development": { "apiUrl": "https://dev.api.com", "debug": true },
+  "env:production": { "apiUrl": "https://api.com", "debug": false },
+  "os:ios": { "statusBarStyle": "light" },
+  "os:android": { "exitOnBack": true }
+}
+```
+
+```javascript
+// Access anywhere
+const url = Alloy.CFG.apiUrl       // Resolved by environment
+const debug = Alloy.CFG.debug      // true in dev, false in prod
+const appName = Alloy.CFG.appName  // From global
+```
+
+:::tip CFG is read-only
+`Alloy.CFG` values are set at build time and cannot be modified at runtime. For runtime configuration, use `Alloy.Globals` or `Ti.App.Properties`.
+:::
+
+---
+
+## Alloy.isTablet / Alloy.isHandheld
+
+Detect device form factor at runtime.
+
+```javascript
+if (Alloy.isTablet) {
+  // Show split-view layout
+  Navigation.open('tablet/splitView')
+} else {
+  // Show phone layout
+  Navigation.open('phone/list')
+}
+```
+
+### In TSS
+
+```tss
+"#sidebar[formFactor=tablet]": {
+  width: 320,
+  visible: true
+}
+
+"#sidebar[formFactor=handheld]": {
+  width: 0,
+  visible: false
+}
+```
+
+### In XML
+
+```xml
+<Alloy>
+  <!-- Only rendered on tablet -->
+  <View formFactor="tablet" id="sidebar">
+    <Require src="sidebar/menu" />
+  </View>
+
+  <!-- Only rendered on phone -->
+  <View formFactor="handheld" id="content">
+    <Require src="phone/content" />
+  </View>
+</Alloy>
+```
+
+---
+
+## $.args — Controller Arguments
+
+Every controller receives arguments via `$.args`. This is the standard way to pass data between controllers.
+
+### Basic Usage
+
+```javascript
+// Opening controller with args
+const ctrl = Alloy.createController('user/profile', {
+  userId: 123,
+  mode: 'edit',
+  onSave: handleSave
+})
+
+// Receiving in target controller
+// controllers/user/profile.js
+const { userId, mode, onSave } = $.args
+```
+
+### Common Patterns
+
+```javascript
+// Pattern 1: Default values with destructuring
+const {
+  userId,
+  mode = 'view',
+  showHeader = true,
+  onComplete = () => {}
+} = $.args
+
+// Pattern 2: Validation
+function init() {
+  if (!$.args.userId) {
+    Ti.API.error('user/profile requires userId')
+    $.getView().close()
+    return
+  }
+
+  loadUser($.args.userId)
+}
+
+// Pattern 3: Passing callbacks for communication
+// Parent controller
+const editor = Alloy.createController('editor', {
+  item: selectedItem,
+  onSave: (updatedItem) => {
+    refreshList()
+  }
+})
+
+// Child controller (editor.js)
+function save() {
+  const data = collectFormData()
+  $.args.onSave(data)
+  $.getView().close()
+}
+```
+
+### $.args in Widgets
+
+Widgets also receive args, but through the `<Widget>` tag attributes:
+
+```xml
+<Widget id="header" src="appHeader" title="L('home')" showBack="false" />
+```
+
+```javascript
+// widgets/appHeader/controllers/widget.js
+const title = $.args.title || ''
+const showBack = $.args.showBack !== 'false'  // XML passes strings
+```
+
+:::warning XML attributes are always strings
+When passing values through XML attributes, they arrive as strings in `$.args`. Numbers and booleans need to be parsed:
+```javascript
+const count = parseInt($.args.count, 10)    // "5" → 5
+const visible = $.args.visible !== 'false'   // "false" → false
+```
+For complex data, pass via `Alloy.createController()` in the parent controller instead.
+:::
+
+---
+
+## Alloy.createController / Alloy.createWidget
+
+### Controller Creation
+
+```javascript
+// Create and open
+const ctrl = Alloy.createController('user/profile', { userId: 123 })
+ctrl.getView().open()
+
+// Create and embed
+const card = Alloy.createController('components/userCard', { user: userData })
+$.container.add(card.getView())
+
+// Access controller methods
+ctrl.refresh()
+ctrl.setData(newData)
+```
+
+### Widget Creation
+
+```javascript
+// Create widget programmatically (alternative to XML <Widget>)
+const loader = Alloy.createWidget('loadingOverlay')
+$.window.add(loader.getView())
+
+loader.show(L('loading'))
+// ... later
+loader.hide()
+```
+
+---
+
+## Alloy.createModel / Alloy.createCollection
+
+```javascript
+// Create a model instance
+const user = Alloy.createModel('User', {
+  name: 'John',
+  email: 'john@example.com'
+})
+user.save()
+
+// Create a collection (fetches from adapter)
+const users = Alloy.createCollection('User')
+users.fetch()
+
+// Collection with query (SQL adapter)
+users.fetch({
+  query: 'SELECT * FROM users WHERE active = 1 ORDER BY name'
+})
+```
+
+---
+
+## Conditional Code in XML
+
+### Platform Conditional
+
+```xml
+<Alloy>
+  <Window>
+    <!-- iOS only -->
+    <NavigationWindow platform="ios" id="navWin">
+      <Require src="home" />
+    </NavigationWindow>
+
+    <!-- Android only -->
+    <Require platform="android" src="home" />
+  </Window>
+</Alloy>
+```
+
+### Form Factor Conditional
+
+```xml
+<Alloy>
+  <View formFactor="tablet" id="splitView">
+    <!-- Tablet layout -->
+  </View>
+  <View formFactor="handheld" id="phoneView">
+    <!-- Phone layout -->
+  </View>
+</Alloy>
+```
+
+### Custom Conditional (if attribute)
+
+```xml
+<!-- Only render if condition is true at creation time -->
+<View if="Alloy.Globals.isLoggedIn" id="userMenu">
+  <Label text="L('welcome_back')" />
+</View>
+
+<View if="Alloy.Globals.featureFlags.newDashboard" id="newDashboard">
+  <Require src="dashboard/v2" />
+</View>
+```
+
+:::warning `if` is evaluated once at controller creation
+The `if` attribute is checked when the controller is created. It does NOT react to later changes in the condition. For dynamic visibility, use the `visible` property in the controller.
+:::
+
+---
+
+## Quick Reference
+
+| Builtin             | Type              | Where Set         | Mutable |
+| ------------------- | ----------------- | ----------------- | ------- |
+| `OS_IOS`            | Compiler constant | Build time        | No      |
+| `OS_ANDROID`        | Compiler constant | Build time        | No      |
+| `ENV_DEV`           | Compiler constant | Build flag        | No      |
+| `ENV_PRODUCTION`    | Compiler constant | Build flag        | No      |
+| `Alloy.CFG`         | Object            | `config.json`     | No      |
+| `Alloy.Globals`     | Object            | `alloy.js`        | Yes     |
+| `Alloy.isTablet`    | Boolean           | Runtime           | No      |
+| `Alloy.isHandheld`  | Boolean           | Runtime           | No      |
+| `Alloy.Collections` | Object            | `alloy.js`        | Yes     |
+| `$.args`            | Object            | Parent controller | No      |