@maccesar/titools 5.2.5 → 5.4.0

package/skills/alloy-guides/SKILL.md

@@ -1,188 +1,27 @@
 ---
 name: alloy-guides
-description: 'Use when working with Alloy MVC projects: writing or reviewing Alloy controllers (`app/controllers/`), XML views (`app/views/`), TSS styles (`app/styles/`), Backbone models and collections (`app/models/`), sync adapters, migrations, widgets, or the Alloy compilation flow. Triggers include the `app/views/` + `app/controllers/` + `app/styles/` folder structure, or `app/models/` for data work. Alloy XML is not HTML; TSS is not CSS; controllers follow Alloy-specific patterns, not web MVC.'
+description: Use when writing or reviewing Titanium Alloy XML views, TSS styles, controllers, models and collections, persistent list binding, widgets or build-time themes. Applies to app/views, app/styles, app/controllers and app/models. Uses the current official Titanium guides; Alloy is a compiler over the Titanium API, not web MVC.
 ---
 
-# alloy-guides
+# Alloy guides
 
-## Overview
+Use this skill for Alloy screen structure, styling, controller lifecycle, persistent data and reusable widgets. Load the relevant reference before writing code.
 
-Reference for the Alloy MVC framework on top of Titanium SDK. Covers core concepts, controllers, models / collections / data binding, XML markup, TSS styling (static and dynamic), widgets, and the compile pipeline.
+| Task | Reference |
+| --- | --- |
+| MVC, project directories and generated output | [Concepts](references/CONCEPTS.md) |
+| Arguments, opening windows, shared modules and cleanup | [Controllers](references/CONTROLLERS.md) |
+| Model definition, ListView binding, filters and transforms | [Models](references/MODELS.md) |
+| Persistence choices and schema migrations | [Persistence](references/MODELS_ADVANCED.md) |
+| XML, IDs, namespaces, conditional elements and composition | [Views](references/VIEWS_XML.md) |
+| TSS selectors, precedence, queries and build-time themes | [Styles](references/VIEWS_STYLES.md) |
+| Runtime class changes and their required class tracking | [Dynamic styles](references/VIEWS_DYNAMIC.md) |
+| Creating, declaring, using and isolating widgets | [Widgets](references/WIDGETS.md) |
+| Creating, converting and running an Alloy app | [App workflow](references/CLI_TASKS.md) |
+| PurgeTSS integration, with its independent source | [PurgeTSS](references/PURGETSS.md) |
 
-## When to use
+Keep XML, TSS and JavaScript in their corresponding `app` directories. `Resources/` and `build/` are generated; do not edit or commit them. A controller creates its views but does not automatically open a Window. Read `$.args` at the top, export deliberate operations and clean up listeners/subscriptions separately from `$.destroy()`.
 
-Use this skill when:
+For configuration, compiler constants, hooks and debugging use `alloy-howtos`. For API signatures and platform availability use `ti-api`. Use `ti-guides` for toolchain, native modules and distribution, `ti-howtos` for service setup, and `ti-ui` for current Titanium layout and list behavior.
 
