@maccesar/titools 2.2.11 → 2.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.2.11",
+  "version": "2.2.12",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/ti-expert/SKILL.md

@@ -38,78 +38,39 @@ Behavior:
 5. Quality: testing, error handling, logging, performance
 6. Cleanup: implement a `cleanup()` pattern for memory management
 
-## Organization policy (low freedom)
-
-- Use technical-type organization in `lib` (for example: `api`, `services`, `actions`, `repositories`, `helpers`, `policies`, `providers`).
-- Keep `lib` flat and predictable: `lib/<type>/<file>.js` only.
-- Do not recommend deep nesting like `lib/services/auth/session/login.js`.
-- Keep UI layers aligned by screen (`controllers/`, `views/`, `styles/`) and avoid unnecessary depth.
-
-## Quick start example
-
-Minimal example that matches the conventions:
-
-View (`views/userCard.xml`)
-```xml
-<Alloy>
-  <View id="cardContainer">
-    <View id="headerRow">
-      <ImageView id="userIcon" image="/images/user.png" />
-      <Label id="name" />
-    </View>
-    <Button id="viewProfileBtn"
-      title="L('view_profile')"
-      onClick="onViewProfile"
-    />
-  </View>
-</Alloy>
-```
-
-Styles (`styles/userCard.tss`)
-```tss
-"#cardContainer": { left: 8, right: 8, top: 8, height: Ti.UI.SIZE, borderRadius: 12, backgroundColor: '#fff' }
-"#headerRow": { layout: 'horizontal', left: 12, right: 12, top: 12, height: Ti.UI.SIZE, width: Ti.UI.FILL }
-"#userIcon": { width: 32, height: 32 }
-"#name": { left: 12, font: { fontSize: 18, fontWeight: 'bold' } }
-"#viewProfileBtn": { left: 12, right: 12, bottom: 12, height: 40, width: Ti.UI.FILL, borderRadius: 6, backgroundColor: '#2563eb', color: '#fff' }
-```
+## Architectural Maturity Tiers
 
-Controller (`controllers/userCard.js`)
-```javascript
-const { Navigation } = require('services/navigation')
+Choose the appropriate tier based on project complexity:
 
-function init() {
-  const user = $.args.user
-  $.name.text = user.name
-}
+### Tier 1: Basic (Rapid Prototyping)
+- **Best for**: Simple utility apps or developers transitioning from Classic.
+- **Structure**: Logic resides directly within `index.js`.
+- **UI Access**: Direct usage of the `$` object throughout the file.
+- **Pros**: Zero boilerplate, extremely fast start.
+- **Cons**: Unmaintainable beyond 500 lines of code.
 
-function onViewProfile() {
-  Navigation.open('userProfile', { userId: $.args.user.id })
-}
+### Tier 2: Intermediate (Modular Alloy)
+- **Best for**: Standard commercial applications.
+- **Structure**: Business logic extracted to `app/lib/` using a flat technical-type organization.
+- **Pattern**: Slim Controllers that `require()` services.
+- **Memory**: Mandatory implementation of `$.cleanup = cleanup`.
 
-function cleanup() {
-  $.destroy()
-}
+### Tier 3: Advanced / Enterprise (Service-Oriented)
+- **Best for**: High-complexity apps (IDEs like TiDesigner, multi-state platforms).
+- **Architecture**: Dependency Injection via a `ServiceRegistry`.
+- **ID Scoping**: Services do not receive the entire `$` object. They receive a "Scoped UI" object containing only relevant IDs.
+- **Cognitive Load**: "Black Box" logic—encapsulated units that reduce mental fatigue.
+- **Observability**: Structured logging with a mandatory `service` context.
 
-$.cleanup = cleanup
-```
+Detailed examples and full implementation samples are available in: [Architectural Tiers Detail](references/architecture-tiers.md)
 
-Service (`lib/services/navigation.js`)
-```javascript
-exports.Navigation = {
-  open(route, params = {}) {
-    const controller = Alloy.createController(route, params)
-    const view = controller.getView()
+## Organization policy (low freedom)
 
-    view.addEventListener('close', function() {
-      if (controller.cleanup) controller.cleanup()
-    })
+- Use technical-type organization in `lib` (for example: `api`, `services`, `actions`, `repositories`, `helpers`, `policies`, `providers`).
+- Keep `lib` flat and predictable: `lib/<type>/<file>.js` only.
+- Do not recommend deep nesting like `lib/services/auth/session/login.js`.
+- Keep UI layers aligned by screen (`controllers/`, `views/`, `styles/`) and avoid unnecessary depth.
 
-    view.open()
-    return controller
-  }
-}
-```
 
 ## Code standards (low freedom)
 
@@ -166,41 +127,47 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 
 | Question                           | Answer                                                         |
 | ---------------------------------- | -------------------------------------------------------------- |
-| How to create a new Alloy project? | `ti create -t app --alloy` (not `--classic` + `alloy new`)      |
+| How to create a new Alloy project? | `ti create -t app --alloy` (not `--classic` + `alloy new`)     |
 | Fastest way to build?              | `tn <recipe>` (using TiNy CLI wrapper)                         |
