@maccesar/titools 5.2.5 → 5.4.0

package/skills/alloy-howtos/references/cli_reference.md

@@ -1,230 +1,25 @@
-# Alloy command-line interface reference
+# Alloy CLI workflow in the current guides
 
-The Alloy CLI manages and builds Alloy projects.
+Install Alloy separately with `npm install -g alloy`. The Titanium CLI and platform toolchain must already work; run `ti info` before creating or building the app.
 
-## Installation
+| Task | Command |
+| --- | --- |
+| Create an app and convert it to Alloy | `ti create --type app --alloy --name Hello --id com.example.hello --platforms android,ios --workspace-dir .` |
+| Convert an existing Classic app | `alloy new` from its project root |
+| Generate a reusable widget | `alloy generate widget com.example.rating` |
+| Build and run on Android | `ti build --platform android` |
+| Build and run on iOS | `ti build --platform ios` |
+| Compile without installing/launching | Add `--build-only` |
+| Reload JavaScript on save | Add `--liveview` |
+| Select real hardware | Add `--target device` |
+| Select one device | Add `--device-id <id>` |
 
-The Alloy CLI is installed when you install the `alloy` package.
+Without Alloy on `PATH`, `ti create --alloy` leaves a Classic project and reports what to install. `ti create` without arguments prompts; noninteractive use needs the creation values shown above, including `--type` and `--workspace-dir`.
 
-### Manual Installation
+Use `ios` for iPhone and iPad; `iphone` selects iPhone only. A new app ID after publication creates a separate store listing. Default build targets are Android emulator and iOS simulator, with prompts when more than one device is available. iOS builds require macOS and Xcode.
 