-- The project contains `app/views/`, `app/controllers/`, `app/styles/`, or `app/models/`
-- Writing or reviewing Alloy XML markup (`<Alloy>`, `<Window>`, `<View>`, ...)
-- Writing or reviewing TSS styles (static and conditional/dynamic)
-- Defining Backbone models/collections, data binding, or sync adapters
-- Creating, consuming, or packaging widgets
-- Understanding the Alloy compilation pipeline (`alloy.jmk`, code generation)
-- Diagnosing TSS, XML, or model schema issues
-
-Do NOT use for:
-
-- Alloy CLI usage and configuration files (use `alloy-howtos`)
-- Titanium SDK fundamentals, `tiapp.xml`, distribution (use `ti-guides`)
-- Looking up Titanium API surfaces (use `ti-api`)
-- Native module dependency updates (use `ti-module-update`)
-
-## Quick reference
-
-| Topic | Reference |
-|---|---|
-| Core concepts, MVC, Backbone.js, conventions | [CONCEPTS.md](references/CONCEPTS.md) |
-| Controllers, events, conditional code, arguments | [CONTROLLERS.md](references/CONTROLLERS.md) |
-| Models, collections, data binding | [MODELS.md](references/MODELS.md) |
-| Sync adapters, migrations, plain Backbone, Backbone version migration | [MODELS_ADVANCED.md](references/MODELS_ADVANCED.md) |
-| XML markup, elements, attributes, events | [VIEWS_XML.md](references/VIEWS_XML.md) |
-| TSS styling, themes, platform-specific styles | [VIEWS_STYLES.md](references/VIEWS_STYLES.md) |
-| Dynamic styles, autostyle, runtime styling | [VIEWS_DYNAMIC.md](references/VIEWS_DYNAMIC.md) |
-| Controllers-less views, patterns | [VIEWS_WITHOUT_CONTROLLERS.md](references/VIEWS_WITHOUT_CONTROLLERS.md) |
-| Creating and using widgets | [WIDGETS.md](references/WIDGETS.md) |
-| CLI commands, code generation | [CLI_TASKS.md](references/CLI_TASKS.md) |
-| PurgeTSS integration (optional addon) | [PURGETSS.md](references/PURGETSS.md) |
-
-## Project structure
-
-Standard Alloy project layout:
-
-```
-app/
-├── alloy.js              # Initializer file
-├── alloy.jmk             # Build configuration
-├── config.json           # Project configuration
-├── assets/               # Images, fonts, files (→ Resources/)
-├── controllers/          # Controller files (.js)
-├── i18n/                 # Localization strings (→ i18n/)
-├── lib/                  # CommonJS modules
-├── migrations/           # DB migrations (<DATETIME>_<name>.js)
-├── models/               # Model definitions (.js)
-├── platform/             # Platform-specific resources (→ platform/)
-├── specs/                # Test-only files (dev/test only)
-├── styles/               # TSS files (.tss)
-├── themes/               # Theme folders
-├── views/                # XML markup files (.xml)
-└── widgets/              # Widget components
-```
-
-## MVC quick start
-
-**Controller** (`app/controllers/index.js`)
-```javascript
-function doClick (e) {
-    alert($.label.text);
-}
-$.index.open();
-```
-
-**View** (`app/views/index.xml`)
-```xml
-<Alloy>
-    <Window class="container">
-        <Label id="label" onClick="doClick">Hello, World</Label>
-    </Window>
-</Alloy>
-```
-
-**Style** (`app/styles/index.tss`)
-```javascript
-'.container': { backgroundColor: 'white' }
-'Label': { color: '#000' }
-```
-
-## Key concepts
-
-- **Models / Collections** — Backbone.js objects with sync adapters (`sql`, `properties`)
-- **Views** — XML markup with TSS styling
-- **Controllers** — JavaScript logic with `$` reference to view components
-- **Data Binding** — Bind collections to UI components automatically
-- **Widgets** — Reusable components with their own MVC structure
-- **Conventions** — File naming and placement drive code generation
-
-## Critical rules
-
-### Platform-specific properties in TSS
-
-> **Warning: Platform-specific properties require modifiers**
->
-> Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS without platform modifiers causes cross-platform compilation failures.
->
-> ```tss
-> // WRONG — adds Ti.UI.iOS to Android project
-> '#mainWindow': {
->     statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android
-> }
->
-> // CORRECT — only adds to iOS
-> '#mainWindow[platform=ios]': {
->     statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-> }
->
-> // CORRECT — only adds to Android
-> '#mainWindow[platform=android]': {
->     actionBar: { displayHomeAsUp: true }
-> }
-> ```
->
-> Properties that always require platform modifiers:
->
-> - **iOS:** `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, anything under `Ti.UI.iOS.*`
-> - **Android:** `actionBar` config, anything under `Ti.UI.Android.*`
->
-> Available modifiers: `[platform=ios]`, `[platform=android]`, `[formFactor=handheld]`, `[formFactor=tablet]`, `[if=Alloy.Globals.<expression>]`
->
-> See [VIEWS_DYNAMIC.md](references/VIEWS_DYNAMIC.md) for the full set of conditional / platform modifier patterns.
-
-## Common patterns
-
-### Creating a model
-
-```bash
-alloy generate model book sql title:string author:string
-```
-
-### Data binding
-
-```xml
-<Collection src="book" />
-<TableView dataCollection="book">
-    <TableViewRow title="{title}" />
-</TableView>
-```
-
-### Platform-specific code
-
-```javascript
-if (OS_IOS) {
-    // iOS-only code
-}
-if (OS_ANDROID) {
-    // Android-only code
-}
-```
-
-### Widget usage
-
-```xml
-<Widget src="mywidget" id="foo" />
-```
-
-## Compilation process
-
-1. **Cleanup** — `Resources` folder cleaned
-2. **Build config** — `alloy.jmk` loaded (`pre:load` task)
-3. **Framework files** — Backbone.js, Underscore.js, sync adapters copied
-4. **MVC generation** — Models, widgets, views, controllers compiled to JS
-5. **Main app** — `app.js` generated from template
-6. **Optimization** — UglifyJS optimization, platform-specific code removal
-
-## Related skills
-
-| Task | Use this skill |
-|---|---|
-| Alloy CLI, `alloy.jmk`, `config.json`, debugging compilation | `alloy-howtos` |
-| Titanium SDK config, Hyperloop, app distribution | `ti-guides` |
-| Titanium API lookup (Ti.UI, Ti.Network, modules) | `ti-api` |
-| Native module dependency updates | `ti-module-update` |
+The current guide pages are at [titaniumsdk.com/docs/alloy.md](https://titaniumsdk.com/docs/alloy.md). References include released-compiler caveats where a published recipe conflicts with released behavior. PurgeTSS keeps its own source and is outside the official Alloy guide refresh.

package/skills/alloy-guides/references/CLI_TASKS.md

@@ -1,233 +1,34 @@
-# Alloy Tasks with the CLI
+# Create and run an Alloy app
 
-Alloy provides command-line interface (CLI) tasks to create a new project, generate skeleton components such as controllers and models, and compile the source files into the Titanium project.
-
-## Creating a New Application
-
-> **Recommended:** Use `ti create --alloy` to create a new Alloy project in one step.
-
-```bash
-ti create -t app --alloy --id com.example.myapp -n MyApp -p android,ios
-```
-
-This creates a complete Alloy project structure with the `app` folder containing controllers, views, styles, models, and migrations.
-
-**Alternative (interactive):**
-```bash
-ti create
-```
-
-You will be prompted to enter an application name and application ID. When prompted for project type, select **Alloy**.
-
-**Legacy method (not recommended):**
-```bash
-ti create
-cd PROJECTDIRECTORY
-alloy new
-```
-
-This two-step approach is discouraged in favor of using `--alloy` directly.
-
-## Creating a New Application Using a Test Application
-
-You can generate a new Alloy project using a test application from the Alloy Github repo.
+Check the toolchain with `ti info` and finish environment setup before diagnosing a failed build as an Alloy problem.
 
 ```bash
