@maccesar/titools 2.0.0

package/skills/ti-guides/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ti-guides
+description: "Titanium SDK official fundamentals and configuration guide. Use when working with, reviewing, analyzing, or examining Titanium projects, Hyperloop native access, app distribution (App Store/Google Play), tiapp.xml configuration, CLI commands, memory management, bridge optimization, CommonJS modules, SQLite transactions, or coding standards. Applies to both Alloy and Classic projects."
+argument-hint: "[topic]"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
+---
+
+# Titanium SDK Guide Expert
+
+This skill ensures Titanium projects follow TiDev standards for stability, performance, and cross-platform reliability.
+
+## Project Detection
+
+:::info AUTO-DETECTS TITANIUM PROJECTS
+This skill automatically detects Titanium projects when invoked and provides SDK-specific guidance.
+
+**Detection occurs automatically** - no manual command needed.
+
+**Titanium project indicator:**
+- `tiapp.xml` file (definitive indicator)
+
+**Applicable to BOTH:**
+- **Alloy projects** (app/ folder)
+- **Classic projects** (Resources/ folder)
+
+**Behavior based on detection:**
+- **Titanium detected** → Provides official Titanium SDK guidance, memory management best practices, app distribution help
+- **Not detected** → Indicates this is for Titanium projects only
+:::
+
+## Table of Contents
+
+- [Titanium SDK Guide Expert](#titanium-sdk-guide-expert)
+  - [Project Detection](#project-detection)
+  - [Table of Contents](#table-of-contents)
+  - [Core Workflow](#core-workflow)
+  - [Procedural Rules (Low Freedom)](#procedural-rules-low-freedom)
+  - [Reference Guides (Progressive Disclosure)](#reference-guides-progressive-disclosure)
+  - [Related Skills](#related-skills)
+  - [Response Format](#response-format)
+
+---
+
+## Core Workflow
+
+1.  **Architecture Check**: Validate that the project follows a modular pattern (CommonJS or Alloy).
+2.  **Memory Review**: Ensure all global listeners are removed and heavy objects are nulled during cleanup.
+3.  **Bridge Optimization**: Identify and cache frequently accessed native properties to minimize bridge crossings.
+4.  **Native Integration**: Use Hyperloop for specialized native functionality, ensuring proper casting and thread management.
+5.  **Asset Management**: Optimize database operations with transactions and manage image memory footprints.
+
+## Procedural Rules (Low Freedom)
+
+-   **Memory Hygiene**: Always remove `Ti.App` and `Ti.Geolocation` listeners in the controller cleanup phase.
+-   **No Bridge Calls in Loops**: Never access `Ti.Platform` or `Ti.DisplayCaps` inside loops; store values in local variables.
+-   **Hyperloop Naming**: Concatenate selectors accurately (e.g., `addAttribute:value:range:` -> `addAttributeValueRange`).
+-   **DB Persistence**: Always close resultsets and database handles after every transaction block.
+
+## Reference Guides (Progressive Disclosure)
+
+-   **[Hello World](references/hello-world.md)**: Project creation, structure, and getting started with Alloy or Classic Titanium.
+-   **[JavaScript Primer](references/javascript-primer.md)**: JavaScript fundamentals, learning resources, best practices, and ES6+ features.
+-   **[Application Frameworks](references/application-frameworks.md)**: Alloy vs Classic Titanium, architectural patterns, and framework selection.
+-   **[Coding Best Practices](references/coding-best-practices.md)**: Memory leaks, bridge efficiency, event naming, security, and lazy loading.
+-   **[CommonJS Advanced](references/commonjs-advanced.md)**: Stateful modules, caching, ES6+ support, and antipatterns.
+-   **[Advanced Data & Images](references/advanced-data-and-images.md)**: SQLite transactions and image memory optimization.
+-   **[Hyperloop Native Access](references/hyperloop-native-access.md)**: Objective-C/Swift/Java syntax, casting, debugging, XIB/Storyboards.
+-   **[Style & Conventions](references/style-and-conventions.md)**: Naming standards and formatting rules.
+-   **[Reserved Words](references/reserved-words.md)**: ECMAScript, iOS, and Alloy reserved keywords to avoid.
+-   **[Alloy CLI Reference](references/alloy-cli-advanced.md)**: extract-i18n, code generation, and build hooks.
+-   **[Alloy Data Mastery](references/alloy-data-mastery.md)**: Sync adapters, data binding, and Backbone collections.
+-   **[Alloy Widgets & Themes](references/alloy-widgets-and-themes.md)**: Widget structure, styling priorities, and theming.
+-   **[Android Manifest](references/android-manifest.md)**: Custom AndroidManifest.xml, permissions, and manifest merge.
+-   **[App Distribution](references/app-distribution.md)**: Google Play (APK/AAB), App Store (IPA), certificates, provisioning, and deployment.
+-   **[tiapp.xml Configuration](references/tiapp-config.md)**: Complete reference for tiapp.xml and timodule.xml, including all elements, properties, and platform-specific settings.
+-   **[CLI Reference](references/cli-reference.md)**: Titanium CLI commands, options, tasks, configuration, and build processes.
+-   **[Resources](references/resources.md)**: Community support, modules, sample code, Slack, and learning materials.
+
+## Related Skills
+
+For tasks beyond SDK fundamentals, use these complementary skills:
+
+| Task                                     | Use This Skill |
+| ---------------------------------------- | -------------- |
+| Project architecture, services, patterns | `alloy-expert` |
+| Native features (location, push, media)  | `ti-howtos`    |
+| Alloy CLI, configuration, debugging      | `alloy-howtos` |
+| UI layouts, ListViews, gestures          | `ti-ui`        |
+
+## Response Format
+
+1.  **Technical Recommendation**: Cite the specific TiDev best practice.
+2.  **Optimized Implementation**: Provide modern ES6+ code without semicolons.
+3.  **Rationale**: Briefly explain the performance or memory impact.

package/skills/ti-guides/references/advanced-data-and-images.md

@@ -0,0 +1,19 @@
+# Advanced Database and Image Best Practices
+
+## 1. SQLite Optimization
+- **Close Everything**: Always `resultSet.close()` and `db.close()` after each operation to avoid locks and memory bloat.
+- **Transactions**: Use `BEGIN` and `COMMIT` for batch inserts. It is significantly faster.
+  ```javascript
+  db.execute('BEGIN');
+  // loop inserts
+  db.execute('COMMIT');
+  ```
+- **Database Skeleton**: Do not ship large pre-populated databases. Ship a "skeleton" and download data on first boot to reduce IPA/APK size.
+
+## 2. Image Memory Management
+- **Memory Footprint**: A JPG is tiny on disk but consumes `width * height * 3 bytes` in RAM.
+- **Unloading**:
+  - `view.remove(imageView)` to help the OS free memory.
+  - Set `imageView = null` to release the native proxy.
+- **Resizing**: Always resize images to their display dimensions via `imageAsResized` before setting the `image` property.
+- **Caching**: iOS caches remote images automatically, but you should manually cache critical assets in `applicationDataDirectory` for predictability.

package/skills/ti-guides/references/alloy-cli-advanced.md

@@ -0,0 +1,84 @@
+# Alloy CLI Reference
+
+The `alloy` command is the primary interface for managing Alloy metadata and automation.
+
+## 1. Internationalization (i18n) Extraction
+
+Instead of manually managing `strings.xml`, use the `extract-i18n` command to automatically scan your XML, JS, and TSS files for `L()` or `Ti.Locale.getString()` calls.
+
+### Syntax
+```bash
+# Preview the strings found in the project
+alloy extract-i18n [language]
+
+# Create or update the strings.xml file
+alloy extract-i18n [language] --apply
+```
+
+### Key Benefits
+- **Accuracy**: Ensures all strings used in code are present in the translation files
+- **Safety**: The `--apply` flag only adds new entries and never deletes or overwrites existing ones
+- **Efficiency**: Faster than manual entry and prevents human error
+
+## 2. Code Generation
+
+Generate components from templates to speed up development:
+
+```bash
+# Create a new controller
+alloy generate controller <name>
+
+# Generate other component types
+alloy generate view <name>
+alloy generate model <name>
+alloy generate widget <name>
+alloy generate migration <name>
+```
+
+## 3. Installation Commands
+
+Install specialized components or themes:
+
+```bash
+# Install a widget or theme
+alloy install widget <path>
+alloy install theme <path>
+```
+
+## 4. Project Conversion
+
+Convert a Classic Titanium project to Alloy:
+
+```bash
+alloy new
+```
+
+## 5. Configuration Files
+
+### `config.json`
+Global app configuration file. Can store:
+- Theme settings (`theme: "theme_name"`)
+- Environment variables
+- Per-platform themes
+- App-specific metadata
+
+### `alloy.js`
+Global initializer executed before any controllers. Perfect for:
+- Creating `Alloy.Collections`
+- Setting up `Alloy.Globals`
+- Initializing singletons
+- Configuring global event listeners
+
+### `alloy.jmk`
+Build configuration file for pre-compile and post-compile hooks:
+```javascript
+task('pre:compile', (event, logger) => {
+  // Run before compilation
+  // Example: Auto-run PurgeTSS
+});
+```
+
+Common use cases:
+- Auto-running PurgeTSS
+- Custom asset processing
+- Environment-specific configurations

package/skills/ti-guides/references/alloy-data-mastery.md

@@ -0,0 +1,29 @@
+# Alloy Data Mastery: Sync Adapters and Binding
+
+## 1. Sync Adapters
+Sync adapters connect Backbone Models to persistent storage.
+- **Ready-Made Adapters**:
+  - `sql`: SQLite (Android/iOS). Supports `query` in `fetch()` and `idAttribute`.
+  - `properties`: `Ti.App.Properties` storage.
+- **Custom Adapters**: Created in `app/lib/alloy/sync`. Requires `sync` function implementation.
+- **Migrations**: Incremental database changes. Named `YYYYMMDDHHmmss_model.js`.
+  - **CRITICAL**: Do not close the `db` handle or open a second instance within a migration.
+
+## 2. Data Binding Principles
+- **Collection Binding**: Bind a collection to a container (ListView, TableView, ScrollableView).
+  - Mandatory: `dataCollection` attribute.
+  - Optional: `dataTransform` (JSON mapping), `dataFilter` (filtering models), `dataFunction` (manual update trigger).
+- **Model Binding**: Bind a single model to a view (e.g., `<Label text="{model.name}" />`).
+- **Memory Management**: **CRITICAL**: You MUST call `$.destroy()` on the controller's `close` event to unbind Backbone listeners and prevent leaks.
+
+## 3. High-Performance Transformations
+- **Lazy Transformation**: Use `Object.defineProperty` in `extendModel` to compute transformations only when accessed.
+  ```javascript
+    transform() {
+      const t = this.toJSON();
+      Object.defineProperty(t, 'friendlyDate', {
+        get: () => moment(t.date).fromNow()
+      });
+      return t;
+    }
+  ```

package/skills/ti-guides/references/alloy-widgets-and-themes.md

@@ -0,0 +1,19 @@
+# Alloy Widgets and Themes
+
+## 1. Widgets (Self-contained components)
+- **Structure**: Mirror the `app` directory. Main controller is `widget.js`.
+- **Public API**: Methods prefixed with `$` are public (e.g., `$.init = (args) => {}`).
+- **Resource Access**: Use `WPATH()` for widget assets and libs (e.g., `require(WPATH('helper'))`).
+- **Nesting**: Widgets can contain other widgets via `<Widget src="widgetName" name="subController" />`.
+
+## 2. Styling Priorities (Low to High)
+1. `app.tss` (Global)
+2. `themes/<name>/styles/app.tss` (Theme Global)
+3. `styles/<controller>.tss` (Controller Style)
+4. `themes/<name>/styles/<controller>.tss` (Theme Controller Style)
+5. XML attributes (Inline Style)
+
+## 3. Themes
+- Located in `app/themes/<theme_name>`.
+- Merges `config.json`, `i18n`, and `styles`. Overwrites `assets` and `lib`.
+- Configured in `config.json` via the `theme` key. Supports per-platform themes.

package/skills/ti-guides/references/android-manifest.md

@@ -0,0 +1,97 @@
+# Custom AndroidManifest.xml
+
+For most Android manifest settings, use `tiapp.xml`. Only create a custom manifest when absolutely necessary.
+
+## Preferred Method: tiapp.xml
+
+Add manifest entries in `tiapp.xml` inside the `<android>` section:
+
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+    <manifest>
+        <!-- SDK version -->
+        <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="34" />
+
+        <!-- Screen support -->
+        <supports-screens
+            android:smallScreens="false"
+            android:normalScreens="true"
+            android:largeScreens="true"
+            android:xlargeScreens="true"
+        />
+
+        <!-- Permissions -->
+        <uses-permission android:name="android.permission.CAMERA" />
+        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+        <!-- Application attributes (merged, not replaced) -->
+        <application android:debuggable="true" />
+    </manifest>
+</android>
+```
+
+## How Merging Works
+
+- **Most elements**: Replaced by your entry
+- **`<application>` element**: Attributes are merged additively
+- **Activities/Services**: Added to existing ones
+
+## Custom Manifest (Rare Cases)
+
+If you need full control, create `platform/android/AndroidManifest.xml`:
+
+```
+MyApp/
+├── app/
+├── platform/
+│   └── android/
+│       └── AndroidManifest.xml  # Custom manifest
+└── tiapp.xml
+```
+
+**Warning**: You must maintain this file manually through SDK updates.
+
+## Common Use Cases
+
+### Camera Permission
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+```
+
+### Hardware Requirements
+```xml
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+```
+
+### Launch Mode
+```xml
+<application android:launchMode="singleTask" />
+```
+
+### Deep Links
+```xml
+<intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="myapp" android:host="path" />
+</intent-filter>
+```
+
+## Debugging
+
+To see the generated manifest:
+```bash
+ti build -p android
+# Check: build/android/AndroidManifest.xml.gen
+```
+
+## Enable Manifest Merge (CLI 7.0+)
+
+If using custom manifest, enable merge in `tiapp.xml`:
+
+```bash
+ti config android.mergeCustomAndroidManifest true
+```
+
+This merges your custom manifest with the generated one instead of replacing it.

package/skills/ti-guides/references/app-distribution.md

@@ -0,0 +1,258 @@
+# App Distribution Guide
+
+Complete guide for distributing Titanium apps to Google Play (Android) and App Store (iOS).
+
+## Android Distribution
+
+### 1. Generate Keystore and Certificate
+
+Create a keystore for signing your app:
+
+```bash
+keytool -genkeypair -v -keystore android.keystore -alias helloworld -keyalg RSA -sigalg SHA1withRSA -validity 10000
+```
+
+**Requirements:**
+- `keyalg`: RSA (required by Google Play)
+- `sigalg`: SHA1withRSA (Android 4.3-) or SHA256withRSA (Android 4.4+)
+- `validity`: 10000 days minimum (~25 years)
+
+**CRITICAL**: Save your keystore password securely. If lost, you cannot release updates.
+
+### 2. Verify Keystore
+
+```bash
+keytool -list -v -keystore android.keystore
+```
+
+### 3. Build for Google Play
+
+**CLI command:**
+```bash
+ti build -p android -T dist-playstore [-K <KEYSTORE_FILE> -P <KEYSTORE_PASSWORD> -L <KEYSTORE_ALIAS> -O <OUTPUT_DIRECTORY>]
+```
+
+**Example:**
+```bash
+ti build -p android -T dist-playstore -K ~/android.keystore -P secret -L foo -O ./dist/
+```
+
+**Output files:**
+- `.apk` - Legacy format (still supported)
+- `.aab` - Android App Bundle (preferred, smaller downloads)
+
+### 4. Verify APK Signing
+
+```bash
+jarsigner -verify -verbose path/yourapp.apk
+```
+
+### 5. Deploy to Device for Testing
+
+**Using CLI:**
+```bash
+ti build -p android -T device --device-id "<DEVICE_ID>"
+```
+
+**Using adb:**
+```bash
+adb install -r your_project/build/android/bin/app.apk
+adb uninstall com.your.appid
+```
+
+**Remote testing:**
+- Host APK on web/Dropbox and email link
+- Use HockeyKit/HockeyApp for beta distribution
+
+### 6. Google Play Submission Requirements
+
+**Required assets:**
+- Minimum 2 screenshots (320x480, 480x800, or 480x854)
+- High-res icon (512x512)
+- Title, description (4000 chars max)
+- Promo text (80 chars max)
+- Category and content rating
+- Contact information
+
+**Versioning in tiapp.xml:**
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+    <manifest android:versionCode="2" android:versionName="1.0.1"/>
+</android>
+```
+
+- `versionCode`: Integer, must increment for each update
+- `versionName`: String, any format you prefer
+
+### 7. SD Card Installation
+
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+   <manifest android:installLocation="preferExternal"/>
+</android>
+```
+
+Values: `preferExternal`, `auto`, `internalOnly`
+
+---
+
+## iOS Distribution
+
+### 1. Distribution Types
+
+- **App Store**: Public distribution via iTunes Store
+- **Ad Hoc**: Limited testing (max 100 devices)
+- **In House**: Enterprise distribution for employees (Enterprise program only)
+
+### 2. Create Distribution Certificate
+
+1. Log in to [Apple Developer Member Center](https://developer.apple.com/membercenter/)
+2. Go to **Certificates, Identifiers & Profiles** > **Certificates**
+3. Click **+** > **App Store and Ad Hoc**
+4. Create a CSR (Certificate Signing Request) in Keychain Access
+5. Upload CSR and generate certificate
+6. Download and install the `.cer` file
+7. **CRITICAL**: Export private key as `.p12` file (File > Export Items)
+
+### 3. Create Distribution Provisioning Profile
+
+1. In [Member Center](https://developer.apple.com/membercenter/), go to **Provisioning Profiles**
+2. Click **+** > select distribution type
+3. Select App ID
+4. Select distribution certificate
+5. For Ad Hoc: select test devices
+6. Name profile (include "distribution" or "ad hoc")
+7. Download `.mobileprovision` and install (drag to Xcode icon)
+
+### 4. Create App ID on iTunes Connect
+
+1. Log in to [iTunes Connect](https://itunesconnect.apple.com)
+2. **Manage Your Apps** > **Add New App**
+3. Provide:
+   - App name
+   - SKU number (unique ID)
+   - Bundle ID (must match App ID from Developer Portal)
+4. Configure:
+   - Availability date
+   - Price tier
+   - Version number
+   - Description (4000 chars max)
+   - Category, keywords (100 chars max)
+   - Copyright
+   - Support URL
+   - Rating info
+   - High-res icon: 1024x1024, 72 DPI, RGB, flat artwork
+   - Screenshots:
+     - iPhone (3.5"): 960x640, 960x600, 640x960, or 640x920
+     - iPhone (4"): 1136x640, 1136x600, 640x1136, or 640x1096
+     - iPad: 1024x768, 1024x748, 768x1024, 768x1004, 2048x1536, 2048x1496, 1536x2048, or 1536x2008
+5. Click **Ready to Upload Binary**
+
+### 5. Build and Package
+
+**CLI command - Ad Hoc:**
+```bash
+ti build -p ios -T dist-adhoc [-R <DISTRIBUTION_CERTIFICATE_NAME> -P <PROVISIONING_PROFILE_UUID> -O <OUTPUT_DIRECTORY>]
+```
+
+**Example:**
+```bash
+ti build -p ios -T dist-adhoc -R "Pseudo, Inc." -P "FFFFFFFF-EEEE-DDDD-CCCC-BBBBBBBBBBBB" -O ./dist/
+```
+
+**CLI command - App Store:**
+```bash
+ti build -p ios -T dist-appstore [-R <DISTRIBUTION_CERTIFICATE_NAME> -P <PROVISIONING_PROFILE_UUID>]
+```
+
+**Example:**
+```bash
+ti build -p ios -T dist-appstore -R "Pseudo, Inc." -P "AAAAAAAA-0000-9999-8888-777777777777"
+```
+
+The CLI installs the package to Xcode's Organizer.
+
+### 6. Upload to iTunes Connect
+
+1. Open Xcode > **Window** > **Organizer**
+2. Select your app archive
+3. Click **Verify** (validates against iTunes Connect app definition)
+4. Click **Submit** (uploads app)
+5. Status changes to **Waiting for Review**
+
+### 7. Ad Hoc Distribution
+
+Testers need:
+- The `.mobileprovision` file installed on their device
+- The `.ipa` package file
+
+**Installation method:**
+1. Connect device to Mac
+2. Open Xcode > **Window** > **Devices**
+3. Select device > **Installed Apps** > **+**
+4. Select IPA file
+
+### 8. App Store Requirements
+
+Apple's guidelines include:
+- Apps must be useful, well-designed, and error-free
+- No downloading/executing code
+- You must own all copyrights and trademarks
+- No hidden features or non-public APIs
+- [Full guidelines](http://developer.apple.com/appstore/resources/approval/guidelines.html)
+
+---
+
+## Device Deployment Testing
+
+### Android Device Setup
+
+1. Enable **Developer options** (tap **Build number** 7 times in **About**)
+2. Enable **USB debugging** in **Developer options**
+3. Enable **Unknown sources** in **Security**
+4. Connect via USB (use data cable, not power-only)
+5. Allow USB debugging when prompted
+
+**Windows only**: Install [OEM USB drivers](http://developer.android.com/sdk/oem-usb.html)
+
+### iOS Device Setup
+
+Requires development certificate and provisioning profile. See [Deploying to iOS devices](#ios-distribution).
+
+---
+
+## Troubleshooting
+
+### Android: Device Not Recognized
+
+```bash
+adb devices        # Check connected devices
+adb kill-server    # Restart adb
+adb start-server
+adb devices        # Verify
+```
+
+### Android: Check Platform Compatibility
+
+```bash
+ti info -p android
+```
+
+### iOS: Mavericks Permission Issues
+
+Grant CLI access in **System Preferences** > **Security & Privacy** > **Privacy**
+
+### General: Clean Build Folder
+
+```bash
+ti clean [-p <PLATFORM>]
+```
+
+---
+
+## References
+
+- [Google Play Developer Policies](http://play.google.com/about/developer-content-policy.html)
+- [Google Play Graphic Assets](http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1078870)
+- [iTunes Connect Developer Guide](http://developer.apple.com/library/mac/#documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/)
+- [iOS App Store Review Guidelines](http://developer.apple.com/appstore/resources/approval/guidelines.html)