+| Controller > 100 lines?            | Extract to Tier 2 (Services)                                   |
+| More than 50 IDs in XML?           | Use Tier 3 (ID Scoping)                                        |
 | Where does API call go?            | `lib/api/`                                                     |
 | Where does business logic go?      | `lib/services/`                                                |
-| How deep should `lib` folders be?  | One level: `lib/<type>/<file>.js`                             |
+| How deep should `lib` folders be?  | One level: `lib/<type>/<file>.js`                              |
 | Where do I store auth tokens?      | Keychain (iOS) / KeyStore (Android) via service                |
 | Models or Collections?             | Collections for API data, Models for SQLite persistence        |
 | Ti.App.fireEvent or EventBus?      | Always EventBus (Backbone.Events)                              |
 | Direct navigation or service?      | Always Navigation service (auto cleanup)                       |
-| Inline styles or TSS files?        | Always TSS files (per-controller + `app.tss` for global)        |
-| Controller 100+ lines?             | Extract logic to services                                      |
+| Inline styles or TSS files?        | Always TSS files (per-controller + `app.tss` for global)       |
 
 ## Reference guides (progressive disclosure)
 
-Architecture
-- [CLI expert and TiNy](references/cli-expert.md): advanced build workflows, LiveView, TiNy (`tn`) recipes
-- [Structure and organization](references/alloy-structure.md): models vs collections, folder maps, widget patterns, automatic cleanup
-- [Alloy builtins and globals](references/alloy-builtins.md): `OS_IOS`/`OS_ANDROID`, `Alloy.CFG`, `Alloy.Globals`, `$.args`, compiler directives
-- [ControllerAutoCleanup.js](assets/ControllerAutoCleanup.js): drop-in utility for automatic controller cleanup
-- [Architectural patterns](references/patterns.md): repository, service layer, event bus, factory, singleton
-- [Contracts and communication](references/contracts.md): layer interaction examples and JSDoc specs
-- [Anti-patterns](references/anti-patterns.md): fat controllers, memory leaks, inline styling, direct API calls
-
-Implementation
-- [Code conventions](references/code-conventions.md): ES6 features, TSS design system, accessibility
-- [Theming and dark mode](references/theming.md): theme system, Alloy.Globals palette, runtime switching, design tokens
-- [Controller patterns](references/controller-patterns.md): templates, animation, dynamic styling
-- [Examples](references/examples.md): API clients, SQL models, full screen examples
-
-Quality and reliability
-- [Unit and integration testing](references/testing-unit.md): unit testing, mocking patterns, controller testing, test helpers
-- [E2E testing and CI/CD](references/testing-e2e-ci.md): Appium, WebdriverIO, GitHub Actions, Fastlane
-- [Error handling and logging](references/error-handling.md): AppError classes, Logger service, validation
-
-Performance and security
-- [ListView and ScrollView performance](references/performance-listview.md): ListView templates, data binding, image caching, ScrollView optimization
-- [Performance optimization](references/performance-optimization.md): bridge crossings, memory management, animations, debounce/throttle, database
-- [Security fundamentals](references/security-fundamentals.md): token storage, certificate pinning, encryption, HTTPS, OWASP
+### Architecture & Patterns
+- [Architectural Tiers Detail](references/architecture-tiers.md)
+- [Architectural Patterns](references/patterns.md) (Factory, Singleton, Repository)
+- [Structure & Organization](references/alloy-structure.md)
+- [Contracts & Communication](references/contracts.md)
+- [State Management](references/state-management.md)
+- [Anti-patterns to Avoid](references/anti-patterns.md)
+
+### Implementation & API
+- [Alloy Builtins & Globals](references/alloy-builtins.md)
+- [Code Conventions](references/code-conventions.md)
+- [Controller Patterns](references/controller-patterns.md)
+- [Theming & Dark Mode](references/theming.md)
+- [Migration Patterns](references/migration-patterns.md)
+- [Examples Collection](references/examples.md)
+
+### Quality & Performance
+- [Performance Optimization](references/performance-optimization.md)
+- [ListView & ScrollView Performance](references/performance-listview.md)
+- [Error Handling & Logging](references/error-handling.md)
+- [Unit & Integration Testing](references/testing-unit.md)
+- [E2E Testing & CI/CD](references/testing-e2e-ci.md)
+
+### Security
+- [Security Fundamentals](references/security-fundamentals.md)
+- [Device Security](references/security-device.md)
+
+### Tools
+- [CLI Expert & TiNy](references/cli-expert.md)

package/skills/ti-expert/references/architecture-tiers.md