-Install Node.js from [nodejs.org](http://nodejs.org/#download) first, then:
+The current guides do not provide a complete Alloy command/options catalog. Use the installed released CLI's `alloy --help` / `alloy <command> --help` when an unlisted operation is required, and verify its behavior rather than importing an archived recipe.
 
-```bash
-sudo npm install -g alloy
-```
+See [creating and running an app](../../alloy-guides/references/CLI_TASKS.md) for prerequisites and device signing, and [debugging](./debugging_troubleshooting.md) for LiveView limitations.
 
-For a specific version:
-```bash
-sudo npm install -g alloy@1.10.0
-```
-
-### Development install
-
-```bash
-git clone https://github.com/tidev/alloy.git
-cd alloy
-[sudo] npm install -g .
-```
-
-## Commands
-
-### new
-
-Creates a new Alloy project on top of an existing Titanium project (create the classic Titanium project first, then run this command from inside the project directory).
-
-```bash
-alloy new [<project_path>] [<project_template>] [--force] [--no-colors]
-```
-
-| Option               | Description                                                                       |
-| -------------------- | --------------------------------------------------------------------------------- |
-| `<project_path>`     | Path to skeleton Titanium project (default: current directory)                    |
-| `<project_template>` | **default** (single pane) or **two_tabbed** (tabbed app)                          |
-| `--testapp <path>`   | Relative path to a test application in the Alloy GitHub repo (under `test/apps/`) |
-| `-f, --force`        | Force execution                                                                   |
-| `-n, --no-colors`    | Disable color output                                                              |
-
-### generate
-
-Creates skeleton Alloy components.
-
-```bash
-alloy generate <component> [--widgetname <widget_name>] [--outputPath <output_path>] [--platform <platform>] [--force] [--no-colors]
-```
-
-| Component                         | Description                                                                                                                                                                 |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `controller <name>`               | Create controller, view and style                                                                                                                                           |
-| `jmk`                             | Create `alloy.jmk`                                                                                                                                                          |
-| `model <name> <adapter> [schema]` | Create model (see Model Format below)                                                                                                                                       |
-| `migration <model_name>`          | Create migration file                                                                                                                                                       |
-| `style <name>` or `--all`         | Create style file (or all styles). If name matches a view-controller, it populates using IDs/classes from markup. Running again updates existing files with new attributes. |
-| `view <name>`                     | Create view and style                                                                                                                                                       |
-| `widget <name>`                   | Create widget                                                                                                                                                               |
-
-| Option                    | Description                                      |
-| ------------------------- | ------------------------------------------------ |
-| `--widgetname <name>`     | Create component for specified widget            |
-| `-o, --outputPath <path>` | Output path (point to 'app' directory)           |
-| `--platform <platform>`   | Create platform-specific component (android/ios) |
-| `-f, --force`             | Force execution                                  |
-| `-n, --no-colors`         | Disable color output                             |
-
-#### Model format
-
-Select adapter type:
-- `sql` - SQLite database for Android/iOS (also generates a migration file)
-- `properties` - Local storage in Titanium SDK context
-
-Schema format: space-delimited list of `field:type`
-- Example: `name:string age:number sex:varchar dob:date`
-
-SQLite type mapping:
-
-| Datatype                                 | SQLite Type |
-| ---------------------------------------- | ----------- |
-| string, varchar, text                    | TEXT        |
-| int, tinyint, smallint, bigint, integer  | INTEGER     |
-| double, float, real                      | REAL        |
-| blob                                     | BLOB        |
-| decimal, number, date, datetime, boolean | NUMERIC     |
-| null                                     | NULL        |
-| unknown                                  | TEXT        |
-
-### install
-
-Installs special Alloy project components.
-
-```bash
-alloy install <module> [<project_path>]
-```
-
-| Module           | Description                               |
-| ---------------- | ----------------------------------------- |
-| `plugin`         | Install compiler plugin for Studio        |
-| `<project_path>` | Project path (default: current directory) |
-
-### compile
-
-Compiles Alloy code to Titanium SDK code.
-
-```bash
-alloy compile [<project_path>] [--config <compiler_options>] [--no-colors]
-```
-
-| Option                   | Description                                                               |
-| ------------------------ | ------------------------------------------------------------------------- |
-| `<project_path>`         | Project path (default: current directory)                                 |
-| `-c, --config <options>` | Comma-delimited compiler options (e.g., `beautify=false,deploytype=test`) |
-| `-n, --no-colors`        | Disable color output                                                      |
-
-Compiler options reference the `event.alloyConfig` object in [Build Configuration File (alloy.jmk)](config_files.md).
-
-### run
-
-Use `titanium build` command to run Alloy projects. See [Titanium Command-Line Interface Reference](https://titaniumsdk.com/docs/reference/cli).
-
-> **💡 Common ti build pitfalls**
->
-> Using `-C` flag without UDID:
-> ```bash
-> # Prompts for simulator selection interactively
-> ti build -p ios -T simulator -C
-> ```
->
-> Correct approach for simulator:
-> ```bash
-> # Runs on default simulator
-> ti build -p ios -T simulator
-> ```
->
-> Using `--no-prompt` incorrectly:
-> ```bash
-> # Still may prompt for device selection if not specific
-> ti build -p ios --no-prompt
-> ```
->
-> Always specify target:
-> ```bash
-> # Clear target specification
-> ti build -p ios -T simulator --no-prompt
-> ```
->
-> **Common patterns:**
-> ```bash
-> # iOS Simulator (most common during development)
-> ti build -p ios -T simulator
->
-> # iOS Device (requires UDID)
-> ti build -p ios -T device -V <udid>
->
-> # Android Emulator
-> ti build -p android -T emulator
->
-> # Build only (don't run)
-> ti build -p ios -T simulator --build-only
-> ```
-
-### i18n-extract
-
-Extracts i18n keys from TSS and JS files to strings.xml.
-
-```bash
-alloy extract-i18n [<language>] [--apply]
-```
-
-| Option       | Description                                |
-| ------------ | ------------------------------------------ |
-| `<language>` | Two-letter language code (default: **en**) |
-| `--apply`    | Write to strings.xml (preview if absent)   |
-
-Supported functions:
-- `Ti.Locale.getString()`
-- `L()`
-
-Usage examples:
-```bash
-# Preview changes for default (English)
-alloy extract-i18n
-
-# Write changes to "app/i18n/en/strings.xml"
-alloy extract-i18n --apply
-
-# Specify "es" as the language and write the changes to "app/i18n/es/strings.xml"
-alloy extract-i18n es --apply
-
-# Preview Spanish changes
-alloy extract-i18n es
-```
-
-### copy
-
-Copy a view-controller (controller, XML, TSS).
-
-```bash
-alloy copy <CONTROLLER_NAME> <COPIED_CONTROLLER_NAME>
-```
-
-### move
-
-Rename a view-controller.
-
-```bash
-alloy move <CONTROLLER_NAME> <NEW_CONTROLLER_NAME>
-```
-
-### remove
-
-Remove a view-controller.
-
-```bash
-alloy remove <CONTROLLER_NAME>
-```
-
-## Additional Options
-
-| Option          | Description           |
-| --------------- | --------------------- |
-| `-h, --help`    | Output command usage  |
-| `-v, --version` | Output version number |
+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).

package/skills/alloy-howtos/references/config_files.md

@@ -1,158 +1,75 @@
-# Alloy configuration files reference
+# Alloy configuration
 
-## Build configuration file (alloy.jmk)
+`app/config.json` holds runtime settings and compiler configuration. A generated project uses these sections:
 
-Alloy exposes hooks to customize compilation with a JS Makefile (JMK).
-
-**Location:** `app/alloy.jmk`
-
-**Example:**
-```javascript
-task('pre:compile', (event, logger) => {
-    logger.showTimestamp = true;
-    logger.info(`building project at ${event.dir.project}`);
-});
-
-task('post:compile', (event, logger) => {
-    logger.info('compile finished!');
-});
+```json
+{
+    "global": {},
+    "env:development": {},
+    "env:test": {},
+    "env:production": {},
+    "os:android": {},
+    "os:ios": {},
+    "dependencies": {},
+    "backbone": "1.4.0"
+}
 ```
 
-### Compiler tasks (event names)
-
-| Task             | When Called                                               |
-| ---------------- | --------------------------------------------------------- |
-| `pre:load`       | After project clean, before copying assets to `Resources` |
-| `pre:compile`    | Before compiler starts                                    |
-| `post:compile`   | After compiler finishes, before exit                      |
-| `compile:app.js` | After compiling `app.js`, before writing to disk          |
-
-### Event object
-
-| Property       | Type    | Description                                                                                                                                                                                                         |
-| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `adapters`     | Array   | List of adapters                                                                                                                                                                                                    |
-| `alloyConfig`  | Object  | Compiler config: `platform` (android/ios), `file` (selective compile), `deploytype` (development/test/production), `beautify` (Boolean)                                                                             |
-| `autoStyle`    | Boolean | Autostyle enabled for project                                                                                                                                                                                       |
-| `dependencies` | Object  | Value of `dependencies` key in config.json                                                                                                                                                                          |
-| `dir`          | Object  | Directory paths: `home` (app path), `project` (root path), `resources`, `resourcesAlloy`, `assets`, `config`, `controllers`, `migrations`, `models`, `styles`, `themes`, `views`, `widgets`, `builtins`, `template` |
-| `sourcemap`    | Boolean | If `true`, generates mapping files to link generated Titanium files in `Resources` back to the source files in `app` for debugging.                                                                                 |
-| `theme`        | String  | Theme name being used                                                                                                                                                                                               |
-| `code`         | String  | *(compile:app.js only)* Contents of `app.js`                                                                                                                                                                        |
-| `appJSFile`    | String  | *(compile:app.js only)* Absolute path to `app.js`                                                                                                                                                                   |
-
-### Logger object
-
-The `logger` object controls compilation log output.
-
-#### Properties
-
-| Property        | Type    | Description                                     |
-| --------------- | ------- | ----------------------------------------------- |
-| `DEBUG`         | Number  | READONLY. Output all log messages.              |
-| `INFO`          | Number  | READONLY. Output all except debug messages.     |
-| `WARN`          | Number  | READONLY. Output only warning and error.        |
-| `ERROR`         | Number  | READONLY. Output only error messages.           |
-| `NONE`          | Number  | READONLY. Disable log messages.                 |
-| `logLevel`      | Number  | Sets which log messages to output.              |
-| `showTimestamp` | Boolean | If `true`, outputs timestamp with log messages. |
-| `stripColors`   | Boolean | If `true`, suppresses color output.             |
+## Runtime values and overrides
 
-#### Methods
+```json
+{
+    "global": { "apiRoot": "https://example.com/api", "pageSize": 20 },
+    "env:production": { "apiRoot": "https://api.example.com" },
+    "os:android": { "pageSize": 10 }
+}
+```
 
-| Method               | Description                    |
-| -------------------- | ------------------------------ |
-| `debug(msg: String)` | Outputs a debug log message.   |
-| `info(msg: String)`  | Outputs an info log message.   |
-| `warn(msg: String)`  | Outputs a warning log message. |
-| `error(msg: String)` | Outputs an error log message.  |
+Read the resulting values with `Alloy.CFG.apiRoot`. The selected `env:` is the build deploy type, not its target. Simulator builds normally use `development`; `--deploy-type production` selects production.
 
----
+For conflicting keys, released Alloy 3.0.1 merges `global`, then the matching `env:`, then `os:`: the OS value wins. The current published configuration page reverses the last two in its prose. Do not rely on that wording; verify the installed compiler when a collision matters.
 
-## Global initializer (alloy.js)
+The merged configuration ships in the app and can be extracted. API roots belong here; secrets belong on a server. Compiler settings can also appear in the generated configuration: do not treat it as a secret store or assume compiler-only keys are stripped.
 
-**Location:** `app/alloy.js`
+## Compile-time constants
 
-Runs before any controllers load. Use it to set up globals and singletons.
+| Constant | True when |
+| --- | --- |
+| `OS_IOS`, `OS_ANDROID` | Building that platform |
+| `ENV_DEV`, `ENV_DEVELOPMENT` | Development deploy type |
+| `ENV_TEST` | Test deploy type |
+| `ENV_PROD`, `ENV_PRODUCTION` | Production deploy type |
+| `DIST_ADHOC` | Target `dist-adhoc` |
+| `DIST_STORE` | Target `dist-appstore` or `dist-playstore` |
 
-Common uses:
-- Creating `Alloy.Collections` (e.g., `Alloy.Collections.myModel = Alloy.createCollection('myModel');`)
-- Setting up `Alloy.Globals` (shared references, utility functions)
-- Initializing singletons (analytics, logging, network managers)
-- Configuring global event listeners
+These are compiler-provided, not entries in `config.json`. Write the platform condition explicitly so the compiler can remove the other branch:
 
-**Example:**
 ```javascript
-// app/alloy.js
-Alloy.Globals.loading = Alloy.createWidget('com.example.loading');
-Alloy.Collections.users = Alloy.createCollection('user');
-
-// Global utility
-Alloy.Globals.alert = (title, message) => {
-    Ti.UI.createAlertDialog({ title, message }).show();
-};
+if (OS_IOS) {
+    // iOS-specific implementation.
+}
 ```
 
----
-
-## Project configuration file (config.json)
+Guard or remove logging before distribution; release logging can expose interpolated private data. Do not infer a target named `dist-store` from the constant.
 
-**Location:** `app/config.json`
+## Themes, widgets and Backbone
 
-Alloy uses `config.json` for global values, environment and platform overrides, and widget dependencies.
-### Objects
+Set a build-time theme using `{ "global": { "theme": "dark" } }` and provide its directory under `app/themes/dark`. See [styles and themes](../../alloy-guides/references/VIEWS_STYLES.md#themes).
 
-| Object            | Description                                                 |
-| ----------------- | ----------------------------------------------------------- |
-| `global`          | Key-value pairs for all environments and platforms          |
-| `env:development` | Development builds (simulator/emulator)                     |
-| `env:test`        | Test builds on device                                       |
-| `env:production`  | Production builds (after package installation)              |
-| `os:android`      | Android-specific values                                     |
-| `os:ios`          | iOS-specific values                                         |
-| `dependencies`    | Widget dependencies (name: version)                         |
-| `autoStyle`       | Enable autostyle for entire project                         |
-| `backbone`        | Backbone.js version: `0.9.2` (default), `1.1.2`, or `1.3.3` |
+`dependencies` lists widget IDs and versions. Provide those widget directories under `app/widgets`; an undeclared widget is not compiled. See [widgets](../../alloy-guides/references/WIDGETS.md).
 
-**Precedence:** `os` > `env` > `global`. Combinations (for example, `os:ios env:production`) override single values.
+`backbone` pins the bundled Backbone version. The released Alloy 3.0.1 template already selects `1.4.0`; do not infer that the project needs unreleased Alloy 3.1.0 from the current model guide's attribution. Check the actual config and `alloy --version`.
 
-**Runtime access:** Values are available at runtime via `Alloy.CFG.<key>`.
+## Build hooks
 
-**Example:**
+`app/alloy.jmk` runs around compilation and can copy inputs or adjust generated output:
 
-```json
-{
-    "global": { "foo": 1 },
-    "env:development": { "foo": 2 },
-    "env:test": { "foo": 3 },
-    "env:production": { "foo": 4 },
-    "os:ios env:production": { "foo": 5 },
-    "os:ios env:development": { "foo": 6 },
-    "os:ios env:test": { "foo": 7 },
-    "os:android": { "foo": 8 },
-    "dependencies": {
-        "com.foo.widget": "1.0"
-    }
-}
+```javascript
+task('post:compile', (event, logger) => {
+    logger.info(`compiled ${event.dir.project}`);
+});
 ```
 
-Accessing values: `Ti.API.info(Alloy.CFG.foo)` on iPhone simulator returns `6`.
-
----
-
-## Widget configuration file (widget.json)
-
-**Location:** Root directory of the widget. Follows the npm `package.json` format with a few exceptions.
-### Keys
-
-| Key                    | Type   | Required | Description                           |
-| ---------------------- | ------ | -------- | ------------------------------------- |
-| `id`                   | String | Yes      | Must match widget root folder name    |
-| `copyright`            | String | No       | Copyright information                 |
-| `license`              | String | No       | License information                   |
-| `min-alloy-version`    | Float  | No*      | Minimum Alloy version required        |
-| `min-titanium-version` | Float  | No*      | Minimum Titanium version required     |
-| `tags`                 | String | No       | Comma-delimited keywords              |
-| `platforms`            | String | No*      | Supported platforms (comma-delimited) |
+Keep hooks small: they execute on each build. The current guide names `pre:load`, `post:load`, `pre:compile` and `post:compile`; released Alloy 3.0.1 implements `pre:load`, `pre:compile` and `post:compile`, but not `post:load`. Do not write a `post:load` recipe without checking support in the version actually installed.
 
-(*) Currently, `min-alloy-version`, `min-titanium-version`, and `platforms` are not strictly enforced, but Alloy will perform checks against these in future versions.
+Sources: [configuration](https://titaniumsdk.com/docs/alloy/config.md), [models](https://titaniumsdk.com/docs/alloy/models.md). The precedence, Backbone and hook caveats are verified against released Alloy 3.0.1.

package/skills/alloy-howtos/references/debugging_troubleshooting.md

@@ -1,78 +1,34 @@
-# Alloy debugging and troubleshooting
+# Debugging an Alloy application
 
-## Debugging
+First separate a compiler/native build failure from a failure in the running app.
 
-### Compiler error messages
+## Build failures
 
-The Alloy compiler reports syntax errors in JavaScript, JSON, TSS, and XML. Error messages include:
-- File path
-- Line and character position
-- Description of the error
+1. Run `ti info` and fix toolchain errors first.
+2. If generated files are stale, run `ti clean` and rebuild.
+3. Read upward to the first Gradle/Xcode error; later messages can be consequences.
+4. For linker failures, inspect native-module compatibility with the SDK through `ti-guides`.
 
-## Troubleshooting
+`Resources/` and `build/` are generated in an Alloy app. Do not repair generated output by editing it.
 
-### Error: No app.js found
+## Runtime diagnosis
 
-**Error:** `[ERROR] No app.js found. Ensure the app.js file exists in your project's Resources directory.`
+Use `Ti.API.trace`, `debug`, `info`, `warn`, `error` and `log`. `info` is the default build log level; add `--log-level warn` to reduce output or `--log-level trace` for build diagnostics. Logs ship with release builds and can expose tokens, email addresses or other interpolated private data; guard or remove them before distribution.
 
-**Solution:** If part of the contents of your `Resources` folder were deleted, run:
-```bash
-alloy compile --config platform=<platform>
-```
-
-### Android: images, HTML, and assets not displaying
-
-**Problem:** Assets display on iOS and Mobile Web but not Android.
-
-**Solution:** Android requires absolute paths. Precede asset paths with a slash ('/'). iOS and Mobile Web accept both relative and absolute paths.
+The VS Code Titanium extension provides the `titanium` debug type for breakpoints. The JetBrains integration uses Chrome DevTools Protocol and also needs `ios-webkit-debug-proxy` for iOS. Without an editor integration, use logs rather than assuming breakpoints are available.
 
-### Android runtime error: cannot call method of undefined
+For native crashes, inspect Android `adb logcat`, or macOS Console with the iOS device selected and filtered by app name. Xcode also retains device crash reports.
 
-**Error:** `Uncaught TypeError: Cannot call method xxx of undefined`
+## LiveView
 
-**Causes:**
-1. Creating an iOS-only Titanium object. Use the `platform` attribute in views to enforce platform-specific objects.
-2. Top-level UI component has an assigned ID. The controller cannot use `$.<controller_name>` to reference it; use the assigned ID instead.
-
-### Android runtime error: Alloy is not defined
-
-**Error:** `Uncaught ReferenceError: Alloy is not defined`
-
-**Cause:** Non-controller JavaScript files are not automatically wrapped by Alloy. See [best_practices.md](best_practices.md) for the safe require pattern for non-controller files.
-
-**Solution:** Require the 'alloy' module:
-```javascript
-const Alloy = require('alloy');
+```bash
+ti build --platform android --liveview
 ```
 
-### iOS application error: invalid method passed to UIModule
-
-**Error:** `invalid method (xxx) passed to UIModule (unknown file)`
-
-**Cause:** Trying to create an Android-only Titanium object.
-
-**Solution:** Use the `platform` attribute in the view to enforce platform-specific objects.
-
-### iOS application error: undefined is not an object
-
-**Error:** `undefined is not an object (evaluating $.xxx.open) (unknown file)`
-
-**Cause:** Top-level UI component has an assigned ID in XML markup.
-
-**Solution:** The controller cannot use `$.<controller_name>` to reference it; use the assigned ID instead.
-
-## Getting help
-
-Use the [TiDev Community Slack](https://slack.tidev.io/) or [GitHub Discussions](https://github.com/tidev/titanium-sdk/discussions):
-- Include 'alloy' as a tag
-- Include the Alloy version (run `alloy --version`)
-- Include platform information
+LiveView re-runs JavaScript against the installed app. Changes to `tiapp.xml`, modules, native dependencies or `app/platform/` require a real build. Check this when a saved change appears ineffective.
 
-## Submitting a bug report
+## Profiling
 
-Search [existing issues](https://github.com/tidev/alloy/issues) first to avoid duplicates. If none match, create a new issue:
-- Select 'Alloy' as the component
-- Include Alloy version (`alloy --version`)
-- Include environment information
+Use Android Studio Profiler on a debug build or Xcode Instruments on iOS. Allocations and Leaks help investigate memory growth. Native frames may show JavaScript work as bridge time rather than a precise source line. For list performance, inspect row/template work and use the current lists guidance through `ti-ui`.
 
-For detailed instructions, see [How to Report a Bug or Make a Feature Request](https://titaniumsdk.com/contribute).
+Source: [debugging and profiling](https://titaniumsdk.com/docs/build/debugging.md).