@maccesar/titools 2.0.6 → 2.2.0

package/agents/{ti-researcher.md → ti-pro.md}

@@ -1,8 +1,8 @@
 ---
-name: ti-researcher
+name: ti-pro
 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
+  - ti-expert
   - alloy-guides
   - alloy-howtos
   - purgetss
@@ -21,10 +21,10 @@ You are a deep-dive research specialist for Titanium SDK and Alloy mobile develo
 
 When invoked, you research complex topics by consulting **all 7 preloaded titanium-\*** skills:
 
-- `alloy-expert` - Architecture, patterns, PurgeTSS conventions
+- `ti-expert` - Architecture, patterns, conventions
 - `alloy-guides` - Alloy MVC complete reference
 - `alloy-howtos` - CLI, config, debugging
-- `purgetss` - Utility-first styling classes
+- `purgetss` - Utility-first styling classes (optional addon — use when the project already has it or the user asks about it)
 - `ti-guides` - SDK official guides, Hyperloop, distribution
 - `ti-howtos` - Native features, platform-specific APIs
 - `ti-ui` - UI/UX patterns, layouts, gestures
@@ -43,7 +43,7 @@ When invoked, you research complex topics by consulting **all 7 preloaded titani
 | -------------------------- | ------------------------------------------------------------------ |
 | **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"  |
+| **Cross-skills questions** | "Compare ListView vs TableView performance and styling approaches" |
 | **Architecture review**    | "Review this project's folder structure and service layer"         |
 | **Platform differences**   | "Research iOS vs Android differences for this feature"             |
 
@@ -51,7 +51,7 @@ When invoked, you research complex topics by consulting **all 7 preloaded titani
 
 | Use Instead                                  | Reason                                 |
 | -------------------------------------------- | -------------------------------------- |