-ti create -t app --classic -i com.appc.picker -n AlloyPicker
-cd AlloyPicker
-alloy new --testapp ui/picker
+npm install -g alloy
+ti create --type app --alloy --name Hello --id com.example.hello --platforms android,ios --workspace-dir .
+cd Hello
+ti build --platform android
 ```
 
-## Generating Components
-
-The CLI can generate skeleton controllers (with views and styles), models, database migrations and widgets.
+Use a reverse-DNS app ID from a domain you control: changing it after publication means a new listing in both stores. `--name` chooses the directory and icon label. `ios` selects iPhone and iPad; `iphone` selects iPhone only. In noninteractive creation, supply `--type` and `--workspace-dir` as shown; `ti create` without arguments prompts.
 
-### Generating a Controller
+`--alloy` invokes `alloy new` after creating the project. Alloy must be on `PATH`; otherwise the project remains Classic and the CLI reports what to install. To convert an existing Classic project, run `alloy new` in its root.
 
-To generate a controller with a style and view:
+## Build and iterate
 
 ```bash
-alloy generate controller <name> [--widgetname <widget_name>] [-o path_to_project/app] [--platform <platform>]
+ti build --platform ios
+ti build --platform android --build-only
+ti build --platform android --liveview
 ```
 
-This creates `app/controllers/<name>.js`, `app/styles/<name>.tss`, and `app/views/<name>.xml`.
-
-### Generating a View
-
-To generate a view and style **without** a controller:
-
-```bash
-alloy generate view <name> [--widgetname <widget_name>] [-o path_to_project/app] [--platform <platform>]
-```
-
-This creates `app/styles/<name>.tss` and `app/views/<name>.xml`.
-
-### Generating a Style
-
-To generate a style for a view-controller:
-
-```bash
-alloy generate style <name> [--widgetname <widget_name>]
-```
-
-Alloy uses the id and attribute names in the markup file to populate the skeleton style file. This creates `app/styles/<name>.tss`. If you add new `id` or `class` attributes to the markup file, running either of these commands updates the style file with the new attributes.
-
-To generate style files for all view-controllers:
-
-```bash
-alloy generate style --all
-```
-
-### Generating a Model
-
-To generate a model:
-
-```bash
-alloy generate model <name> <adapter> [<col_name_1>:<col_type_1> <col_name_2>:<col_type_2> ...] [-o path_to_project/app]
-```
-
-The fourth parameter selects the adapter type: `sql` for SQLite or `properties` for local storage. The fifth parameter defines the table schema. This is required for `sql` and `properties` adapter types.
-
-This creates `app/models/<name>.js`, and `app/migrations/DATETIME_<name>.js` if the adapter type is 'sql'.
-
-### Generating a Migration
-
-To generate a standalone migration for a specific model:
-
-```bash
-alloy generate migration <name> [-o path_to_project/app]
-```
-
-This creates `app/migrations/DATETIME_<name>.js`.
-
-### Generating a Widget
-
-To generate a basic widget:
-
-```bash
-alloy generate widget <name> [-o path_to_project/app]
-```
-
-This creates `app/widgets/<name>/widget.json`, `app/widgets/<name>/controllers/widget.js`, `app/widgets/<name>/styles/widget.tss`, and `app/widgets/<name>/views/widget.xml`. The widget is automatically added to `config.json`.
-
-### Generating alloy.jmk
-
-To generate the build customization file:
-
-```bash
-alloy generate jmk [-o path_to_project/app]
-```
-
-This creates `app/alloy.jmk` with a few task hooks in place.
-
-## Extracting Localization Strings
-
-The `alloy extract-i18n` command inspects your JS, TSS and XML files (since Alloy 1.6.0) for instances of Titanium's localization functions and adds those strings to an i18n strings.xml file.
-
-```bash
-alloy extract-i18n [language] [--apply]
-```
-
-**Parameters**:
-
-* `language` – Optional. Two-letter language code (`en`, `es`, etc.). Default is `en`.
-* `--apply` – Optional. Writes new entries to `strings.xml`. Without it, displays a preview. This is a safe operation: it only adds new entries and never removes existing ones.
-
-Supported functions:
-
-* `Titanium.Locale.getString()`
-* `Ti.Locale.getString()`
-* `L()`
-
-**Example**:
-
-```javascript
-// In JavaScript/TSS
-const name = Ti.Locale.getString('name');
-const color = Titanium.Locale.getString('color');
-const currency = L('currency');
-```
-
-```xml
-<!-- In XML (since Alloy 1.6.0) -->
-<Label textid="greeting" />
-<Button titleid="submit_button" />
-```
-
-**Preview Output** (without --apply):
-
-```
-[INFO] ######## BEFORE ########
-[INFO] <?xml version="1.0" encoding="UTF-8"?>
-[INFO] <resources>
-[INFO] </resources>
-[INFO]
-[INFO] ######## AFTER ########
-[INFO] <?xml version="1.0" encoding="UTF-8"?>
-[INFO] <resources>
-[INFO]     <string name="name">name</string>
-[INFO]     <string name="color">color</string>
-[INFO]     <string name="currency">currency</string>
-[INFO]     <string name="greeting">greeting</string>
-[INFO]     <string name="submit_button">submit_button</string>
-[INFO] </resources>
-```
-
-Running with `--apply`:
-
-```bash
-alloy extract-i18n --apply
-```
-
-Generates `app/i18n/en/strings.xml`.
-
-To generate strings for another language, pass the language code:
-
-```bash
-alloy extract-i18n es --apply
-```
-
-This generates `app/i18n/es/strings.xml`.
-
-```xml
-<resources>
-  <string name="name">name</string>
-  <string name="color">color</string>
-  <string name="currency">currency</string>
-  <string name="greeting">greeting</string>
-  <string name="submit_button">submit_button</string>
-</resources>
-```
-
-## Compiling a Specific View-Controller
-
-To select which Alloy view-controller to compile to Titanium code:
-
-```bash
-alloy compile --config platform=<platform>,file=<file>
-
-## Example
-alloy compile --config platform=android,file=app/controller/index.js
-```
-
-## Building an Application
-
-To build and run an application:
-
-```bash
-ti build --platform <platform> [--project-dir <value>] [--sdk <value>] [<platform_build_options>]
-```
-
-Running this from the root directory of the project compiles the files to the correct location automatically.
-
-## Installing Special Project Components
+Default targets are Android emulator and iOS simulator. With several available devices, the CLI prompts; use `--device-id` to choose explicitly. iOS builds require macOS and Xcode. Initial native builds are slower than incremental builds. A successful build reports `Project built successfully`; terminal logs continue until Ctrl-C. `--build-only` skips installation and launch; LiveView reloads JavaScript on save.
 
-### Installing the Compiler Plugin
+For real devices, use `--target device`. Android needs developer options, USB debugging and USB authorization; check `ti info -t android`. iOS needs a development certificate and a matching provisioning profile containing the device; connect, unlock and trust the Mac. Select a UDID from `ti info -t ios` with `--device-id`. Use `ti-guides` for full setup and signing.
 
-To install the compiler plugin that hooks the Alloy project to Studio:
+To generate the widget described by the current guide:
 
 ```bash
-alloy install plugin [path_to_project]
+alloy generate widget com.example.rating
 ```
 
-Use this command to update the compiler plugin if your project was created using an older version of Alloy.
+Sources: [first app](https://titaniumsdk.com/docs/build/first-app.md), [Alloy](https://titaniumsdk.com/docs/alloy.md), [widgets](https://titaniumsdk.com/docs/alloy/widgets.md).