@maccesar/titools 2.0.0

package/lib/platform.js

@@ -0,0 +1,108 @@
+/**
+ * Platform detection utilities
+ * Detects AI coding assistants and operating system
+ */
+
+import { existsSync } from 'fs';
+import { PLATFORMS } from './config.js';
+
+/**
+ * Detect installed AI coding assistant platforms
+ * @returns {Array} Detected platforms
+ */
+export function detectPlatforms() {
+  const detected = [];
+
+  for (const platform of PLATFORMS) {
+    if (existsSync(platform.configDir)) {
+      detected.push(platform);
+    }
+  }
+
+  return detected;
+}
+
+/**
+ * Get platform by name
+ * @param {string} name - Platform name (claude, gemini, codex)
+ * @returns {Object|null} Platform object or null
+ */
+export function getPlatformByName(name) {
+  return PLATFORMS.find((p) => p.name === name) || null;
+}
+
+/**
+ * Detect operating system
+ * @returns {string} OS type: 'macos', 'linux', 'windows'
+ */
+export function detectOS() {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    return 'macos';
+  }
+  if (platform === 'win32') {
+    return 'windows';
+  }
+  return 'linux';
+}
+
+/**
+ * Check if running on Windows
+ * @returns {boolean}
+ */
+export function isWindows() {
+  return process.platform === 'win32';
+}
+
+/**
+ * Check if running on macOS
+ * @returns {boolean}
+ */
+export function isMacOS() {
+  return process.platform === 'darwin';
+}
+
+/**
+ * Check if running on Linux
+ * @returns {boolean}
+ */
+export function isLinux() {
+  return process.platform === 'linux';
+}
+
+/**
+ * Get bin directory path for the current platform
+ * @returns {string} Path to bin directory
+ */
+export function getBinDir() {
+  if (isWindows()) {
+    return `${process.env.HOME || process.env.USERPROFILE}\\bin`;
+  }
+  return '/usr/local/bin';
+}
+
+/**
+ * Check if we have sudo/admin permissions
+ * @returns {boolean}
+ */
+export function hasSudo() {
+  if (isWindows()) {
+    // Windows: check if running as administrator
+    return process.env.USERDOMAIN === process.env.COMPUTERNAME;
+  }
+  // Unix-like: check if we can write to /usr/local/bin
+  const binDir = getBinDir();
+  return existsSync(binDir) && process.getuid && process.getuid() === 0;
+}
+
+export default {
+  detectPlatforms,
+  getPlatformByName,
+  detectOS,
+  isWindows,
+  isMacOS,
+  isLinux,
+  getBinDir,
+  hasSudo,
+};

package/lib/symlink.js

