@maccesar/titools 2.0.0

package/skills/ti-guides/references/cli-reference.md

@@ -0,0 +1,402 @@
+# Titanium CLI Reference
+
+Complete reference for Titanium CLI commands, options, and configuration.
+
+## Environment Setup
+
+### Check Environment
+
+```bash
+ti setup check
+```
+
+Reports configured tools and potential issues.
+
+### Get System Info
+
+```bash
+ti info
+```
+
+Detailed environment info (SDKs, certificates, provisioning profiles).
+
+```bash
+ti info -p android  # Android-specific info
+ti info -p ios      # iOS-specific info
+```
+
+### Configure CLI
+
+```bash
+# Display current config
+ti config
+
+# Set option
+ti config cli.logLevel info
+
+# Append to path
+ti config -a paths.hooks "/path/to/hook"
+
+# Remove all Android options
+ti config -r android
+```
+
+**Alternative methods:**
+```bash
+# Pass JSON string
+ti build -p ios --config "{ paths: { hooks: '/path/to/hook' } }"
+
+# Pass JSON file
+ti build -p ios --config-file "/Users/me/customConfig.json"
+```
+
+---
+
+## Project Commands
+
+### Create Project
+
+**For Alloy projects (recommended):**
+```bash
+ti create -t app --alloy --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE> -u <URL>
+```
+
+**Example (Alloy):**
+```bash
+ti create -t app --alloy --id com.titaniumsdk.sample -n SampleProject -p android,ios -d ~/Documents/workspace -u https://titaniumsdk.com
+```
+
+**For Classic Titanium projects:**
+```bash
+ti create -t app --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE> -u <URL>
+```
+
+**Parameters:**
+- `--alloy`: Create an Alloy project (recommended for new projects)
+- `-t, --type`: Project type (`app`)
+- `--id`: App ID (reverse domain notation)
+- `-n, --name`: App name
+- `-p, --platforms`: Comma-separated platforms (`android`, `ios`, `ipad`, `iphone`)
+- `-d, --dir`: Workspace directory
+- `-u, --url`: App URL
+
+> **Note:** Always use the `--alloy` flag when creating new projects. The Alloy framework provides MVC structure, data binding, and modern development patterns. Use Classic (`--classic` or omitting `--alloy`) only when maintaining legacy projects.
+
+### Build Project
+
+```bash
+ti build -p <PLATFORM> [OPTIONS]
+```
+
+---
+
+## Build Commands
+
+### Android Emulator
+
+```bash
+ti build -p android [-C <EMULATOR_NAME>]
+```
+
+**Example:**
+```bash
+ti build -p android -C "Google Nexus 7 - 4.4.2 - API 19 - 800x1280"
+```
+
+List emulators: `ti info -p android`
+
+### Android Device
+
+```bash
+ti build -p android -T device -C <DEVICE_ID>
+```
+
+**Example:**
+```bash
+ti build -p android -T device -C deadbeef
+```
+
+Omit `-C` if only one device connected.
+
+### iOS Simulator
+
+```bash
+ti build -p ios [-C <SIMULATOR_NAME>]
+```
+
+**Example:**
+```bash
+ti build -p ios -C "iPad Retina"
+```
+
+### iOS Device
+
+```bash
+ti build -p ios -T device -C <DEVICE_UDID> [-V "<CERT_NAME>" -P <PROFILE_UUID>]
+```
+
+**Example:**
+```bash
+ti build -p ios -T device -C itunes -V "Loretta Martin (GE7BAC5)" -P "11111111-2222-3333-4444-555555555555"
+```
+
+Omit `-V` and `-P` to be prompted.
+
+### Clean Build
+
+```bash
+ti clean [-p <PLATFORM>]
+```
+
+**Examples:**
+```bash
+ti clean          # All platforms
+ti clean -p ios   # iOS only
+```
+
+### Module Management
+
+```bash
+ti module [TASK] [OPTIONS]
+```
+
+**Tasks:**
+- `create`: Create a new Titanium module.
+
+### Project Management
+
+```bash
+ti project [TASK] [OPTIONS]
+```
+
+**Tasks:**
+- `scan`: Scan directory for Titanium projects.
+
+---
+
+## Distribution Commands
+
+### Google Play (Android)
+
+```bash
+ti build -p android -T dist-playstore [-K <KEYSTORE> -P <PASSWORD> -L <ALIAS> -O <OUTPUT>]
+```
+
+**Example:**
+```bash
+ti build -p android -T dist-playstore -K ~/android.keystore -P secret -L foo -O ./dist/
+```
+
+**If key password differs from keystore password:**
+```bash
+--key-password <KEYPASS>
+```
+
+### Ad Hoc (iOS)
+
+```bash
+ti build -p ios -T dist-adhoc [-R <CERT_NAME> -P <PROFILE_UUID> -O <OUTPUT>]
+```
+
+**Example:**
+```bash
+ti build -p ios -T dist-adhoc -R "Pseudo, Inc." -P "FFFFFFFF-EEEE-DDDD-CCCC-BBBBBBBBBBBB" -O ./dist/
+```
+
+### App Store (iOS)
+
+```bash
+ti build -p ios -T dist-appstore [-R <CERT_NAME> -P <PROFILE_UUID>]
+```
+
+**Example:**
+```bash
+ti build -p ios -T dist-appstore -R "Pseudo, Inc." -P "AAAAAAAA-0000-9999-8888-777777777777"
+```
+
+Installs package to Xcode Organizer.
+
+---
+
+## SDK Management
+
+### List SDKs
+
+```bash
+ti sdk list
+```
+
+### Select SDK
+
+```bash
+ti sdk select
+```
+
+Interactive selection of default SDK.
+
+---
+
+## Configuration Options
+
+### Android Options
+
+| Option                               | Default     | Description                      |
+| ------------------------------------ | ----------- | -------------------------------- |
+| `android.sdkPath`                    | auto        | Android SDK path                 |
+| `android.ndkPath`                    | auto        | Android NDK path                 |
+| `android.adb.port`                   | 5037        | ADB port number                  |
+| `android.autoSelectDevice`           | true        | Auto-select device/emulator      |
+| `android.symlinkResources`           | true (OS X) | Symlink vs copy resources        |
+| `android.buildTools.selectedVersion` | max         | Build tools version              |
+| `android.javac.maxmemory`            | "1024M"     | JVM heap size                    |
+| `android.javac.source`               | "1.6"       | Java source version              |
+| `android.javac.target`               | "1.6"       | Java target version              |
+| `android.mergeCustomAndroidManifest` | false       | Merge custom AndroidManifest.xml |
+
+### iOS Options
+
+| Option                 | Default     | Description                           |
+| ---------------------- | ----------- | ------------------------------------- |
+| `ios.developerName`    | -           | Developer certificate name            |
+| `ios.distributionName` | -           | Distribution certificate name         |
+| `ios.autoSelectDevice` | true        | Auto-select device/simulator          |
+| `ios.symlinkResources` | true (OS X) | Symlink vs copy resources             |
+| `ios.keychain`         | -           | Specific keychain to search for certs |
+| `ios.xcodePath`        | auto        | Path to Xcode installation            |
+
+### CLI Options
+
+| Option                   | Default | Description                                   |
+| ------------------------ | ------- | --------------------------------------------- |
+| `cli.logLevel`           | trace   | Log level: error, warning, info, debug, trace |
+| `cli.colors`             | true    | Color output                                  |
+| `cli.progressBars`       | true    | Show progress bars                            |
+| `cli.prompt`             | true    | Prompt for missing info                       |
+| `cli.quiet`              | false   | Suppress all output                           |
+| `cli.rejectUnauthorized` | true    | Reject bad SSL certs                          |
+| `cli.width`              | 100     | Text wrap width                               |
+| `cli.failOnWrongSDK`     | false   | Fail on SDK mismatch                          |
+| `cli.hideCharEncWarning` | false   | Hide encoding warnings                        |
+| `cli.httpProxyServer`    | -       | Proxy server URL                              |
+
+### SDK Options
+
+| Option                       | Description                        |
+| ---------------------------- | ---------------------------------- |
+| `sdk.defaultInstallLocation` | SDK install location (OS-specific) |
+| `sdk.selected`               | Selected SDK version (REQUIRED)    |
+
+### Paths
+
+| Option           | Description                    |
+| ---------------- | ------------------------------ |
+| `paths.commands` | Additional CLI command scripts |
+| `paths.hooks`    | CLI hook scripts               |
+| `paths.modules`  | Module search paths            |
+| `paths.plugins`  | Plugin search paths            |
+| `paths.sdks`     | SDK search paths               |
+| `paths.xcode`    | Xcode installation paths       |
+
+### Java Options
+
+| Option                       | Description               |
+| ---------------------------- | ------------------------- |
+| `java.home`                  | JDK directory             |
+| `java.executables.java`      | java executable path      |
+| `java.executables.javac`     | javac executable path     |
+| `java.executables.jarsigner` | jarsigner executable path |
+| `java.executables.keytool`   | keytool executable path   |
+
+### Genymotion Options
+
+| Option                              | Description               |
+| ----------------------------------- | ------------------------- |
+| `genymotion.enabled`                | Enable Genymotion support |
+| `genymotion.path`                   | Genymotion app directory  |
+| `genymotion.executables.genymotion` | genymotion executable     |
+| `genymotion.executables.player`     | player executable         |
+| `genymotion.executables.vboxmanage` | vboxmanage executable     |
+
+### Application Options
+
+| Option                      | Description                 |
+| --------------------------- | --------------------------- |
+| `app.idprefix`              | Prefix for new app IDs      |
+| `app.publisher`             | Default publisher           |
+| `app.url`                   | Default company URL         |
+| `app.workspace`             | Default workspace directory |
+| `app.skipAppIdValidation`   | Skip app ID validation      |
+| `app.skipVersionValidation` | Skip version validation     |
+
+---
+
+## Common Issues
+
+### Android SDK Not Found
+
+```bash
+! sdk                Android SDK not found
+! targets            no targets found
+! avds               no avds found
+```
+
+**Solution:**
+```bash
+ti config android.sdkPath /path/to/android-sdk
+```
+
+### Xcode Too Old
+
+```bash
+! Xcode 4.3 is too old and is no longer supported by Titanium SDK 3.3.0
+```
+
+**Solution:** Install newer Xcode from Mac App Store.
+
+### Clean Build Issues
+
+```bash
+ti clean -p ios
+ti clean -p android
+```
+
+### ADB Device Issues
+
+```bash
+adb kill-server
+adb start-server
+adb devices
+```
+
+---
+
+## Command Quick Reference
+
+| Command                 | Description             |
+| ----------------------- | ----------------------- |
+| `ti setup check`        | Check environment setup |
+| `ti info`               | Display system info     |
+| `ti info -p <PLATFORM>` | Platform-specific info  |
+| `ti config`             | Display/set config      |
+| `ti create`             | Create new project      |
+| `ti build`              | Build project           |
+| `ti clean`              | Clean build folder      |
+| `ti sdk list`           | List installed SDKs     |
+| `ti sdk select`         | Select default SDK      |
+
+---
+
+## SDK Version Precedence
+
+1. `tiapp.xml` `<sdk-version>` tag
+2. `--sdk` CLI option
+3. `app.sdk` config setting
+4. Selected SDK (`ti sdk select`)
+
+---
+
+## References
+
+- [Titanium CLI GitHub](https://github.com/tidev/titanium-cli)
+- [Android SDK Manager](http://developer.android.com/sdk)
+- [Xcode Downloads](https://apps.apple.com/us/app/xcode/id497799835?mt=12/)

package/skills/ti-guides/references/coding-best-practices.md

@@ -0,0 +1,102 @@
+# Coding Best Practices
+
+## 1. Scope Management
+- **Avoid Global Scope**: Global variables are not automatically garbage collected and can cause naming conflicts.
+- **Always use `let` or `const`**: (Original guide says `var`, but modernization rules apply). Omitting declarations places variables in the global scope.
+
+## 2. Memory Leak Prevention
+- **Global Event Listeners**: Listeners on `Ti.App`, `Ti.Geolocation`, etc., will leak memory if they reference locally scoped objects unless explicitly removed.
+```javascript
+// ANTI-PATTERN
+Ti.App.addEventListener('data:sync', (e) => {
+  localView.text = e.text // localView is now leaked
+})
+```
+- **Rule**: Global events should only handle global objects. Always `removeEventListener` during cleanup.
+
+## 3. Event Naming Conventions
+- **No Spaces in Event Names**: Using spaces in custom event names causes issues with Backbone.js and other libraries that use spaces as delimiters.
+```javascript
+// ❌ WRONG - may fire multiple times
+Ti.App.fireEvent('my event')
+
+// ✅ CORRECT - use colon or underscore
+Ti.App.fireEvent('my:event')
+Ti.App.fireEvent('my_event')
+```
+
+## 4. Performance
+- **Defer Script Loading**: Evaluate JavaScript only when needed. Don't `require` modules at startup if they are only for specific screens.
+
+**Lazy script loading example:**
+```javascript
+// must be loaded at launch
+const WindowOne = require('ui/WindowOne').WindowOne;
+const win1 = new WindowOne();
+win1.open();
+
+win1.addEventListener('click', () => {
+  // load window two JavaScript only when needed
+  const WindowTwo = require('ui/WindowTwo').WindowTwo;
+  const win2 = new WindowTwo();
+  win2.open();
+});
+```
+
+- **Bridge Efficiency**: Minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable once.
+- **Avoid Extending Ti Namespace**: Never add properties to `Ti.*` as it's a proxy system and leads to instability.
+
+## 5. App Architecture Recommendations
+
+### Modular Components with CommonJS (Recommended)
+Titanium's primary recommended architecture. Discrete and independent building blocks that eliminate global variables.
+
+**MyModule.js**
+```javascript
+// Private variable
+const defaultMessage = "Hello world";
+
+exports.sayHello = (msg) => {
+  Ti.API.info('Hello ' + msg);
+};
+
+exports.helloWorld = () => {
+  Ti.API.info(defaultMessage);
+}
+```
+
+**app.js**
+```javascript
+const myModule = require('/MyModule');
+myModule.sayHello('User');
+```
+
+### Custom Objects as Components
+Popular for rapid deployment. Uses a namespace hierarchy.
+```javascript
+const myapp = {};
+(() => {
+  myapp.ui = {}; 
+  myapp.ui.createApplicationWindow = () => {
+    const win = Ti.UI.createWindow({ backgroundColor:'white' });
+    return win;
+  };
+})();
+```
+
+### Classical-based Patterns
+Not recommended as JavaScript is not a class-based language. It confuses classes and objects and is slower to implement in rapid prototyping.
+
+## 6. Security Best Practices
+- **No Sensitive Data in Non-JS Files**: JavaScript files are minified and obfuscated during build, but images, JSON files, SQLite databases, and other non-.js files are packaged as-is. APK and IPA files are essentially ZIP files that can be extracted.
+```javascript
+// ❌ WRONG - API keys visible in app/assets/config.json
+const config = require('assets/config.json')
+
+// ✅ CORRECT - Store in code or use secure storage
+const API_KEY = Ti.App.Properties.getString('api_key')
+```
+
+## 7. Multiplatform Strategies
+- **Code Branching**: Use for small differences.
+- **Platform Files**: Use `.ios.js` or `.android.js` for major logic differences to keep code readable.

package/skills/ti-guides/references/commonjs-advanced.md

@@ -0,0 +1,134 @@
+# CommonJS Advanced Patterns
+
+## 1. Stateful Modules (Singleton Pattern)
+
+Modules in Titanium are created once per JavaScript context and then passed by reference on subsequent `require()` calls. This makes them ideal for maintaining application state.
+
+### Example: Stateful Counter Module
+```javascript
+// app/lib/counter.js
+let _count = 0
+
+exports.increment = () => {
+  _count++
+}
+
+exports.getCount = () => {
+  return _count
+}
+
+exports.reset = () => {
+  _count = 0
+}
+```
+
+**Usage**: Multiple controllers requiring this module share the same `_count` state.
+
+### Critical Note
+A module is created once **per Titanium JavaScript context**. Additional contexts create new module instances.
+
+## 2. Caching Behavior
+
+Titanium caches the object returned by `require()` and provides the same reference without re-evaluating the code.
+
+**Implication**: If you think you need code evaluated multiple times, create a module with a callable function instead.
+
+```javascript
+// Good - factory pattern
+exports.createView = (args) => {
+  return Ti.UI.createView(args)
+}
+
+// Bad - expecting re-evaluation
+```
+
+## 3. ES6+ Support (SDK 7.1.0+)
+
+Since Titanium SDK 7.1.0, you can use ES6+ module syntax. Code is transpiled to ES5 for all platforms.
+
+```javascript
+// MyClass.js
+export default class MyClass {
+  constructor(name) {
+    this.name = name
+  }
+
+  greet() {
+    return `Hello, ${this.name}`
+  }
+}
+
+// Usage in controller
+import MyClass from 'MyClass'
+const instance = new MyClass('World')
+```
+
+## 4. Module Composition Patterns
+
+### Exports Object Pattern
+```javascript
+exports.sayHello = (name) => {
+  Ti.API.info(`Hello ${name}`)
+}
+
+exports.version = 1.4
+```
+
+### Constructor Pattern (module.exports)
+```javascript
+class Person {
+  constructor(firstName, lastName) {
+    this.firstName = firstName
+    this.lastName = lastName
+  }
+
+  fullName() {
+    return `${this.firstName} ${this.lastName}`
+  }
+}
+
+module.exports = Person
+```
+
+## 5. Antipatterns to Avoid
+
+### Don't Assign Directly to exports
+```javascript
+// ❌ WRONG - won't work
+function Person() {}
+exports = Person
+
+// ✅ CORRECT
+module.exports = Person
+```
+
+### Don't Mix module.exports and exports.*
+```javascript
+// ❌ DISCOURAGED
+module.exports = Person
+exports.foo = 'bar'
+
+// ✅ Use one consistently
+```
+
+### No Global Variables Across Modules
+Any data a module needs must be passed during construction or initialization. Never rely on globals shared across modules.
+
+## 6. Security and Scope
+
+All modules have private scope. Variables declared within the module are private unless added to `exports`.
+
+```javascript
+const _privateVar = 'secret' // Not accessible outside
+
+exports.publicMethod = () => {
+  // Can access _privateVar
+  return _privateVar
+}
+```
+
+## 7. Node.js Compatibility
+
+Titanium supports Node.js module patterns and `require()` resolution. Node.js modules can often be used directly.
+
+For detailed Node.js support information, refer to the official Titanium Node.js guide.