@maccesar/titools 2.0.0

package/agents/ti-researcher.md

@@ -0,0 +1,108 @@
+---
+name: ti-researcher
+description: Titanium SDK and Alloy research specialist. Preloads all 7 titanium-* skills for comprehensive analysis. Use proactively for: analyzing Titanium/Alloy codebases, reviewing Alloy app architecture, researching Titanium SDK implementations, exploring mobile app architectural questions, multi-feature research across Titanium APIs, cross-referencing framework patterns, or investigating platform-specific Titanium differences. Returns findings with specific file/line references from all documentation.
+skills:
+  - alloy-expert
+  - alloy-guides
+  - alloy-howtos
+  - purgetss
+  - ti-guides
+  - ti-howtos
+  - ti-ui
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# Titanium SDK Research Specialist
+
+You are a deep-dive research specialist for Titanium SDK and Alloy mobile development.
+
+## What You Do
+
+When invoked, you research complex topics by consulting **all 7 preloaded titanium-\*** skills:
+
+- `alloy-expert` - Architecture, patterns, PurgeTSS conventions
+- `alloy-guides` - Alloy MVC complete reference
+- `alloy-howtos` - CLI, config, debugging
+- `purgetss` - Utility-first styling classes
+- `ti-guides` - SDK official guides, Hyperloop, distribution
+- `ti-howtos` - Native features, platform-specific APIs
+- `ti-ui` - UI/UX patterns, layouts, gestures
+
+## Research Process
+
+1. **Understand the query** - What specific aspect needs research?
+2. **Consult ALL relevant skills** - All skills are preloaded in your context
+3. **Cross-reference** - Find connections across multiple skills
+4. **Provide specifics** - Include file paths, line numbers, code examples
+5. **Cite sources** - Reference which skill and file each answer comes from
+
+## What You're Good For
+
+| Use Case                   | Example                                                            |
+| -------------------------- | ------------------------------------------------------------------ |
+| **Codebase analysis**      | "Analyze this Alloy app's architecture and identify anti-patterns" |
+| **Multi-feature research** | "Research how to implement location + push + background sync"      |
+| **Cross-skills questions** | "Compare ListView vs TableView performance with PurgeTSS styling"  |
+| **Architecture review**    | "Review this project's folder structure and service layer"         |
+| **Platform differences**   | "Research iOS vs Android differences for this feature"             |
+
+## What You're NOT For
+
+| Use Instead                                  | Reason                                 |
+| -------------------------------------------- | -------------------------------------- |
+| `/alloy-expert` for architecture guidance    | Inline consultation during development |
+| `/purgetss` to verify a class                | Quick inline reference                 |
+| `/ti-howtos` for step-by-step implementation | Task-oriented guidance                 |
+| Main conversation for iterative work         | Sub-agents run in isolation            |
+
+## Response Format
+
+When returning research findings:
+
+1. **Summary** - Brief overview of findings
+2. **Key Points** - Bulleted list with specific references
+3. **Code Examples** - From the skills, with source citations
+4. **Related Skills** - Which skills were consulted
+5. **File References** - Specific `path:line` format
+
+Example:
+```markdown
+## Summary
+Your app uses `Ti.App.fireEvent` which causes memory leaks.
+
+## Key Points
+- **alloy-expert/references/anti-patterns.md:45** - Ti.App.fireEvent leaks memory
+- **alloy-howtos/references/best_practices.md:23** - Use Backbone.Events instead
+
+## Solution
+[Code example from alloy-howtos]
+```
+
+## Tool Usage
+
+You have **read-only tools**: `Read`, `Grep`, `Glob`
+
+Use them to:
+- Search the codebase when asked to analyze it
+- Find patterns across multiple files
+- Verify claims against actual code
+
+You **cannot** modify files. If the user asks for changes, provide the research and suggest using the appropriate skill or main conversation for implementation.
+
+---
+
+## Usage Examples
+
+**Automatic activation (proactive):**
+- "Analyze this **Titanium Alloy** codebase and identify architectural anti-patterns"
+- "Research the best way to implement location services in this **Titanium project**"
+- "Do a comprehensive analysis of the UI patterns used in this **Alloy app**"
+- "Explore the architecture of this **mobile app** and identify areas for improvement"
+
+> **Tip**: Include words like "Titanium", "Alloy", "mobile app", or "architecture review" to ensure the agent is triggered for Titanium-specific analysis.
+
+**Manual activation (always works):**
+- "Use the ti-researcher agent to analyze this codebase"
+- "Have ti-researcher investigate the architecture of this project"
+- "Use ti-researcher to research platform-specific differences for this feature"