-| `/alloy-expert` for architecture guidance    | Inline consultation during development |
+| `/ti-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            |
@@ -72,7 +72,7 @@ Example:
 Your app uses `Ti.App.fireEvent` which causes memory leaks.
 
 ## Key Points
-- **alloy-expert/references/anti-patterns.md:45** - Ti.App.fireEvent leaks memory
+- **ti-expert/references/anti-patterns.md:45** - Ti.App.fireEvent leaks memory
 - **alloy-howtos/references/best_practices.md:23** - Use Backbone.Events instead
 
 ## Solution
@@ -103,6 +103,6 @@ You **cannot** modify files. If the user asks for changes, provide the research
 > **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"
+- "Use the ti-pro agent to analyze this codebase"
+- "Have ti-pro investigate the architecture of this project"
+- "Use ti-pro to research platform-specific differences for this feature"

package/bin/titools.js

@@ -7,7 +7,7 @@
 
 import { Command } from 'commander';
 import { PACKAGE_VERSION } from '../lib/config.js';
-import { installCommand } from '../lib/commands/install.js';
+import { skillsCommand } from '../lib/commands/skills.js';
 import { agentsCommand } from '../lib/commands/agents.js';
 import { updateCommand } from '../lib/commands/update.js';
 import { uninstallCommand } from '../lib/commands/uninstall.js';
@@ -16,35 +16,39 @@ const program = new Command();
 
 program
   .name('titools')
-  .description('Titanium SDK Skills CLI - Manage skills and agents for AI coding assistants')
+  .description('Titanium SDK Knowledge CLI - Manage skills and knowledge 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')
+  .description('Install Titanium knowledge packages and platform links')
+  .option('-l, --local', 'Install skills locally in the current project')
+  .option('-a, --all', 'Install all detected platforms without prompting')
   .option('--path <path>', 'Install to a custom path (skips symlink setup)')
-  .action(installCommand);
+  .action(skillsCommand);
 
-// Agents command
+// Sync command
 program
-  .command('agents')
-  .description('Add AGENTS.md/CLAUDE.md/GEMINI.md to your Titanium project')
+  .command('sync')
+  .description('Sync knowledge index files (AGENTS.md/CLAUDE.md/GEMINI.md) in a Titanium project')
   .argument('[path]', 'Project path (defaults to current directory)', '.')
   .option('-f, --force', 'Overwrite existing files without prompting')
+  .option('-v, --verbose', 'Show detailed diagnostics')
   .action(agentsCommand);
 
 // Update command
 program
   .command('update')
-  .description('Update Titanium skills and docs to the latest version')
+  .description('Update installed knowledge packages and agent (not the CLI)')
+  .option('-l, --local', 'Update local skills in the current project')
   .action(updateCommand);
 
-// Uninstall command
+// Remove command
 program
-  .command('uninstall')
-  .description('Remove Titanium skills and agents')
+  .command('remove')
+  .description('Remove Titanium knowledge packages and agent')
+  .option('-l, --local', 'Remove local skills from the current project')
   .action(uninstallCommand);
 
 // Parse arguments

package/lib/cleanup.js

@@ -0,0 +1,95 @@
+/**
+ * Cleanup helpers for skills, agents, and symlinks
+ */
+
+import {
+  SKILLS,
+  LEGACY_SKILLS,
+  AGENTS,
+  LEGACY_AGENTS,
+  getAgentsSkillsDir,
+  getClaudeAgentsDir,
+} from './config.js';
+import { detectPlatforms } from './platform.js';
+import { existsSync, lstatSync, rmSync } from 'fs';
+import { join } from 'path';
+
+export function getSkillList({ includeLegacy = true, legacyOnly = false } = {}) {
+  if (legacyOnly) return [...LEGACY_SKILLS];
+  return includeLegacy ? [...SKILLS, ...LEGACY_SKILLS] : [...SKILLS];
+}
+
+export function getAgentList({ includeLegacy = true, legacyOnly = false } = {}) {
+  if (legacyOnly) return [...LEGACY_AGENTS];
+  return includeLegacy ? [...AGENTS, ...LEGACY_AGENTS] : [...AGENTS];
+}
+
+function removeEntriesAtDir(dir, names, { suffix = '', recursive = true } = {}) {
+  const results = { removed: [], failed: [] };
+  if (!dir || !existsSync(dir)) return results;
+
+  for (const name of names) {
+    const target = join(dir, suffix ? `${name}${suffix}` : name);
+    try {
+      lstatSync(target);
+      rmSync(target, { recursive, force: true });
+      results.removed.push(name);
+    } catch (error) {
+      if (error.code && error.code !== 'ENOENT') {
+        results.failed.push(name);
+      }
+    }
+  }
+
+  return results;
+}
+
+export function removeSkillSymlinks(platformSkillsDir, options = {}) {
+  const skillList = getSkillList(options);
+  return removeEntriesAtDir(platformSkillsDir, skillList, { recursive: true });
+}
+
+export function removeLegacySkillSymlinks(platformSkillsDir) {
+  return removeSkillSymlinks(platformSkillsDir, { legacyOnly: true });
+}
+
+export function removeSkills(baseDir, options = {}) {
+  const skillsDir = getAgentsSkillsDir(baseDir);
+  const skillList = getSkillList(options);
+  return removeEntriesAtDir(skillsDir, skillList, { recursive: true });
+}
+
+export function removeAgents(baseDir, options = {}) {
+  const agentsDir = getClaudeAgentsDir(baseDir);
+  const agentList = getAgentList(options);
+  return removeEntriesAtDir(agentsDir, agentList, { suffix: '.md', recursive: false });
+}
+
+export function cleanupLegacyArtifacts(baseDir) {
+  removeSkills(baseDir, { legacyOnly: true });
+  removeAgents(baseDir, { legacyOnly: true });
+
+  const platforms = detectPlatforms(baseDir);
+  for (const platform of platforms) {
+    removeLegacySkillSymlinks(platform.skillsDir);
+  }
+
+  if (baseDir) {
+    removeSkills(undefined, { legacyOnly: true });
+    removeAgents(undefined, { legacyOnly: true });
+    const globalPlatforms = detectPlatforms();
+    for (const platform of globalPlatforms) {
+      removeLegacySkillSymlinks(platform.skillsDir);
+    }
+  }
+}
+
+export default {
+  getSkillList,
+  getAgentList,
+  removeSkillSymlinks,
+  removeLegacySkillSymlinks,
+  removeSkills,
+  removeAgents,
+  cleanupLegacyArtifacts,
+};

package/lib/commands/agents.js

@@ -3,21 +3,19 @@
  * 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,
+  SKILLS,
 } from '../config.js';
+import checkbox, { Separator } from '../prompts/checkboxCancel.js';
 import {
   isTitaniumProject,
   detectTitaniumVersion,
-  getAIFiles,
-  determineFilesToUpdate,
   addOrUpdateBlock,
+  blockExists,
+  removeOldBlock,
 } from '../utils.js';
 import { existsSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
@@ -28,28 +26,47 @@ import { join, resolve } from 'path';
  * @param {Object} options - Command options
  */
 export async function agentsCommand(projectPath, options) {
-  console.log('');
-  console.log(chalk.bold.blue('Titanium AGENTS.md Installer'));
+  const effectiveOptions = options || {};
+  const inline = !!effectiveOptions.inline;
+  if (!inline) {
+    console.log('');
+  }
+  console.log(chalk.bold.blue('Titanium AI Knowledge Manager'));
   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.');
+    console.log('Run this command from the project root.');
+    process.exit(1);
+  }
+  // Check for local vs global skills
+  const localSkillsPaths = {
+    'CLAUDE.md': join(projectDir, '.claude', 'skills'),
+    'GEMINI.md': join(projectDir, '.gemini', 'skills'),
+    'AGENTS.md': join(projectDir, '.agents', 'skills'),
+  };
+
+  const agentsSkillsDir = getAgentsSkillsDir();
+  const hasSkillsAt = (skillsDir) =>
+    skillsDir && SKILLS.some((skill) => existsSync(join(skillsDir, skill)));
+  const hasGlobalSkills = hasSkillsAt(agentsSkillsDir);
+  const hasAnyLocalSkills = Object.values(localSkillsPaths).some(hasSkillsAt);
+
+  // Verify skills are installed (either global or local)
+  if (!hasGlobalSkills && !hasAnyLocalSkills) {
+    console.log(chalk.red('Error: Skills not installed.'));
+    console.log(`${chalk.bold('Run:')} ${chalk.cyan('titools install')}`);
+    if (options?.verbose) {
+      console.log(
+        chalk.gray(
+          `Searched: ${agentsSkillsDir} | ./.agents/skills, ./.claude/skills, ./.gemini/skills`
+        )
+      );
+    }
     process.exit(1);
   }
 
@@ -58,67 +75,126 @@ export async function agentsCommand(projectPath, options) {
   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' },
-          ],
+  // Define potential files
+  const possibleFiles = [
+    { name: 'AGENTS.md', value: 'AGENTS.md' },
+    { name: 'CLAUDE.md', value: 'CLAUDE.md' },
+    { name: 'GEMINI.md', value: 'GEMINI.md' },
+  ];
+
+  // Get current state of files
+  const fileStates = possibleFiles.map(f => {
+    const filePath = join(projectDir, f.value);
+    return {
+      ...f,
+      exists: existsSync(filePath),
+      hasBlock: blockExists(filePath)
+    };
+  });
+
+  // Determine which files to process
+  let selectedFiles = [];
+
+  if (effectiveOptions.onlyExisting) {
+    selectedFiles = fileStates.filter(f => f.exists).map(f => f.value);
+  } else if (effectiveOptions.force) {
+    selectedFiles = fileStates.filter(f => f.hasBlock).map(f => f.value);
+    if (selectedFiles.length === 0) selectedFiles = ['CLAUDE.md'];
+  } else {
+    try {
+      selectedFiles = await checkbox({
+        message: 'Select instruction files to sync:',
+        choices: [
+          ...fileStates.map(f => ({
+            name: f.name,
+            value: f.value,
+            checked: f.hasBlock
+          })),
+          new Separator(' ')
+        ],
+        shortcuts: { invert: null },
+        theme: {
+          style: {
+            renderSelectedChoices: () => '',
+          },
         },
-      ]);
-      filesToUpdate = [answers.ai];
+      });
+    } catch (error) {
+      console.log('\nCancelled.');
+      process.exit(0);
     }
   }
 
-  // Update each file
+  // Handle cancellation
+  if (selectedFiles.includes('cancel')) {
+    console.log('Cancelled.');
+    return;
+  }
+
+  // If nothing selected, proceed to remove knowledge from all existing files
+  if (selectedFiles.length === 0) {
+    console.log(chalk.yellow('No selection. Removing knowledge index from all files.'));
+  }
+
+  // Process each file
   const spinner = ora();
   const updated = [];
+  const removed = [];
 
-  for (const filename of filesToUpdate) {
+  for (const f of fileStates) {
+    const filename = f.value;
     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}`);
