@maccesar/titools 2.2.9 → 2.2.11

package/lib/commands/update.js

@@ -42,6 +42,49 @@ function hasAnySkillSymlink(platformSkillsDir) {
   return skillList.some((skill) => existsSync(join(platformSkillsDir, skill)));
 }
 
+/**
+ * Perform the actual update for a specific scope
+ * @param {string|undefined} baseDir - Base directory (undefined = global, path = local)
+ * @param {string} repoDir - Repository directory
+ * @param {Object} spinner - Ora spinner instance
+ * @returns {Promise<void>}
+ */
+async function performUpdate(baseDir, repoDir, spinner) {
+  // Detect platforms with existing symlinks (only update those)
+  const detectedPlatforms = detectPlatforms(baseDir);
+  const platformsWithSymlinks = detectedPlatforms.filter((p) =>
+    hasAnySkillSymlink(p.skillsDir)
+  );
+
+  // Install skills
+  spinner.start('Syncing skills...');
+  const skillsResult = await installSkills(repoDir, baseDir);
+  spinner.succeed(`${skillsResult.installed.length} skills updated`);
+
+  // Install agents (only if Claude Code has symlinks)
+  const claudePlatform = platformsWithSymlinks.find((p) => p.name === 'claude');
+  if (claudePlatform) {
+    spinner.start('Syncing agents...');
+    const agentsResult = await installAgents(repoDir, baseDir);
+    if (agentsResult.installed.length > 0) {
+      spinner.succeed('Platform agents updated');
+    } else {
+      spinner.info('No agents to sync');
+    }
+  }
+
+  cleanupLegacyArtifacts(baseDir);
+
+  // Update symlinks silently for platforms that already had them
+  for (const platform of platformsWithSymlinks) {
+    await createSkillSymlinks(
+      platform.skillsDir,
+      SKILLS,
+      baseDir
+    );
+  }
+}
+
 /**
  * Update command handler
  * @param {Object} options - Command options
@@ -65,15 +108,16 @@ export async function updateCommand(options) {
     const localPlatforms = detectPlatforms(projectDir);
     const hasLocalSkills = isProject && hasSkillsAt(projectDir);
     const hasGlobalSkills = hasSkillsAt(undefined);
-    if (hasLocalSkills && !hasGlobalSkills) {
-      baseDir = projectDir;
-    } else if (isProject && localPlatforms.length > 0) {
+
+    // Only show prompt if BOTH local and global skills exist
+    if (hasLocalSkills && hasGlobalSkills) {
       try {
         const scope = await select({
-          message: 'Local installation detected. What do you want to update:',
+          message: 'Both local and global skills detected. What do you want to update:',
           choices: [
             { name: 'Global skills (user home)', value: 'global' },
             { name: 'Local skills (current project)', value: 'local' },
+            { name: 'Both locations', value: 'both' },
           ],
           theme: {
             style: {
@@ -87,32 +131,44 @@ export async function updateCommand(options) {
           process.exit(0);
         }
         if (scope === 'local') {
-          baseDir = process.cwd();
+          baseDir = projectDir;
+        } else if (scope === 'both') {
+          baseDir = 'both';
         }
       } catch (error) {
         console.log('\nCancelled.');
         process.exit(0);
       }
+    } else if (hasLocalSkills && !hasGlobalSkills) {
+      // Only local skills exist, update local
+      baseDir = projectDir;
     }
+    // If only global skills exist, baseDir remains undefined (global)
   }
 
-  if (baseDir) {
+  // Display mode
+  if (baseDir === 'both') {
+    console.log(chalk.cyan('Mode: Updating both global and local skills'));
+  } else if (baseDir) {
     console.log(chalk.cyan('Mode: Local update (current project)'));
   } else {
     console.log(chalk.cyan('Mode: Global update (user home)'));
   }
   console.log('');
 
-  const skillsDir = getAgentsSkillsDir(baseDir);
-  const hasSkillsInstalled = skillsDir && SKILLS.some((skill) => existsSync(join(skillsDir, skill)));
-  if (!hasSkillsInstalled) {
-    console.log(chalk.yellow('No skills installed at this location.'));
-    console.log('Install them first with:');
-    console.log('  titools install');
-    console.log('');
-    console.log('Looked for skills in:');
-    console.log(`  ${baseDir ? 'Local' : 'Global'}: ${skillsDir}`);
-    return;
+  // Verify skills are installed
+  if (baseDir !== 'both') {
+    const skillsDir = getAgentsSkillsDir(baseDir);
+    const hasSkillsInstalled = skillsDir && SKILLS.some((skill) => existsSync(join(skillsDir, skill)));
+    if (!hasSkillsInstalled) {
+      console.log(chalk.yellow('No skills installed at this location.'));
+      console.log('Install them first with:');
+      console.log('  titools install');
+      console.log('');
+      console.log('Looked for skills in:');
+      console.log(`  ${baseDir ? 'Local' : 'Global'}: ${skillsDir}`);
+      return;
+    }
   }
 
   // Check for updates
@@ -121,7 +177,7 @@ export async function updateCommand(options) {
   try {
     const hasUpdate = await checkForUpdate(PACKAGE_VERSION);
 
-    // If there's a newer version on GitHub, prompt user to update CLI first
+    // If there's a newer version on npm, prompt user to update CLI first
     if (hasUpdate) {
       let latestVersion = '(newer)';
       try {
@@ -158,38 +214,18 @@ export async function updateCommand(options) {
       return;
     }
 
-    // Detect platforms with existing symlinks (only update those)
-    const detectedPlatforms = detectPlatforms(baseDir);
-    const platformsWithSymlinks = detectedPlatforms.filter((p) =>
-      hasAnySkillSymlink(p.skillsDir)
-    );
-
-    // Install skills
-    spinner.start('Syncing skills...');
-    const skillsResult = await installSkills(repoDir, baseDir);
-    spinner.succeed(`${skillsResult.installed.length} skills updated`);
-
-    // Install agents (only if Claude Code has symlinks)
-    const claudePlatform = platformsWithSymlinks.find((p) => p.name === 'claude');
-    if (claudePlatform) {
-      spinner.start('Syncing agents...');
-      const agentsResult = await installAgents(repoDir, baseDir);
-      if (agentsResult.installed.length > 0) {
-        spinner.succeed('Platform agents updated');
-      } else {
-        spinner.info('No agents to sync');
-      }
-    }
-
-    cleanupLegacyArtifacts(baseDir);
+    // Perform update(s)
+    if (baseDir === 'both') {
+      // Update both global and local
+      console.log(chalk.bold('Updating global skills...'));
+      await performUpdate(undefined, repoDir, spinner);
+      console.log('');
 
-    // Update symlinks silently for platforms that already had them
-    for (const platform of platformsWithSymlinks) {
-      await createSkillSymlinks(
-        platform.skillsDir,
-        SKILLS,
-        baseDir
-      );
+      console.log(chalk.bold('Updating local skills...'));
+      await performUpdate(process.cwd(), repoDir, spinner);
+    } else {
+      // Update single scope
+      await performUpdate(baseDir, repoDir, spinner);
     }
 
     // Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.2.9",
+  "version": "2.2.11",
   "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

@@ -31,18 +31,25 @@ Behavior:
 
 ## Workflow
 
-1. Architecture: define structure (`lib/api`, `lib/services`, `lib/helpers`)
+1. Architecture: define structure by technical type with flat folders (`lib/api`, `lib/services`, `lib/actions`, `lib/repositories`, `lib/helpers`)
 2. Data strategy: choose Models (SQLite) or Collections (API)
 3. Contracts: define I/O specs between layers
 4. Implementation: write XML views and ES6+ controllers
 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/user/card.xml`)
+View (`views/userCard.xml`)
 ```xml
 <Alloy>
   <View id="cardContainer">
@@ -58,7 +65,7 @@ View (`views/user/card.xml`)
 </Alloy>
 ```
 
-Styles (`styles/user/card.tss`)
+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 }
@@ -67,7 +74,7 @@ Styles (`styles/user/card.tss`)
 "#viewProfileBtn": { left: 12, right: 12, bottom: 12, height: 40, width: Ti.UI.FILL, borderRadius: 6, backgroundColor: '#2563eb', color: '#fff' }
 ```
 
-Controller (`controllers/user/card.js`)
+Controller (`controllers/userCard.js`)
 ```javascript
 const { Navigation } = require('services/navigation')
 
@@ -77,7 +84,7 @@ function init() {
 }
 
 function onViewProfile() {
-  Navigation.open('user/profile', { userId: $.args.user.id })
+  Navigation.open('userProfile', { userId: $.args.user.id })
 }
 
 function cleanup() {
@@ -163,6 +170,7 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 | Fastest way to build?              | `tn <recipe>` (using TiNy CLI wrapper)                         |
 | 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`                             |
 | 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)                              |

package/skills/ti-expert/references/alloy-structure.md

@@ -4,52 +4,81 @@
 
 ```
 app/
-├── controllers/           # View orchestrators
+├── controllers/          # View orchestrators
 │   ├── index.js          # Bootstrap only (no business logic)
-│   └── feature/
-│       └── list.js       # Controller for list view
+│   ├── home.js
+│   └── userProfile.js
 ├── models/               # OPTIONAL: For persistence with migrations
 │   └── user.js           # Model definition (ONLY if using SQLite)
 ├── views/                # XML views
 │   ├── index.xml
-│   └── feature/
-│       └── list.xml      # View definition
+│   ├── home.xml
+│   └── userProfile.xml
 ├── styles/               # TSS styles (one per view + global)
 │   ├── app.tss           # Global application styles
 │   ├── index.tss         # Styles for index view
-│   └── feature/
-│       └── list.tss      # Styles for feature/list view
+│   ├── home.tss
+│   └── userProfile.tss
 ├── lib/                  # Reusable logic (no UI)
 │   ├── api/
-│   │   └── client.js     # API calls
+│   │   ├── authApi.js
+│   │   ├── userApi.js
+│   │   └── frameApi.js
 │   ├── services/
-│   │   ├── auth.js       # Business logic services
-│   │   ├── navigation.js # Navigation orchestration
-│   │   └── nativeService.js # Native module wrapper (e.g. Audio, FB, Maps)
-│   └── helpers/
-│       ├── utils.js      # Pure utility functions
-│       └── i18n.js       # Complex string transformations
+│   │   ├── authService.js
+│   │   ├── navigationService.js
+│   │   └── notificationService.js
+│   ├── actions/
+│   │   ├── syncUserAction.js
+│   │   └── refreshSessionAction.js
+│   ├── repositories/
+│   │   ├── userRepository.js
+│   │   └── settingsRepository.js
+│   ├── helpers/
+│   │   ├── validator.js
+│   │   ├── formatter.js
+│   │   └── dateHelper.js
+│   ├── policies/
+│   │   ├── permissionPolicy.js
+│   │   └── featurePolicy.js
+│   └── providers/
+│       ├── containerProvider.js
+│       └── loggerProvider.js
 ├── widgets/              # Truly reusable components (used in 3+ places)
 │   └── customButton/
 ├── config.json           # Alloy configuration
 └── alloy.js              # Collections & Global services
 ```
 
+## Organization strategy
+
+- `lib/` uses technical-type grouping (Laravel-style naming adapted to Titanium).
+- UI stays in Alloy MVC folders (`controllers`, `views`, `styles`).
+- This is a hybrid approach: technical grouping for reusable logic + screen-based organization for UI files.
+- Keep folder depth low to preserve discoverability.
+- Use clear composed names (`authService.js`, `userRepository.js`, `authApi.js`) and keep multiple files per folder as the normal case.
+
+### Folder depth policy (critical)
+
+- Allowed in `lib`: `lib/<type>/<file>.js`
+- Avoid in `lib`: `lib/<type>/<domain>/<subdomain>/<file>.js`
+- If a folder grows too much, split by new technical type, not deep tree nesting.
+
 ## lib/ folder and module require paths
 
 :::danger CRITICAL: lib/ Folder is FLATTENED During Build
 When Alloy compiles, the **entire `lib/` folder is flattened to the root of Resources**. This means:
-- `app/lib/services/picsum.js` → `Resources/iphone/services/picsum.js`
-- `app/lib/api/client.js` → `Resources/iphone/api/client.js`
+- `app/lib/services/authService.js` → `Resources/iphone/services/authService.js`
+- `app/lib/api/authApi.js` → `Resources/iphone/api/authApi.js`
 
 **Therefore, require statements should NOT include `lib/` prefix:**
 ```javascript
 // ❌ WRONG - Will fail at runtime
-const client = require('lib/api/client')
+const authApi = require('lib/api/authApi')
 
 // ✅ CORRECT - Path relative to flattened lib/
-const client = require('api/client')
-const picsum = require('services/picsum')
+const authApi = require('api/authApi')
+const authService = require('services/authService')
 ```
 
 **This applies to:**
@@ -62,13 +91,18 @@ const picsum = require('services/picsum')
 app/
 ├── lib/
 │   ├── services/
-│   │   ├── picsum.js     # require('services/logger')
-│   │   ├── navigation.js # require('services/logger')
-│   │   └── logger.js
-│   └── api/
-│       └── client.js     # require('services/logger')
+│   │   ├── authService.js       # require('services/navigationService')
+│   │   ├── navigationService.js # require('services/notificationService')
+│   │   └── notificationService.js
+│   ├── api/
+│   │   ├── authApi.js           # require('services/authService')
+│   │   ├── userApi.js
+│   │   └── frameApi.js
+│   └── repositories/
+│       ├── userRepository.js
+│       └── settingsRepository.js
 ├── controllers/
-│   └── index.js          # require('services/picsum')
+│   └── index.js                 # require('services/authService')
 ```
 :::
 
@@ -145,6 +179,7 @@ api.getFrames()
 - Handle UI events and delegate to services.
 - Format data for display (simple cases).
 - Manage view lifecycle (including cleanup).
+- Keep `lib` modules flat and easy to locate.
 
 **DON'T:**
 - Use inline style attributes in XML (define in TSS files).

package/skills/ti-guides/references/app-distribution.md

@@ -198,3 +198,176 @@ Installation method:
 2. Open Xcode, then Window, then Devices.
 3. Select the device, then Installed Apps, then +.
 4. Select the IPA file.
+
+---
+
+## Mac Catalyst distribution (Mac App Store)
+
+Mac Catalyst allows you to run your iPad app on macOS. Titanium SDK 13.1.1.GA and later supports building for Mac Catalyst.
+
+### 1. Enable Mac Catalyst for your App ID
+
+1. Go to [Apple Developer → Identifiers](https://developer.apple.com/account/resources/identifiers/list)
+2. Select your App ID or create a new one
+3. Enable **Mac Catalyst** capability
+4. Save the changes
+
+### 2. Create Mac App Store Distribution Certificate
+
+1. Go to [Apple Developer → Certificates](https://developer.apple.com/account/resources/certificates/list)
+2. Click **+** to create a new certificate
+3. Select **Mac App Store Distribution**
+4. Upload your CSR (Certificate Signing Request)
+5. Download and install the certificate
+
+### 3. Mac Catalyst build targets
+
+Titanium provides two targets for Mac Catalyst:
+
+| Target | Description | Configuration |
+|--------|-------------|---------------|
+| `macos` | Development builds for testing on Mac | Debug-maccatalyst |
+| `dist-macappstore` | Production builds for Mac App Store | Release-maccatalyst |
+
+### 4. Build for Mac Catalyst (Development)
+
+```bash
+ti build -p ios -T macos
+```
+
+The `.app` bundle will be created at:
+```
+build/iphone/build/Products/Debug-maccatalyst/AppName.app
+```
+
+For a production-ready build:
+```bash
+ti build -p ios -T macos --deploy-type production
+```
+
+The `.app` bundle will be at:
+```
+build/iphone/build/Products/Release-maccatalyst/AppName.app
+```
+
+### 5. Build for Mac App Store (Distribution)
+
+```bash
+ti build -p ios -T dist-macappstore [-R <CERTIFICATE_NAME>]
+```
+
+Example:
+```bash
+ti build -p ios -T dist-macappstore -R "Apple Distribution: Your Team Name (TEAM_ID)"
+```
+
+If you omit the `-R` flag, Titanium will prompt you to select a certificate.
+
+**What happens during the build:**
+- Uses `Release-maccatalyst` configuration
+- Sets code signing to Manual with identity `-`
+- Creates a `.xcarchive` for Mac App Store
+- Installs the archive in Xcode's Organizer
+- Destination: `generic/platform=macOS`
+
+### 6. Upload to Mac App Store Connect
+
+1. Open Xcode → Window → Organizer
+2. Select your Mac Catalyst archive
+3. Click **Validate App** to check for issues
+4. Click **Distribute App**
+5. Select **Mac App Store**
+6. Follow the prompts to upload
+
+### 7. Create app listing in App Store Connect
+
+1. Go to [App Store Connect](https://appstoreconnect.apple.com)
+2. **My Apps → + → New App**
+3. Select **Mac** as platform
+4. Enter app details:
+   - Name
+   - Primary Language
+   - Bundle ID (must match your App ID with Mac Catalyst enabled)
+   - SKU
+5. Complete required metadata:
+   - Description
+   - Keywords
+   - Screenshots (Mac-specific sizes)
+   - Category
+   - Age rating
+
+### 8. Mac Catalyst entitlements
+
+Add Mac-specific entitlements in `tiapp.xml`:
+
+```xml
+<ios>
+  <entitlements>
+    <dict>
+      <!-- File access for saving to Downloads -->
+      <key>com.apple.security.files.user-selected.read-write</key>
+      <true/>
+      <key>com.apple.security.files.downloads.read-write</key>
+      <true/>
+
+      <!-- App sandbox (required for Mac App Store) -->
+      <key>com.apple.security.app-sandbox</key>
+      <true/>
+
+      <!-- Network access -->
+      <key>com.apple.security.network.client</key>
+      <true/>
+
+      <!-- Additional entitlements as needed -->
+      <key>com.apple.security.print</key>
+      <true/>
+    </dict>
+  </entitlements>
+</ios>
+```
+
+### 9. Common issues
+
+**Issue**: "No suitable signing certificate found"
+- Ensure you have a **Mac App Store Distribution Certificate** (not iOS Distribution)
+- The certificate must be installed in your Keychain
+
+**Issue**: Build fails with code signing errors
+- Verify your App ID has Mac Catalyst enabled
+- Check that the certificate matches the App ID
+- Try cleaning the build: `ti clean -p ios`
+
+**Issue**: App crashes on launch
+- Verify entitlements are correctly configured
+- Check Console.app for crash logs
+- Ensure all required capabilities are enabled
+
+### 10. Versioning
+
+Update version numbers in `tiapp.xml`:
+
+```xml
+<ti:app xmlns:ti="http://ti.tidev.io">
+  <id>com.yourcompany.yourapp</id>
+  <name>Your App Name</name>
+  <version>1.0.0</version>
+  <publisher>Your Company</publisher>
+  ...
+</ti:app>
+```
+
+- `version`: Display version (e.g., "1.0.0")
+- For iOS, use `pv-version-code` in `<ios>` section for build number
+- For Mac, the build number can be set in Xcode or via `CFBundleVersion`
+
+### 11. Testing on Mac
+
+Before submitting to Mac App Store:
+
+1. Build with `macos` target for testing
+2. Run the app on different Mac architectures (Intel and Apple Silicon)
+3. Test all features that use file system, network, and other sandboxed resources
+4. Verify entitlements are working correctly
+5. Test on macOS versions you plan to support
+
+---

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

@@ -258,7 +258,7 @@ Omit `-V` and `-P` to be prompted.
 | `-P, --pp-uuid <uuid>`           | Provisioning profile UUID (for device/dist targets).                                                   |
 | `-R, --distribution-name <name>` | iOS Distribution Certificate (for dist targets).                                                       |
 | `--sim-focus`                    | Focus the iOS Simulator after launching (default: true). Use --no-sim-focus to disable.                |
-| `-T, --target <value>`           | Target: simulator, device, dist-appstore, or dist-adhoc.                                               |
+| `-T, --target <value>`           | Target: simulator, device, dist-appstore, dist-adhoc, macos, or dist-macappstore.                            |
 | `-V, --developer-name <name>`    | iOS Developer Certificate (required for device target).                                                |
 | `-W, --watch-device-id <udid>`   | Watch simulator UDID (simulator only).                                                                 |
 | `--watch-app-name <name>`        | Name of the watch app to launch (simulator only).                                                      |
@@ -394,6 +394,48 @@ ti build -p ios -T dist-appstore -R "Pseudo, Inc." -P "AAAAAAAA-0000-9999-8888-7
 
 Installs the package to Xcode Organizer.
 
+### Mac Catalyst (macOS Development)
+
+```bash
+ti build -p ios -T macos
+```
+
+Builds a Mac Catalyst version of your iOS app for local testing. The resulting `.app` bundle is located at:
+```
+build/iphone/build/Products/Debug-maccatalyst/AppName.app
+```
+
+For a production build:
+```bash
+ti build -p ios -T macos --deploy-type production
+```
+
+The release `.app` bundle will be at:
+```
+build/iphone/build/Products/Release-maccatalyst/AppName.app
+```
+
+### Mac App Store (Mac Catalyst Distribution)
+
+```bash
+ti build -p ios -T dist-macappstore [-R <CERT_NAME>]
+```
+
+Example:
+```bash
+ti build -p ios -T dist-macappstore -R "Apple Distribution: Your Name (TEAM_ID)"
+```
+
+**Important Notes:**
+- Requires a Mac App Store Distribution Certificate (not iOS Distribution)
+- The build creates an archive for Mac App Store distribution
+- The `.xcarchive` is installed in Xcode's Organizer
+- Uses `Release-maccatalyst` configuration
+- Destination: `generic/platform=macOS`
+- Code signing is set to Manual with identity `-`
+
+The target `dist-macappstore` is available in Titanium SDK 13.1.1.GA and later.
+
 ---
 
 ## SDK management