@@ -0,0 +1,248 @@
+# Titanium Architectural Maturity Tiers
+
+To ensure scalability and maintainability, Titanium projects should follow one of these three tiers based on their complexity.
+
+---
+
+# Tier 1 — Basic (Rapid Prototyping)
+
+**Best for:** Utilities, internal tools, proof of concept, learning Alloy.
+
+### Characteristics
+
+* Logic directly in `index.js`
+* Direct `$` access everywhere
+* No separation of concerns
+* No cleanup strategy
+
+### When to upgrade?
+
+* Controller > 100–150 lines
+* Logic duplicated in multiple controllers
+* UI starts feeling coupled
+
+---
+
+## Example (Tier 1)
+
+### Controller (`controllers/index.js`)
+
+```javascript
+function onButtonClick() {
+  $.label.text = "Clicked!"
+  Ti.API.info("Button was clicked")
+}
+
+$.index.open()
+```
+
+Simple. Fast. Dangerous beyond small apps.
+
+---
+
+# Tier 2 — Intermediate (Modular Alloy)
+
+**Best for:** Standard commercial applications.
+
+### Characteristics
+
+* Business logic extracted to `app/lib/`
+* Slim controllers
+* Flat organization (`lib/services`, `lib/api`)
+* Mandatory `cleanup`
+* Reusable UI components
+
+### Why this tier exists
+
+This tier separates UI from logic, but still allows services to reference global dependencies.
+
+It’s modular — but not yet decoupled.
+
+---
+
+## Example (Tier 2)
+
+### View (`views/userCard.xml`)
+
+```xml
+<Alloy>
+  <View id="cardContainer">
+    <View id="headerRow">
+      <ImageView id="userIcon" image="/images/user.png" />
+      <Label id="name" />
+    </View>
+
+    <Button id="viewProfileBtn"
+      title="View Profile"
+      onClick="onViewProfile" />
+  </View>
+</Alloy>
+```
+
+---
+
+### Controller (`controllers/userCard.js`)
+
+```javascript
+const { Navigation } = require('services/navigation')
+
+function init() {
+  const user = $.args.user
+  $.name.text = user.name
+}
+
+function onViewProfile() {
+  Navigation.open('userProfile', { userId: $.args.user.id })
+}
+
+function cleanup() {
+  $.destroy()
+}
+
+$.cleanup = cleanup
+```
+
+---
+
+### Service (`lib/services/navigation.js`)
+
+```javascript
+exports.Navigation = {
+  open(route, params = {}) {
+    const controller = Alloy.createController(route, params)
+    const view = controller.getView()
+
+    view.addEventListener('close', () => {
+      if (controller.cleanup) controller.cleanup()
+    })
+
+    view.open()
+    return controller
+  }
+}
+```
+
+---
+
+### What improves from Tier 1?
+
+* Controllers stay under control
+* Logic is reusable
+* Memory is explicitly cleaned
+* Code is easier to test
+
+But services can still depend directly on other services or globals.
+
+---
+
+# Tier 3 — Advanced / Enterprise (Service-Oriented)
+
+**Best for:** Complex applications (IDEs, platforms, multi-state apps).
+
+This is where architectural maturity changes fundamentally.
+
+---
+
+## Core Concepts
+
+### 1️⃣ Dependency Injection
+
+Services receive what they need — they don’t fetch it.
+
+### 2️⃣ Service Registry
+
+Centralized dependency wiring.
+
+### 3️⃣ ID Scoping
+
+Services receive only the UI elements they own.
+
+### 4️⃣ Encapsulation (Black Box Principle)
+
+Once a service method works, treat it as trusted.
+
+### 5️⃣ Observability
+
+All logs are structured and include service context.
+
+---
+
+## Example (Tier 3)
+
+---
+
+### Service (`lib/services/chatService.js`)
+
+```javascript
+/**
+ * @param {Object} deps
+ * @param {Object} deps.ui - Scoped UI elements
+ * @param {Object} deps.logger
+ * @param {Object} deps.designService
+ */
+module.exports = function createChatService(deps) {
+  const { ui, logger, designService } = deps
+
+  function sendMessage(text) {
+    if (!text) return
+
+    ui.sendBtn.enabled = false        // ID Scoping
+    designService.trackMessage(text)  // Inter-service communication
+
+    logger.event('message:sent', {
+      service: 'ChatService',
+      length: text.length
+    })
+  }
+
+  return {
+    sendMessage
+  }
+}
+```
+
+---
+
+### Registry (`lib/services/indexServiceRegistry.js`)
+
+```javascript
+const createChatService = require('services/chatService')
+const createDesignService = require('services/designService')
+
+module.exports = function createIndexServiceRegistry(deps) {
+  const { $, Ti, logger } = deps
+
+  // 1. Independent services
+  const designService = createDesignService({ Ti, logger })
+
+  // 2. Dependent services with scoped UI
+  const chatService = createChatService({
+    ui: {
+      sendBtn: $.sendBtn,
+      messageInput: $.messageInput
+    },
+    logger,
+    designService
+  })
+
+  return {
+    chatService,
+    designService
+  }
+}
+```
+
+---
+
+## Decision Matrix
+
+| Signal                              | Move To |
+| ----------------------------------- | ------- |
+| Controller > 100 lines              | Tier 2  |
+| Controller > 300 lines              | Tier 3  |
+| More than 50 IDs in XML             | Tier 3  |
+| Services need to talk to each other | Tier 3  |
+| Multiple application states         | Tier 3  |
+| Memory leaks appear                 | Tier 3  |
+
+---