@maccesar/titools 2.0.0

package/skills/ti-howtos/references/automation-fastlane-appium.md

@@ -0,0 +1,95 @@
+# Automation with Fastlane and Appium
+
+Guide for setting up continuous integration pipelines, automatic testing, and deployment in Titanium.
+
+## Table of Contents
+
+- [Automation with Fastlane and Appium](#automation-with-fastlane-and-appium)
+  - [Table of Contents](#table-of-contents)
+  - [1. UI Testing with Appium](#1-ui-testing-with-appium)
+    - [Prerequisites](#prerequisites)
+    - [Test Example (Mocha + WebdriverIO)](#test-example-mocha--webdriverio)
+  - [2. Automation with Fastlane](#2-automation-with-fastlane)
+    - [Titanium Plugins](#titanium-plugins)
+    - [Fastfile Configuration](#fastfile-configuration)
+  - [3. CI/CD Best Practices](#3-cicd-best-practices)
+
+---
+
+## 1. UI Testing with Appium
+
+Appium allows for automated functional testing on real devices and simulators.
+
+### Prerequisites
+- **Appium Desktop** or CLI.
+- **Mocha** (test runner).
+- **WebdriverIO** (recommended client).
+
+### Test Example (Mocha + WebdriverIO)
+```javascript
+const opts = {
+    port: 4723,
+    capabilities: {
+        platformName: "iOS",
+        deviceName: "iPhone 15",
+        app: "/path/to/your/app.app",
+        automationName: "XCUITest"
+    }
+};
+
+describe("Login Test", () => {
+    it("Should login with valid credentials", async () => {
+        const client = await wdio.remote(opts);
+        const userField = await client.$("~Enter Username"); // Use Accessibility ID
+        await userField.setValue("my_user");
+        await client.deleteSession();
+    });
+});
+```
+
+## 2. Automation with Fastlane
+
+Fastlane automates the building, signing, and uploading process to the stores.
+
+### Titanium Plugins
+Install specific plugins in your project:
+```bash
+fastlane add_plugin ti_build_app
+fastlane add_plugin mocha_run_tests
+```
+
+### Fastfile Configuration
+Create a `fastlane/Fastfile` in the root:
+
+```ruby
+platform :ios do
+  desc "Build for Simulator Tests"
+  lane :build_test do
+    ti_build_app(
+      appc_cli: "ti build -p ios -T simulator --build-only"
+    )
+  end
+
+  desc "Run UI Tests"
+  lane :test do
+    build_test
+    mocha_run_tests(
+      mocha_js_file_name: 'tests/login_test.js'
+    )
+  end
+
+  desc "Deploy to TestFlight"
+  lane :release do
+    ti_build_app(
+      appc_cli: "ti build -p ios -T dist-appstore --distribution-name 'Your Company' --pp-uuid 'UUID-HERE' --output-dir /dist"
+    )
+    # Add fastlane pilot command here to upload the .ipa
+  end
+end
+```
+
+## 3. CI/CD Best Practices
+1. **Accessibility IDs**: Always assign `accessibilityLabel` to your components in XML/TSS so Appium can find them easily.
+2. **Environment Lanes**: Define separate lanes for `beta`, `production`, and `test`.
+3. **Profile Management**: Use Fastlane Match to sync certificates and provisioning profiles across the team.
+4. **Snapshots**: Use Fastlane's `snapshot` action to automate App Store screenshot generation.

package/skills/ti-howtos/references/buffer-codec-streams.md

@@ -0,0 +1,140 @@
+# Buffer, Codec, and Streams
+
+Guide for advanced binary data manipulation and data flows in Titanium SDK.
+
+## Table of Contents
+
+- [Buffer, Codec, and Streams](#buffer-codec-and-streams)
+  - [Table of Contents](#table-of-contents)
+  - [1. Titanium.Buffer](#1-titaniumbuffer)
+    - [Creating Buffers](#creating-buffers)
+    - [Common Operations](#common-operations)
+  - [2. Titanium.Codec](#2-titaniumcodec)
+    - [Encoding Numbers](#encoding-numbers)
+    - [Decoding Strings](#decoding-strings)
+  - [3. Streams](#3-streams)
+    - [Stream Types](#stream-types)
+    - [Example: BufferStream](#example-bufferstream)
+    - [Example: FileStream (Chunk-based reading)](#example-filestream-chunk-based-reading)
+    - [Example: BlobStream (Camera to File)](#example-blobstream-camera-to-file)
+  - [4. Best Practices](#4-best-practices)
+
+---
+
+## 1. Titanium.Buffer
+
+Buffers are mutable and resizable containers for bytes (byte arrays).
+
+### Creating Buffers
+```javascript
+// Empty 512-byte buffer
+const buffer1 = Ti.createBuffer({ length: 512 });
+
+// Buffer initialized with a string (UTF-8 by default)
+const buffer2 = Ti.createBuffer({ value: "Hello World" });
+```
+
+### Common Operations
+```javascript
+const b1 = Ti.createBuffer({ value: "Part 1. " });
+const b2 = Ti.createBuffer({ value: "Part 2." });
+
+// Append
+b1.append(b2);
+
+// Truncate
+b1.length = 10;
+
+// Direct access (array-like)
+b1[0] = 72; // 'H' character in ASCII
+
+// Free memory
+b1.release();
+```
+
+## 2. Titanium.Codec
+
+The Codec module allows encoding and decoding primitive data (numbers and strings) to/from buffers.
+
+### Encoding Numbers
+```javascript
+const buffer = Ti.createBuffer({ length: 8 });
+Ti.Codec.encodeNumber({
+    source: 12345,
+    dest: buffer,
+    type: Ti.Codec.TYPE_INT,
+    byteOrder: Ti.Codec.BIG_ENDIAN
+});
+```
+
+### Decoding Strings
+```javascript
+const text = Ti.Codec.decodeString({
+    source: buffer,
+    charset: Ti.Codec.CHARSET_UTF8
+});
+```
+
+## 3. Streams
+
+Streams allow reading and writing data in a serialized and memory-efficient way.
+
+### Stream Types
+1. **BufferStream**: For reading/writing in memory buffers.
+2. **FileStream**: For file operations (more efficient than `file.read()`).
+3. **BlobStream**: Read-only for Blob objects (images, camera).
+
+### Example: BufferStream
+```javascript
+const buffer = Ti.createBuffer({ length: 1024 });
+const stream = Ti.Stream.createStream({
+    source: buffer,
+    mode: Ti.Stream.MODE_WRITE
+});
+
+stream.write(Ti.createBuffer({ value: "Stream data" }));
+stream.close();
+```
+
+### Example: FileStream (Chunk-based reading)
+```javascript
+const file = Ti.Filesystem.getFile('large_file.txt');
+const instream = file.open(Ti.Filesystem.MODE_READ);
+const buffer = Ti.createBuffer({ length: 1024 }); // 1KB chunks
+
+let bytesRead = 0;
+while ((bytesRead = instream.read(buffer)) > 0) {
+    Ti.API.info(`Read ${bytesRead} bytes`);
+    // Process buffer...
+}
+instream.close();
+```
+
+### Example: BlobStream (Camera to File)
+```javascript
+Ti.Media.showCamera({
+    success: (e) => {
+        const instream = Ti.Stream.createStream({
+            source: e.media,
+            mode: Ti.Stream.MODE_READ
+        });
+        
+        const outfile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, 'photo.jpg');
+        const outstream = outfile.open(Ti.Filesystem.MODE_WRITE);
+        
+        const buffer = Ti.createBuffer({ length: 4096 });
+        let readBytes = 0;
+        while ((readBytes = instream.read(buffer)) > 0) {
+            outstream.write(buffer, 0, readBytes);
+        }
+        
+        instream.close();
+        outstream.close();
+    }
+});
+```
+
+## 4. Best Practices
+- **Always close streams**: Avoid memory leaks and file locks by calling `.close()`.
+- **Use chunks**: For large files or networking, read in small blocks (e.g., 1KB or 4KB) to avoid saturating RAM.
+- **Buffers vs Blobs**: Buffers are mutable; Blobs are immutable. Convert a Blob to a Buffer if you need to modify bytes.

package/skills/ti-howtos/references/cross-platform-development.md

@@ -0,0 +1,348 @@
+# Cross-Platform Development
+
+Strategies and techniques for building Titanium apps that work on iOS and Android from a single codebase.
+
+## Table of Contents
+
+- [Cross-Platform Development](#cross-platform-development)
+  - [Table of Contents](#table-of-contents)
+  - [Philosophy](#philosophy)
+    - ["Write Once, Adapt Everywhere"](#write-once-adapt-everywhere)
+    - [Embrace the Platform](#embrace-the-platform)
+  - [Platform Identification](#platform-identification)
+    - [Platform Properties](#platform-properties)
+    - [Best Practice: Cache Platform Checks](#best-practice-cache-platform-checks)
+    - [Anti-Pattern: Don't Assume Binary](#anti-pattern-dont-assume-binary)
+  - [Coding Strategies](#coding-strategies)
+    - [1. Branching (For Mostly Similar Code)](#1-branching-for-mostly-similar-code)
+    - [2. Platform-Specific Files (For Mostly Different Code)](#2-platform-specific-files-for-mostly-different-code)
+    - [3. Single Execution Context (Recommended)](#3-single-execution-context-recommended)
+  - [Platform-Specific Resources](#platform-specific-resources)
+    - [Resource Overrides System](#resource-overrides-system)
+    - [Assets (Alloy)](#assets-alloy)
+  - [5. Webpack Build Pipeline (TiSDK 9.1.0+)](#5-webpack-build-pipeline-tisdk-910)
+    - [`@` Alias](#-alias)
+    - [NPM Support](#npm-support)
+  - [6. Internationalization (i18n)](#6-internationalization-i18n)
+    - [Using Localized Strings](#using-localized-strings)
+    - [Date and Currency Formatting](#date-and-currency-formatting)
+    - [Testing Localizations](#testing-localizations)
+  - [Platform-Specific APIs](#platform-specific-apis)
+    - [Example: Platform-Specific Properties](#example-platform-specific-properties)
+  - [Common Cross-Platform Patterns](#common-cross-platform-patterns)
+    - [Tab Groups](#tab-groups)
+    - [Navigation](#navigation)
+    - [Platform-Specific Event Handling](#platform-specific-event-handling)
+  - [Best Practices](#best-practices)
+  - [Resources](#resources)
+
+---
+
+## Philosophy
+
+### "Write Once, Adapt Everywhere"
+
+Titanium is **not** "write once, run anywhere." It's "write once, **adapt** everywhere."
+
+**What's shared (90-100%):**
+- Business logic
+- Networking code
+- Database operations
+- Event handling
+- Data models
+
+**What differs:**
+- UI conventions (tabs position, navigation)
+- Platform-specific features
+- Hardware capabilities
+- User expectations
+
+### Embrace the Platform
+
+Best-of-breed apps feel **native** on each platform:
+
+- **iOS** - Bottom tabs, left navigation buttons, iOS-specific controls
+- **Android** - Top tabs, Menu button (legacy), Action Bar, Material Design
+
+**Develop for both platforms from the start** - much more efficient than porting later.
+
+---
+
+## Platform Identification
+
+### Platform Properties
+
+```javascript
+// Platform name
+Ti.Platform.name          // "iPhone OS", "android", "mobileweb"
+Ti.Platform.osname        // "iphone", "ipad", "android", "mobileweb"
+Ti.Platform.model         // "iPhone 15", "Pixel 8", etc.
+```
+
+### Best Practice: Cache Platform Checks
+
+```javascript
+// Create aliases - query once, use many times
+const osname = Ti.Platform.osname;
+const isAndroid = (osname === 'android');
+const isIOS = (osname === 'iphone' || osname === 'ipad');
+const isMobileWeb = (osname === 'mobileweb');
+```
+
+### Anti-Pattern: Don't Assume Binary
+
+```javascript
+// BAD: Assumes if not Android, then iOS
+if (osname !== 'android') {
+   // Wrong! Could be mobile web or future platform
+}
+
+// GOOD: Explicit checks
+if (isAndroid) {
+   // Android code
+} else if (isIOS) {
+   // iOS code
+}
+```
+
+---
+
+## Coding Strategies
+
+### 1. Branching (For Mostly Similar Code)
+
+Use when code is 90%+ the same with small differences.
+
+```javascript
+const isAndroid = (Ti.Platform.osname === 'android');
+
+const win = Ti.UI.createWindow({
+    backgroundColor: 'white',
+    // Platform-specific property
+    softInputMode: isAndroid ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null
+});
+```
+
+**Tips:**
+- Cache platform checks to avoid repeated "bridge crossings"
+- Group as much code as possible within branches
+- Defer loading to reduce performance impact
+
+### 2. Platform-Specific Files (For Mostly Different Code)
+
+Use when code differs significantly between platforms.
+
+**Structure:**
+```
+Resources/
+├── ui.js              // Common code (optional)
+├── android/
+│   └── ui.js          // Android-specific (overrides)
+└── iphone/
+    └── ui.js          // iOS-specific (overrides)
+```
+
+**Usage:**
+```javascript
+// Will automatically include the specific version
+const ui = require('ui');
+// Carga: /android/ui.js en Android, /iphone/ui.js en iOS
+```
+
+### 3. Single Execution Context (Recommended)
+
+**Avoid multiple contexts:**
+```javascript
+// Creates a new context - variables from app.js are not available
+Ti.UI.createWindow({
+    url: 'window.js'  // DON'T DO THIS
+}).open();
+```
+
+**Use instead:**
+```javascript
+// Same context - all variables available
+const win = Ti.UI.createWindow({});
+require('window')(win);
+win.open();
+```
+
+---
+
+## Platform-Specific Resources
+
+### Resource Overrides System
+
+```javascript
+// Automatically uses the platform-specific version
+const image = Ti.UI.createImageView({
+    image: '/images/logo.png'  // Will choose the correct file
+});
+```
+
+### Assets (Alloy)
+
+```
+app/
+├── assets/
+│   └── images/
+│       └── logo.png      // Default
+├── assets/
+│   └── android/
+│       └── images/
+│           └── logo.png  // Android
+└── assets/
+    └── iphone/
+        └── images/
+            └── logo.png  // iOS
+```
+
+---
+
+## 5. Webpack Build Pipeline (TiSDK 9.1.0+)
+
+Titanium's modern build engine optimizes packaging and allows using NPM libraries natively.
+
+### `@` Alias
+Use `@` to reference your code root regardless of the current folder depth.
+```javascript
+import MyModule from '@/utils/myModule'; // Points to app/lib or src
+```
+
+### NPM Support
+Install any NPM package in the project root and use it directly with `import`.
+
+For more details on optimization, diagnostics, and build Web UI, see:
+- [Webpack Build Pipeline](./webpack-build-pipeline.md)
+
+## 6. Internationalization (i18n)
+
+### Using Localized Strings
+
+**Basic usage:**
+```javascript
+// Two equivalent methods
+const str1 = L('welcome_message');
+const str2 = Ti.Locale.getString('welcome_message');
+```
+
+**String formatting:**
+```javascript
+// Simple replacement
+const formatted = String.format(L('format_test'), 'Kevin');
+// Result: "Your name is Kevin"
+
+// Ordered replacement
+const formatted = String.format(L('ordered'), 'Jeff', 'Kevin');
+// Result: "Hi Jeff, my name is Kevin"
+```
+
+### Date and Currency Formatting
+
+```javascript
+// Date formatting
+const today = new Date();
+const dateStr = String.formatDate(today, 'long');
+const timeStr = String.formatTime(today, 'short');
+
+// Currency
+const price = String.formatCurrency(1234.56);
+
+// Decimal
+const amount = String.formatDecimal(1234.56);
+```
+
+### Testing Localizations
+
+**iOS:**
+1. Settings → General → Language & Region
+2. Change iPhone Language
+3. Confirm and restart device
+
+**Android:**
+1. Settings → Language & input
+2. Select Language
+
+---
+
+## Platform-Specific APIs
+
+### Example: Platform-Specific Properties
+
+```javascript
+const win = Ti.UI.createWindow({
+    // iOS-specific
+    barColor: isIOS ? '#007AFF' : null,
+    titlePrompt: isIOS ? 'Title' : null,
+
+    // Android-specific
+    softInputMode: isAndroid ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null,
+    exitOnClose: isAndroid ? true : false
+});
+```
+
+---
+
+## Common Cross-Platform Patterns
+
+### Tab Groups
+
+```javascript
+const tabGroup = Ti.UI.createTabGroup();
+
+const tab1 = Ti.UI.createTab({
+    title: 'Tab 1',
+    icon: isIOS ? 'tab1.png' : null,  // iOS uses icons
+    window: win1
+});
+
+tabGroup.addTab(tab1);
+tabGroup.open();
+```
+
+### Navigation
+
+```javascript
+if (isIOS) {
+    // iOS: Navigation window with back button
+    const nav = Ti.UI.iOS.createNavigationWindow({
+        window: win
+    });
+    nav.open();
+} else if (isAndroid) {
+    // Android: Open window, use physical button
+    win.open();
+}
+```
+
+### Platform-Specific Event Handling
+
+```javascript
+if (isAndroid) {
+    // Android: Handle physical 'Back' button
+    win.addEventListener('androidback', (e) => {
+        // Custom behavior
+        alert('Back pressed!');
+    });
+}
+```
+
+---
+
+## Best Practices
+
+1. **Test early on both platforms** - Don't wait until "porting time"
+2. **Use Alloy framework** - Provides MVC structure and platform abstraction
+3. **Follow platform conventions** - iOS apps should feel like iOS, Android like Android
+4. **Cache platform checks** - Store in variables, don't call `Ti.Platform.osname` repeatedly
+5. **Use CommonJS modules** - Better code organization and reusability
+6. **Leverage resource overrides** - Avoid conditional code for images/assets
+7. **Think cross-platform from design phase** - UI should adapt gracefully
+
+---
+
+## Resources
+
+- **Alloy Framework** - MVC framework for Titanium (see alloy-guides skill)
+- **CommonJS Modules** - Module specification (see coding-strategies above)
+- **Platform API Deep Dives** - iOS and Android platform-specific features