package/bin/titools.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * titools - Titanium SDK Skills CLI Tool
+ * Main entry point for the NPM package
+ */
+
+import { Command } from 'commander';
+import { PACKAGE_VERSION } from '../lib/config.js';
+import { installCommand } from '../lib/commands/install.js';
+import { agentsCommand } from '../lib/commands/agents.js';
+import { updateCommand } from '../lib/commands/update.js';
+import { uninstallCommand } from '../lib/commands/uninstall.js';
+
+const program = new Command();
+
+program
+  .name('titools')
+  .description('Titanium SDK Skills CLI - Manage skills and agents for AI coding assistants')
+  .version(PACKAGE_VERSION);
+
+// Install command
+program
+  .command('install')
+  .description('Install Titanium skills and agents to your AI coding assistant')
+  .option('-a, --all', 'Install to all detected platforms without prompting')
+  .option('--path <path>', 'Install to a custom path (skips symlink setup)')
+  .action(installCommand);
+
+// Agents command
+program
+  .command('agents')
+  .description('Add AGENTS.md/CLAUDE.md/GEMINI.md to your Titanium project')
+  .argument('[path]', 'Project path (defaults to current directory)', '.')
+  .option('-f, --force', 'Overwrite existing files without prompting')
+  .action(agentsCommand);
+
+// Update command
+program
+  .command('update')
+  .description('Update Titanium skills and docs to the latest version')
+  .action(updateCommand);
+
+// Uninstall command
+program
+  .command('uninstall')
+  .description('Remove Titanium skills and agents')
+  .action(uninstallCommand);
+
+// Parse arguments
+program.parse();
+
+export { program };

package/lib/commands/agents.js