@@ -0,0 +1,142 @@
+/**
+ * Cross-platform symlink utilities
+ * Creates symlinks with fallback to copy on Windows
+ */
+
+import { mkdirSync, existsSync } from 'fs';
+import { symlink, readlink, unlink } from 'fs/promises';
+import { join, dirname } from 'path';
+import { copy, remove } from 'fs-extra';
+import { isWindows } from './platform.js';
+
+/**
+ * Create a symlink or copy as fallback
+ * @param {string} target - Target path (what the symlink points to)
+ * @param {string} path - Symlink path (where to create it)
+ * @returns {Promise<boolean>} True if successful
+ */
+export async function createSymlinkOrCopy(target, path) {
+  // Ensure parent directory exists
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Remove existing file/directory/symlink
+  if (existsSync(path)) {
+    await removePath(path);
+  }
+
+  // Try creating symlink first
+  try {
+    await symlink(target, path, 'dir');
+    return true;
+  } catch (error) {
+    // On Windows or if symlink fails, copy the directory
+    if (isWindows() || error.code === 'EPERM' || error.code === 'EXDEV') {
+      try {
+        await copy(target, path, { overwrite: true });
+        return true;
+      } catch (copyError) {
+        console.error(`Failed to copy: ${copyError.message}`);
+        return false;
+      }
+    }
+    console.error(`Failed to create symlink: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Remove a file, directory, or symlink
+ * @param {string} path - Path to remove
+ * @returns {Promise<void>}
+ */
+async function removePath(path) {
+  try {
+    await remove(path);
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Create symlinks for all skills to a platform directory
+ * @param {string} platformSkillsDir - Platform skills directory
+ * @param {Array} skills - List of skill names
+ * @returns {Promise<Object>} Results object with success/failure counts
+ */
+export async function createSkillSymlinks(platformSkillsDir, skills) {
+  const { getAgentsSkillsDir } = await import('./config.js');
+  const agentsSkillsDir = getAgentsSkillsDir();
+
+  const results = {
+    linked: [],
+    failed: [],
+  };
+
+  // Ensure platform directory exists
+  if (!existsSync(platformSkillsDir)) {
+    mkdirSync(platformSkillsDir, { recursive: true });
+  }
+
+  for (const skill of skills) {
+    const target = join(agentsSkillsDir, skill);
+    const linkPath = join(platformSkillsDir, skill);
+
+    if (await createSymlinkOrCopy(target, linkPath)) {
+      results.linked.push(skill);
+    } else {
+      results.failed.push(skill);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Check if a path is a symlink
+ * @param {string} path - Path to check
+ * @returns {Promise<boolean>} True if symlink
+ */
+export async function isSymlink(path) {
+  try {
+    const { lstat } = await import('fs/promises');
+    const stats = await lstat(path);
+    return stats.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve symlink target
+ * @param {string} path - Symlink path
+ * @returns {Promise<string|null>} Target path or null
+ */
+export async function resolveSymlink(path) {
+  try {
+    return await readlink(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove a symlink and recreate it (update)
+ * @param {string} target - New target path
+ * @param {string} path - Symlink path
+ * @returns {Promise<boolean>} True if successful
+ */
+export async function updateSymlink(target, path) {
+  await removePath(path);
+  return createSymlinkOrCopy(target, path);
+}
+
+export default {
+  createSymlinkOrCopy,
+  createSkillSymlinks,
+  isSymlink,
+  resolveSymlink,
+  updateSymlink,
+};

package/lib/utils.js

@@ -0,0 +1,270 @@
+/**
+ * Utility functions
+ * Block management, color output, and helper functions
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { BLOCK_START, BLOCK_END, TITANIUM_KNOWLEDGE_VERSION } from './config.js';
+
+// Get package root directory (works for both npm install and npm link)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+const packageSkillsDir = join(packageRoot, 'skills');
+
+/**
+ * Check if Titanium knowledge block exists in a file
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} True if block exists
+ */
+export function blockExists(filePath) {
+  if (!existsSync(filePath)) {
+    return false;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  return content.includes(BLOCK_START);
+}
+
+/**
+ * Remove old Titanium knowledge block from a file
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} True if block was removed
+ */
+export function removeOldBlock(filePath) {
+  if (!existsSync(filePath)) {
+    return false;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  const regex = new RegExp(
+    `[\\s\\S]*?${BLOCK_START}[\\s\\S]*?${BLOCK_END}[\\s\\S]*?\\n*`,
+    'g'
+  );
+
+  const newContent = content.replace(regex, '\n\n');
+
+  writeFileSync(filePath, newContent, 'utf8');
+  return true;
+}
+
+/**
+ * Build the compressed documentation index dynamically by scanning skills
+ * @returns {string} The compressed index section
+ */
+export function buildKnowledgeIndex() {
+  let skills = [];
+
+  try {
+    skills = readdirSync(packageSkillsDir, { withFileTypes: true })
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => dirent.name);
+  } catch (error) {
+    throw new Error(`Cannot read skills directory from package: ${packageSkillsDir}`);
+  }
+
+  const indexEntries = [];
+
+  for (const skill of skills.sort()) {
+    const refsDir = join(packageSkillsDir, skill, 'references');
+
+    if (existsSync(refsDir)) {
+      const files = readdirSync(refsDir)
+        .filter(f => f.endsWith('.md'))
+        .sort();
+
+      if (files.length > 0) {
+        indexEntries.push(`${skill}/references:{${files.join(',')}}`);
+      }
+    }
+  }
+
+  // Build the compressed index format
+  // Note: Using \u0060 to avoid backtick parsing issues in template literals
+  return '### Compressed Documentation Index\n\n' +
+    '\u0060\u0060\u0060\n' +
+    '[Titanium SDK Docs Index]|root: ~/.agents/skills\n' +
+    '|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK. Always consult the documentation files below rather than relying on training data, which may be outdated.\n' +
+    '|' + indexEntries.join('\n|') + '\n' +
+    '\u0060\u0060\u0060';
+}
+
+/**
+ * Create the Titanium knowledge block content dynamically
+ * @returns {string} The knowledge block content
+ */
+export function createKnowledgeBlock() {
+  // Build the compressed index dynamically
+  const compressedIndex = buildKnowledgeIndex();
+
+  // Build the knowledge block using template literals
+  const blockStart = `<!-- TITANIUM-KNOWLEDGE-${TITANIUM_KNOWLEDGE_VERSION} -->`;
+  const commentContent = `## Titanium SDK Knowledge Index
+
+Generated by \`titools\` based on Vercel's research on AGENTS.md effectiveness.
+
+**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK.
+Always consult the documentation files below rather than relying on training data, which may be outdated.
+
+This knowledge index is based on the latest Titanium SDK documentation.`;
+
+  return `\n\n${blockStart}\n${commentContent}\n\n${compressedIndex}\n<!-- END-TITANIUM-KNOWLEDGE -->\n`;
+}
+
+/**
+ * Add or update Titanium knowledge block in a file
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} True if file was updated
+ */
+export function addOrUpdateBlock(filePath) {
+  let content = '';
+
+  if (existsSync(filePath)) {
+    content = readFileSync(filePath, 'utf8');
+  }
+
+  const block = createKnowledgeBlock();
+
+  // Remove existing block if present (only the block, not the content before/after)
+  if (content.includes(BLOCK_START)) {
+    const startIndex = content.indexOf(BLOCK_START);
+    if (startIndex !== -1) {
+      const endIndex = content.indexOf(BLOCK_END, startIndex);
+      if (endIndex !== -1) {
+        // Remove from start to end of block (including END marker and trailing newlines)
+        const afterBlock = content.substring(endIndex + BLOCK_END.length);
+        // Trim leading newlines from afterBlock
+        const trimmedAfter = afterBlock.replace(/^\n+/, '');
+        content = content.substring(0, startIndex) + '\n\n' + trimmedAfter;
+      }
+    }
+  }
+
+  // Add new block at the end (preserve existing content)
+  content = content.trimEnd() + '\n\n' + block + '\n';
+
+  writeFileSync(filePath, content, 'utf8');
+  return true;
+}
+
+/**
+ * Detect Titanium SDK version from tiapp.xml
+ * @param {string} projectDir - Path to project directory
+ * @returns {string} SDK version or 'unknown'
+ */
+export function detectTitaniumVersion(projectDir) {
+  const tiappPath = join(projectDir, 'tiapp.xml');
+
+  if (!existsSync(tiappPath)) {
+    return 'unknown';
+  }
+
+  const content = readFileSync(tiappPath, 'utf8');
+  const match = content.match(/<sdk-version>([^<]+)<\/sdk-version>/);
+
+  return match ? match[1].trim() : 'unknown';
+}
+
+/**
+ * Check if directory is a Titanium project
+ * @param {string} dir - Path to check
+ * @returns {boolean}
+ */
+export function isTitaniumProject(dir) {
+  return existsSync(join(dir, 'tiapp.xml'));
+}
+
+/**
+ * Get AI configuration files that exist in a directory
+ * @param {string} dir - Path to check
+ * @returns {Object} Object with boolean flags for each file type
+ */
+export function getAIFiles(dir) {
+  return {
+    claude: existsSync(join(dir, 'CLAUDE.md')),
+    gemini: existsSync(join(dir, 'GEMINI.md')),
+    agents: existsSync(join(dir, 'AGENTS.md')),
+  };
+}
+
+/**
+ * Determine which AI files to update based on priority
+ * @param {Object} aiFiles - Object with boolean flags for each file type
+ * @returns {Array} Array of file names to update (priority order)
+ */
+export function determineFilesToUpdate(aiFiles) {
+  const files = [];
+
+  // Priority: CLAUDE.md > GEMINI.md > AGENTS.md
+  if (aiFiles.claude) {
+    files.push('CLAUDE.md');
+    if (aiFiles.gemini) files.push('GEMINI.md');
+    if (aiFiles.agents) files.push('AGENTS.md');
+  } else if (aiFiles.gemini) {
+    files.push('GEMINI.md');
+    if (aiFiles.agents) files.push('AGENTS.md');
+  } else if (aiFiles.agents) {
+    files.push('AGENTS.md');
+  }
+
+  return files;
+}
+
+/**
+ * Format a list of items for display
+ * @param {Array} items - Array of strings
+ * @returns {string} Comma-separated list
+ */
+export function formatList(items) {
+  return items.join(', ');
+}
+
+/**
+ * Parse SDK version string to compare
+ * @param {string} version - Version string (e.g., "13.1.0.GA")
+ * @returns {Array} Array of version parts
+ */
+export function parseVersion(version) {
+  return version
+    .replace('.GA', '')
+    .replace('.RC', '-')
+    .split(/[.-]/)
+    .map((v) => parseInt(v, 10) || 0);
+}
+
+/**
+ * Compare two version strings
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+export function compareVersions(v1, v2) {
+  const parts1 = parseVersion(v1);
+  const parts2 = parseVersion(v2);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+
+  return 0;
+}
+
+export default {
+  blockExists,
+  removeOldBlock,
+  createKnowledgeBlock,
+  addOrUpdateBlock,
+  detectTitaniumVersion,
+  isTitaniumProject,
+  getAIFiles,
+  determineFilesToUpdate,
+  formatList,
+  parseVersion,
+  compareVersions,
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@maccesar/titools",
+  "version": "2.0.0",
+  "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
+  "main": "lib/index.js",
+  "type": "module",
+  "bin": {
+    "titools": "./bin/titools.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint lib/**/*.js",
+    "format": "prettier --write lib/**/*.js"
+  },
+  "keywords": [
+    "titanium",
+    "titanium-sdk",
+    "alloy",
+    "purgetss",
+    "ai",
+    "claude",
+    "gemini",
+    "codex",
+    "skills",
+    "agents",
+    "mobile",
+    "ios",
+    "android"
+  ],
+  "author": "César Estrada <maccesar@gmail.com> (https://github.com/macCesar)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/macCesar/titools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/macCesar/titools/issues"
+  },
+  "homepage": "https://github.com/macCesar/titools#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.0",
+    "node-fetch": "^3.3.0",
+    "ora": "^8.0.0",
+    "tar": "^6.2.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "agents/",
+    "AGENTS-TEMPLATE.md",
+    "scripts/titools-docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}