+    const isSelected = selectedFiles.includes(filename);
+
+    if (isSelected) {
+      // ADD or UPDATE
+      spinner.start(`${f.hasBlock ? 'Updating' : 'Adding'} knowledge index in ${filename}...`);
+
+      try {
+        if (!f.exists && !existsSync(filePath)) {
+          writeFileSync(filePath, `# ${filename}\n\n`, 'utf8');
+        }
+
+        let rootPath = '~/.agents/skills';
+        const localPath = localSkillsPaths[filename];
+        if (localPath && existsSync(localPath)) {
+          rootPath = `./${filename === 'CLAUDE.md' ? '.claude' : filename === 'GEMINI.md' ? '.gemini' : '.agents'}/skills`;
+        } else {
+          if (filename === 'CLAUDE.md') rootPath = '~/.claude/skills';
+          if (filename === 'GEMINI.md') rootPath = '~/.gemini/skills';
+        }
+
+        addOrUpdateBlock(filePath, rootPath);
+        spinner.succeed(`${filename} updated`);
+        updated.push(filename);
+      } catch (error) {
+        spinner.fail(`Failed to sync ${filename}: ${error.message}`);
+      }
+    } else if (f.hasBlock) {
+      // REMOVE block if it was previously there but now unselected
+      spinner.start(`Removing knowledge index from ${filename}...`);
+      try {
+        removeOldBlock(filePath);
+        spinner.succeed(`${filename} knowledge index removed`);
+        removed.push(filename);
+      } catch (error) {
+        spinner.fail(`Failed to clean ${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.`
-    );
+  if (!inline) {
+    console.log('');
+  }
+  if (updated.length > 0 || removed.length > 0) {
+    const updatedText = updated.length > 0 ? ` Updated: ${updated.join(', ')}` : '';
+    const cleanedText = removed.length > 0 ? ` Cleaned: ${removed.join(', ')}` : '';
+    console.log('');
+    console.log(chalk.green(`✓ sync complete!${updatedText}${cleanedText}`));
+  } else {
+    console.log(chalk.yellow('No changes made.'));
+  }
+  if (!inline) {
     console.log('');
   }
 }