@@ -0,0 +1,126 @@
+/**
+ * Agents command
+ * Adds AGENTS.md/CLAUDE.md/GEMINI.md to Titanium projects
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import {
+  getAgentsDir,
+  getAgentsSkillsDir,
+  TITANIUM_PROJECT_FILE,
+  AI_FILE_PRIORITIES,
+} from '../config.js';
+import {
+  isTitaniumProject,
+  detectTitaniumVersion,
+  getAIFiles,
+  determineFilesToUpdate,
+  addOrUpdateBlock,
+} from '../utils.js';
+import { existsSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+/**
+ * Agents command handler
+ * @param {string} projectPath - Project path argument
+ * @param {Object} options - Command options
+ */
+export async function agentsCommand(projectPath, options) {
+  console.log('');
+  console.log(chalk.bold.blue('Titanium AGENTS.md Installer'));
+  console.log('');
+
+  // Resolve project path
+  const projectDir = resolve(projectPath);
+
+  // Verify skills are installed (needed for building index)
+  const agentsSkillsDir = getAgentsSkillsDir();
+  if (!existsSync(agentsSkillsDir)) {
+    console.log(chalk.red('Error: Skills not installed'));
+    console.log('Install titools first:');
+    console.log('  titools install');
+    console.log('');
+    console.log('This command needs access to Titanium skills to build the documentation index.');
+    process.exit(1);
+  }
+
+  // Verify this is a Titanium project
+  if (!isTitaniumProject(projectDir)) {
+    console.log(chalk.red('Error: Not a Titanium project (no tiapp.xml)'));
+    console.log('Run this command from your project root.');
+    process.exit(1);
+  }
+
+  // Detect Titanium version
+  const tiVersion = detectTitaniumVersion(projectDir);
+  console.log(chalk.green('✓'), `Titanium project (SDK ${tiVersion})`);
+  console.log('');
+
+  // Check which AI files exist
+  const aiFiles = getAIFiles(projectDir);
+
+  // Determine which files to update
+  let filesToUpdate = determineFilesToUpdate(aiFiles);
+
+  // If no files exist, ask which AI they use
+  if (filesToUpdate.length === 0) {
+    if (options.force) {
+      // Default to CLAUDE.md if force mode
+      filesToUpdate = ['CLAUDE.md'];
+    } else {
+      const answers = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'ai',
+          message: 'Which AI assistant are you using?',
+          choices: [
+            { name: 'Claude Code (creates CLAUDE.md)', value: 'CLAUDE.md' },
+            { name: 'Gemini CLI (creates GEMINI.md)', value: 'GEMINI.md' },
+            { name: 'Cursor/Copilot (creates AGENTS.md)', value: 'AGENTS.md' },
+          ],
+        },
+      ]);
+      filesToUpdate = [answers.ai];
+    }
+  }
+
+  // Update each file
+  const spinner = ora();
+  const updated = [];
+
+  for (const filename of filesToUpdate) {
+    const filePath = join(projectDir, filename);
+
+    // Create file if it doesn't exist
+    if (!existsSync(filePath)) {
+      writeFileSync(filePath, '', 'utf8');
+    }
+
+    spinner.start(`Updating ${filename}...`);
+
+    try {
+      addOrUpdateBlock(filePath);
+      spinner.succeed(`${filename} updated`);
+      updated.push(filename);
+    } catch (error) {
+      spinner.fail(`Failed to update ${filename}: ${error.message}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.green('✓'), `Done! Updated: ${updated.join(', ')}`);
+  console.log('');
+
+  // Show notes for multiple files
+  if (updated.length > 1) {
+    console.log(
+      chalk.cyan('Note:'),
+      `Updated ${updated.length} files - Titanium knowledge synced across all.`
+    );
+    console.log('');
+  }
+}
+
+export default agentsCommand;

package/lib/commands/install.js

@@ -0,0 +1,188 @@
+/**
+ * Install command
+ * Installs skills and agents to AI coding assistant directories
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import {
+  SKILLS,
+  AGENTS,
+  REPO_URL,
+} from '../config.js';
+import {
+  detectPlatforms,
+  detectOS,
+} from '../platform.js';
+import {
+  installSkills,
+  installAgents,
+  installAgentsTemplate,
+  getLocalRepoDir,
+} from '../installer.js';
+import { downloadRepoArchive } from '../downloader.js';
+import { createSkillSymlinks } from '../symlink.js';
+import { formatList } from '../utils.js';
+import { mkdtemp } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+/**
+ * Install command handler
+ * @param {Object} options - Command options
+ */
+export async function installCommand(options) {
+  console.log('');
+  console.log(chalk.bold.blue('Titanium SDK Skills Installer'));
+  console.log('');
+
+  // Detect installed platforms
+  const detectedPlatforms = detectPlatforms();
+
+  if (detectedPlatforms.length === 0 && !options.path) {
+    console.log(chalk.yellow('No AI coding assistants detected.'));
+    console.log('Install one of: Claude Code, Gemini CLI, or Codex CLI');
+    console.log('Or use: titools install --path /custom/path');
+    process.exit(1);
+  }
+
+  // Show detected platforms
+  for (const platform of detectedPlatforms) {
+    console.log(chalk.green('✓'), `${platform.displayName} detected`);
+  }
+  console.log('');
+
+  // Select platforms to install
+  let selectedPlatforms = [];
+
+  if (options.path) {
+    // Custom path mode - skip platform selection
+    selectedPlatforms = [];
+  } else if (options.all) {
+    // Install to all detected platforms
+    selectedPlatforms = detectedPlatforms;
+  } else {
+    // Interactive selection
+    const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'platform',
+        message: 'Select platform to install:',
+        choices: [
+          { name: 'All detected platforms', value: 'all' },
+          ...detectedPlatforms.map((p) => ({
+            name: `${p.displayName} only`,
+            value: p.name,
+          })),
+          { name: 'Cancel', value: 'cancel' },
+        ],
+      },
+    ]);
+
+    if (answers.platform === 'cancel') {
+      console.log('Cancelled.');
+      process.exit(0);
+    }
+
+    if (answers.platform === 'all') {
+      selectedPlatforms = detectedPlatforms;
+    } else {
+      selectedPlatforms = detectedPlatforms.filter(
+        (p) => p.name === answers.platform
+      );
+    }
+  }
+
+  if (selectedPlatforms.length === 0 && !options.path) {
+    console.log('No platforms selected.');
+    process.exit(0);
+  }
+
+  // Get repository directory (local or download)
+  const spinner = ora();
+  let repoDir = getLocalRepoDir();
+
+  if (!repoDir) {
+    // Download from GitHub
+    spinner.start('Downloading from GitHub...');
+    try {
+      const tempDir = tmpdir();
+      repoDir = await mkdtemp(join(tempDir, 'titanium-skills-'));
+      await downloadRepoArchive(repoDir);
+      spinner.succeed('Downloaded from GitHub');
+    } catch (error) {
+      spinner.fail('Failed to download');
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  } else {
+    console.log(chalk.green('Using local repository'));
+  }
+
+  try {
+    // Install skills
+    spinner.start('Installing skills...');
+    const skillsResult = await installSkills(repoDir);
+    spinner.succeed(
+      `Skills: ${formatList(skillsResult.installed)}`
+    );
+
+    // Install agents
+    spinner.start('Installing agents...');
+    const agentsResult = await installAgents(repoDir);
+    if (agentsResult.installed.length > 0) {
+      spinner.succeed(
+        `Agents: ${formatList(agentsResult.installed)}`
+      );
+    } else {
+      spinner.info('No agents to install (Claude Code not detected)');
+    }
+
+    // Install AGENTS-TEMPLATE.md
+    spinner.start('Installing AGENTS-TEMPLATE.md...');
+    const templateInstalled = await installAgentsTemplate(repoDir);
+    if (templateInstalled) {
+      spinner.succeed('AGENTS-TEMPLATE.md installed');
+    } else {
+      spinner.warn('AGENTS-TEMPLATE.md not found');
+    }
+
+    // Create symlinks for selected platforms
+    for (const platform of selectedPlatforms) {
+      spinner.start(`Linking ${platform.displayName}...`);
+      const symlinkResult = await createSkillSymlinks(
+        platform.skillsDir,
+        SKILLS
+      );
+      if (symlinkResult.linked.length === SKILLS.length) {
+        spinner.succeed(`${platform.displayName} linked`);
+      } else {
+        spinner.warn(
+          `${platform.displayName}: ${symlinkResult.linked.length}/${SKILLS.length} linked`
+        );
+      }
+    }
+
+    // Summary
+    console.log('');
+    console.log(chalk.green('✓ Installation complete!'));
+    console.log('');
+    console.log(chalk.bold('▸'), 'Add AGENTS.md to your project:', chalk.cyan('titools agents'));
+    console.log(chalk.bold('▸'), 'Improves AI:', chalk.red('53%'), '→', chalk.green('100%'));
+    console.log('');
+
+    if (detectOS() === 'windows') {
+      console.log(chalk.yellow('▸'), 'Windows: Ensure ~/bin is in your PATH');
+      console.log('');
+    }
+
+  } finally {
+    // Clean up temp directory if we downloaded
+    if (repoDir !== getLocalRepoDir() && repoDir.startsWith(tmpdir())) {
+      await import('fs-extra').then(({ remove }) => remove(repoDir));
+    }
+  }
+}
+
+export default installCommand;

package/lib/commands/uninstall.js

@@ -0,0 +1,215 @@
+/**
+ * Uninstall command
+ * Removes installed skills and agents
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import { SKILLS, AGENTS } from '../config.js';
+import {
+  detectPlatforms,
+} from '../platform.js';
+import { remove } from 'fs-extra';
+import { existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import {
+  getAgentsSkillsDir,
+  getClaudeAgentsDir,
+  getClaudeSkillsDir,
+  getGeminiSkillsDir,
+  getCodexSkillsDir,
+} from '../config.js';
+
+/**
+ * Remove skill symlinks from a platform directory
+ * @param {string} platformSkillsDir - Platform skills directory
+ * @returns {Object} Results object with success/failure counts
+ */
+function removeSkillSymlinks(platformSkillsDir) {
+  const results = {
+    removed: [],
+    failed: [],
+  };
+
+  if (!existsSync(platformSkillsDir)) {
+    return results;
+  }
+
+  for (const skill of SKILLS) {
+    const linkPath = join(platformSkillsDir, skill);
+
+    if (existsSync(linkPath)) {
+      try {
+        rmSync(linkPath, { recursive: true, force: true });
+        results.removed.push(skill);
+      } catch (error) {
+        results.failed.push(skill);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Remove skills from central directory
+ * @returns {Object} Results object
+ */
+function removeSkills() {
+  const skillsDir = getAgentsSkillsDir();
+  const results = {
+    removed: [],
+    failed: [],
+  };
+
+  if (!existsSync(skillsDir)) {
+    return results;
+  }
+
+  for (const skill of SKILLS) {
+    const skillPath = join(skillsDir, skill);
+
+    if (existsSync(skillPath)) {
+      try {
+        rmSync(skillPath, { recursive: true, force: true });
+        results.removed.push(skill);
+      } catch (error) {
+        results.failed.push(skill);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Remove agents from Claude Code
+ * @returns {Object} Results object
+ */
+function removeAgents() {
+  const agentsDir = getClaudeAgentsDir();
+  const results = {
+    removed: [],
+    failed: [],
+  };
+
+  if (!existsSync(agentsDir)) {
+    return results;
+  }
+
+  for (const agent of AGENTS) {
+    const agentPath = join(agentsDir, `${agent}.md`);
+
+    if (existsSync(agentPath)) {
+      try {
+        rmSync(agentPath);
+        results.removed.push(agent);
+      } catch (error) {
+        results.failed.push(agent);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Uninstall command handler
+ * @param {Object} options - Command options
+ */
+export async function uninstallCommand(options) {
+  console.log('');
+  console.log(chalk.bold.blue('Titanium SDK Skills Uninstaller'));
+  console.log('');
+
+  // Detect installed platforms
+  const detectedPlatforms = detectPlatforms();
+
+  if (detectedPlatforms.length === 0) {
+    console.log(chalk.yellow('No AI coding assistants detected.'));
+    console.log('However, you can still remove skills from the central directory.');
+    console.log('');
+  }
+
+  // Show detected platforms
+  for (const platform of detectedPlatforms) {
+    console.log(chalk.green('✓'), `${platform.displayName} detected`);
+  }
+  console.log('');
+
+  // Select what to uninstall
+  const answers = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'targets',
+      message: 'What do you want to uninstall?',
+      choices: [
+        { name: 'Skill symlinks from all platforms', value: 'symlinks', checked: true },
+        { name: 'Skills from central directory (~/.agents/skills/)', value: 'skills', checked: false },
+        { name: 'Agents from Claude Code', value: 'agents', checked: false },
+      ],
+      validate: (answer) => answer.length > 0 || 'Please select at least one option',
+    },
+  ]);
+
+  if (answers.targets.includes('symlinks') && detectedPlatforms.length === 0) {
+    console.log(chalk.yellow('No platforms detected, skipping symlink removal.'));
+    answers.targets = answers.targets.filter((t) => t !== 'symlinks');
+  }
+
+  if (answers.targets.length === 0) {
+    console.log('Nothing to uninstall.');
+    process.exit(0);
+  }
+
+  const spinner = ora();
+
+  // Remove symlinks from platforms
+  if (answers.targets.includes('symlinks')) {
+    for (const platform of detectedPlatforms) {
+      spinner.start(`Removing ${platform.displayName} symlinks...`);
+      const symlinkResult = removeSkillSymlinks(platform.skillsDir);
+
+      if (symlinkResult.removed.length > 0) {
+        spinner.succeed(`${platform.displayName}: ${symlinkResult.removed.length} removed`);
+      } else {
+        spinner.info(`${platform.displayName}: No symlinks found`);
+      }
+    }
+  }
+
+  // Remove skills from central directory
+  if (answers.targets.includes('skills')) {
+    spinner.start('Removing skills from central directory...');
+    const skillsResult = removeSkills();
+
+    if (skillsResult.removed.length > 0) {
+      spinner.succeed(`Skills: ${skillsResult.removed.join(', ')}`);
+    } else {
+      spinner.info('No skills found in central directory');
+    }
+  }
+
+  // Remove agents
+  if (answers.targets.includes('agents')) {
+    spinner.start('Removing agents...');
+    const agentsResult = removeAgents();
+
+    if (agentsResult.removed.length > 0) {
+      spinner.succeed(`Agents: ${agentsResult.removed.join(', ')}`);
+    } else {
+      spinner.info('No agents found');
+    }
+  }
+
+  console.log('');
+  console.log(chalk.green('✓ Uninstallation complete!'));
+  console.log('');
+  console.log(chalk.gray('Note: AGENTS.md/CLAUDE.md/GEMINI.md files in your projects were NOT removed.'));
+  console.log(chalk.gray('To remove them manually:'));
+  console.log(chalk.gray('  rm -f /path/to/your/project/AGENTS.md'));
+  console.log('');
+}
+
+export default uninstallCommand;