@maccesar/titools 2.0.0

package/lib/commands/update.js

@@ -0,0 +1,159 @@
+/**
+ * Update command
+ * Updates skills and docs to the latest version
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import {
+  PACKAGE_VERSION,
+  REPO_URL,
+  REPO_API_URL,
+  SKILLS,
+  AGENTS,
+} from '../config.js';
+import {
+  detectPlatforms,
+} from '../platform.js';
+import {
+  installSkills,
+  installAgents,
+  installAgentsTemplate,
+  getLocalRepoDir,
+} from '../installer.js';
+import {
+  downloadRepoArchive,
+  checkForUpdate,
+} 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';
+
+/**
+ * Update command handler
+ */
+export async function updateCommand() {
+  console.log('');
+  console.log(chalk.bold.blue('Titanium SDK Skills Updater'));
+  console.log('');
+
+  const spinner = ora();
+
+  // Check for updates
+  spinner.start('Checking for updates...');
+
+  try {
+    const hasUpdate = await checkForUpdate(PACKAGE_VERSION);
+
+    if (!hasUpdate) {
+      spinner.info(`Already up to date (v${PACKAGE_VERSION})`);
+      console.log('');
+      console.log(chalk.green('✓'), 'Skills and agents are already at the latest version');
+      console.log('');
+      return;
+    }
+
+    spinner.succeed(`Update available!`);
+    console.log('');
+    console.log(chalk.gray(`Current: ${PACKAGE_VERSION}`));
+    console.log(chalk.gray(`Latest:  (from GitHub)`));
+    console.log('');
+
+    // Detect installed platforms
+    const detectedPlatforms = detectPlatforms();
+
+    if (detectedPlatforms.length === 0) {
+      console.log(chalk.yellow('No AI coding assistants detected.'));
+      console.log('Update will install skills to ~/.agents/skills/');
+      console.log('');
+    } else {
+      for (const platform of detectedPlatforms) {
+        console.log(chalk.green('✓'), platform.displayName);
+      }
+      console.log('');
+    }
+
+    // Download latest from GitHub
+    spinner.start('Downloading latest from GitHub...');
+
+    let repoDir = getLocalRepoDir();
+    let tempDir = null;
+
+    if (!repoDir) {
+      tempDir = await mkdtemp(join(tmpdir(), 'titanium-skills-'));
+      repoDir = await downloadRepoArchive(tempDir);
+    }
+
+    spinner.succeed('Downloaded from GitHub');
+
+    try {
+      // Install skills
+      spinner.start('Updating skills...');
+      const skillsResult = await installSkills(repoDir);
+      spinner.succeed(
+        `Skills: ${formatList(skillsResult.installed)}`
+      );
+
+      // Install agents
+      spinner.start('Updating agents...');
+      const agentsResult = await installAgents(repoDir);
+      if (agentsResult.installed.length > 0) {
+        spinner.succeed(
+          `Agents: ${formatList(agentsResult.installed)}`
+        );
+      } else {
+        spinner.info('No agents to update');
+      }
+
+      // Install AGENTS-TEMPLATE.md
+      spinner.start('Updating AGENTS-TEMPLATE.md...');
+      const templateInstalled = await installAgentsTemplate(repoDir);
+      if (templateInstalled) {
+        spinner.succeed('AGENTS-TEMPLATE.md updated');
+      } else {
+        spinner.warn('AGENTS-TEMPLATE.md not found');
+      }
+
+      // Update symlinks for detected platforms
+      for (const platform of detectedPlatforms) {
+        spinner.start(`Updating ${platform.displayName} symlinks...`);
+        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('✓ Update complete!'));
+      console.log('');
+      console.log(chalk.bold('▸'), 'Run in your Titanium project:', chalk.cyan('titools agents'));
+      console.log('');
+
+    } finally {
+      // Clean up temp directory
+      if (tempDir) {
+        await import('fs-extra').then(({ remove }) => remove(tempDir));
+      }
+    }
+
+  } catch (error) {
+    spinner.fail('Update failed');
+    console.error(chalk.red(error.message));
+    console.log('');
+    console.log('You can try manually installing from:');
+    console.log(chalk.cyan(REPO_URL));
+    process.exit(1);
+  }
+}
+
+export default updateCommand;

package/lib/config.js

@@ -0,0 +1,119 @@
+/**
+ * Configuration constants for Titanium SDK Skills
+ * Single source of truth for version management
+ */
+
+import path from 'path';
+import os from 'os';
+import { readFileSync } from 'fs';
+
+// Read package.json version dynamically
+let packageVersion = '1.7.0';
+try {
+  const packagePath = new URL('../package.json', import.meta.url);
+  const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+  packageVersion = pkg.version;
+} catch {
+  // Use default version if package.json not found
+}
+
+// Version management
+export const PACKAGE_VERSION = packageVersion;
+export const TITANIUM_KNOWLEDGE_VERSION = `v${PACKAGE_VERSION}`;
+export const BLOCK_START = `<!-- TITANIUM-KNOWLEDGE-${TITANIUM_KNOWLEDGE_VERSION} -->`;
+export const BLOCK_END = '<!-- END-TITANIUM-KNOWLEDGE -->';
+
+// Repository configuration
+export const REPO_URL = 'https://github.com/macCesar/titools';
+export const REPO_RAW_URL = 'https://raw.githubusercontent.com/macCesar/titools/main';
+export const REPO_API_URL = 'https://api.github.com/repos/macCesar/titools';
+
+// Skills to install
+export const SKILLS = [
+  'alloy-expert',
+  'purgetss',
+  'ti-ui',
+  'ti-howtos',
+  'ti-guides',
+  'alloy-guides',
+  'alloy-howtos',
+];
+
+// Agents to install
+export const AGENTS = [
+  'ti-researcher',
+];
+
+// Directory paths
+export const getAgentsDir = () => path.join(os.homedir(), '.agents');
+export const getAgentsSkillsDir = () => path.join(getAgentsDir(), 'skills');
+export const getClaudeAgentsDir = () => path.join(os.homedir(), '.claude', 'agents');
+export const getClaudeSkillsDir = () => path.join(os.homedir(), '.claude', 'skills');
+export const getGeminiSkillsDir = () => path.join(os.homedir(), '.gemini', 'skills');
+export const getCodexSkillsDir = () => path.join(os.homedir(), '.codex', 'skills');
+
+// AI platform detection
+export const PLATFORMS = [
+  {
+    name: 'claude',
+    displayName: 'Claude Code',
+    skillsDir: getClaudeSkillsDir(),
+    configDir: path.join(os.homedir(), '.claude'),
+  },
+  {
+    name: 'gemini',
+    displayName: 'Gemini CLI',
+    skillsDir: getGeminiSkillsDir(),
+    configDir: path.join(os.homedir(), '.gemini'),
+  },
+  {
+    name: 'codex',
+    displayName: 'Codex CLI',
+    skillsDir: getCodexSkillsDir(),
+    configDir: path.join(os.homedir(), '.codex'),
+  },
+];
+
+// Files to install
+export const AGENTS_TEMPLATE_FILE = 'AGENTS-TEMPLATE.md';
+export const TI_DOCS_INDEX_SCRIPT = 'ti-docs-index';
+
+// AI file priorities (higher = more priority)
+export const AI_FILE_PRIORITIES = {
+  'CLAUDE.md': 3,
+  'GEMINI.md': 2,
+  'AGENTS.md': 1,
+};
+
+// Titanium project detection
+export const TITANIUM_PROJECT_FILE = 'tiapp.xml';
+
+// API configuration
+export const GITHUB_API_HEADERS = {
+  Accept: 'application/vnd.github.v3+json',
+  'User-Agent': '@maccesar/titanium-skills',
+};
+
+export default {
+  PACKAGE_VERSION,
+  TITANIUM_KNOWLEDGE_VERSION,
+  BLOCK_START,
+  BLOCK_END,
+  REPO_URL,
+  REPO_RAW_URL,
+  REPO_API_URL,
+  SKILLS,
+  AGENTS,
+  getAgentsDir,
+  getAgentsSkillsDir,
+  getClaudeAgentsDir,
+  getClaudeSkillsDir,
+  getGeminiSkillsDir,
+  getCodexSkillsDir,
+  PLATFORMS,
+  AGENTS_TEMPLATE_FILE,
+  TI_DOCS_INDEX_SCRIPT,
+  AI_FILE_PRIORITIES,
+  TITANIUM_PROJECT_FILE,
+  GITHUB_API_HEADERS,
+};

package/lib/downloader.js

@@ -0,0 +1,153 @@
+/**
+ * GitHub download utilities
+ * Fetches releases and archives from GitHub
+ */
+
+import { createWriteStream, existsSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join, dirname } from 'path';
+import { pipeline } from 'stream/promises';
+import { unlink } from 'fs/promises';
+import tar from 'tar';
+import fetch from 'node-fetch';
+import { REPO_API_URL, REPO_RAW_URL, GITHUB_API_HEADERS } from './config.js';
+
+/**
+ * Fetch latest release info from GitHub API
+ * @returns {Promise<Object>} Release information
+ */
+export async function fetchLatestRelease() {
+  const response = await fetch(
+    `${REPO_API_URL}/releases/latest`,
+    {
+      headers: GITHUB_API_HEADERS,
+    }
+  );
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch release info: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Fetch latest version from GitHub
+ * @returns {Promise<string>} Latest version tag
+ */
+export async function fetchLatestVersion() {
+  const release = await fetchLatestRelease();
+  return release.tag_name;
+}
+
+/**
+ * Download a file from URL to local path
+ * @param {string} url - URL to download
+ * @param {string} destPath - Destination path
+ * @returns {Promise<void>}
+ */
+export async function downloadFile(url, destPath) {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to download: ${response.statusText}`);
+  }
+
+  // Ensure directory exists
+  const dir = dirname(destPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Download with progress indication
+  await pipeline(response.body, createWriteStream(destPath));
+}
+
+/**
+ * Download and extract GitHub repository archive
+ * @param {string} destDir - Destination directory
+ * @param {string} ref - Git ref (branch, tag, commit)
+ * @returns {Promise<string>} Path to extracted directory
+ */
+export async function downloadRepoArchive(destDir, ref = 'main') {
+  const archiveUrl = `${REPO_API_URL}/tarball/${ref}`;
+  const tempFile = join(tmpdir(), `titanium-skills-${Date.now()}.tar.gz`);
+
+  try {
+    // Download archive
+    await downloadFile(archiveUrl, tempFile);
+
+    // Extract archive
+    await tar.extract({
+      file: tempFile,
+      cwd: destDir,
+      strip: 1, // Remove top-level directory
+    });
+
+    return destDir;
+  } finally {
+    // Clean up temp file
+    if (existsSync(tempFile)) {
+      await unlink(tempFile);
+    }
+  }
+}
+
+/**
+ * Download a single file from GitHub raw content
+ * @param {string} filePath - Path in repository (e.g., 'AGENTS-TEMPLATE.md')
+ * @param {string} destPath - Local destination path
+ * @param {string} ref - Git ref (branch, tag, commit)
+ * @returns {Promise<void>}
+ */
+export async function downloadRawFile(filePath, destPath, ref = 'main') {
+  const url = `${REPO_RAW_URL}/${ref}/${filePath}`;
+
+  // Ensure directory exists
+  const dir = dirname(destPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  await downloadFile(url, destPath);
+}
+
+/**
+ * Check if an update is available
+ * @param {string} currentVersion - Current version
+ * @returns {Promise<boolean>} True if update available
+ */
+export async function checkForUpdate(currentVersion) {
+  try {
+    const latestVersion = await fetchLatestVersion();
+    // Remove 'v' prefix if present
+    const latest = latestVersion.replace(/^v/, '');
+    const current = currentVersion.replace(/^v/, '');
+
+    // Simple version comparison
+    const latestParts = latest.split('.').map((v) => parseInt(v, 10));
+    const currentParts = current.split('.').map((v) => parseInt(v, 10));
+
+    for (let i = 0; i < Math.max(latestParts.length, currentParts.length); i++) {
+      const l = latestParts[i] || 0;
+      const c = currentParts[i] || 0;
+
+      if (l > c) return true;
+      if (l < c) return false;
+    }
+
+    return false;
+  } catch {
+    // If check fails, assume no update
+    return false;
+  }
+}
+
+export default {
+  fetchLatestRelease,
+  fetchLatestVersion,
+  downloadFile,
+  downloadRepoArchive,
+  downloadRawFile,
+  checkForUpdate,
+};

package/lib/installer.js

@@ -0,0 +1,253 @@
+/**
+ * File installation utilities
+ * Installs skills, agents, and templates to their respective directories
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+} from 'fs';
+import { join } from 'path';
+import { remove, copy } from 'fs-extra';
+import {
+  SKILLS,
+  AGENTS,
+  getAgentsSkillsDir,
+  getClaudeAgentsDir,
+  getAgentsDir,
+  AGENTS_TEMPLATE_FILE,
+} from './config.js';
+
+/**
+ * Recursively copy a directory
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ * @returns {Promise<void>}
+ */
+export async function copyDirectory(src, dest) {
+  // Create destination if it doesn't exist
+  if (!existsSync(dest)) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  // Use fs-extra copy for recursive directory copy
+  await copy(src, dest, { overwrite: true });
+}
+
+/**
+ * Remove existing file or directory
+ * @param {string} target - Path to remove
+ * @returns {Promise<void>}
+ */
+export async function removeExisting(target) {
+  if (existsSync(target)) {
+    await remove(target);
+  }
+}
+
+/**
+ * Install a single skill to the agents skills directory
+ * @param {string} repoDir - Repository directory
+ * @param {string} skillName - Name of the skill
+ * @returns {Promise<boolean>} True if installed successfully
+ */
+export async function installSkill(repoDir, skillName) {
+  const skillsDir = getAgentsSkillsDir();
+  const skillSrc = join(repoDir, 'skills', skillName);
+  const skillDest = join(skillsDir, skillName);
+
+  // Create skills directory if needed
+  if (!existsSync(skillsDir)) {
+    mkdirSync(skillsDir, { recursive: true });
+  }
+
+  // Check if source exists
+  if (!existsSync(skillSrc)) {
+    return false;
+  }
+
+  // Remove existing if present
+  if (existsSync(skillDest)) {
+    await remove(skillDest);
+  }
+
+  // Copy skill directory
+  await copyDirectory(skillSrc, skillDest);
+  return true;
+}
+
+/**
+ * Install all skills to the agents skills directory
+ * @param {string} repoDir - Repository directory
+ * @returns {Promise<Object>} Results object with success/failure counts
+ */
+export async function installSkills(repoDir) {
+  const results = {
+    installed: [],
+    failed: [],
+  };
+
+  for (const skill of SKILLS) {
+    if (await installSkill(repoDir, skill)) {
+      results.installed.push(skill);
+    } else {
+      results.failed.push(skill);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Install a single agent to Claude agents directory
+ * @param {string} repoDir - Repository directory
+ * @param {string} agentName - Name of the agent (without .md)
+ * @returns {Promise<boolean>} True if installed successfully
+ */
+export async function installAgent(repoDir, agentName) {
+  const agentsDir = getClaudeAgentsDir();
+  const agentSrc = join(repoDir, 'agents', `${agentName}.md`);
+  const agentDest = join(agentsDir, `${agentName}.md`);
+
+  // Create agents directory if needed
+  if (!existsSync(agentsDir)) {
+    mkdirSync(agentsDir, { recursive: true });
+  }
+
+  // Check if source exists
+  if (!existsSync(agentSrc)) {
+    return false;
+  }
+
+  // Remove existing if present
+  if (existsSync(agentDest)) {
+    await remove(agentDest);
+  }
+
+  // Copy agent file
+  copyFileSync(agentSrc, agentDest);
+  return true;
+}
+
+/**
+ * Install all agents to Claude agents directory
+ * @param {string} repoDir - Repository directory
+ * @returns {Promise<Object>} Results object with success/failure counts
+ */
+export async function installAgents(repoDir) {
+  const results = {
+    installed: [],
+    failed: [],
+  };
+
+  for (const agent of AGENTS) {
+    if (await installAgent(repoDir, agent)) {
+      results.installed.push(agent);
+    } else {
+      results.failed.push(agent);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Install AGENTS-TEMPLATE.md to the agents directory
+ * @param {string} repoDir - Repository directory
+ * @returns {Promise<boolean>} True if installed successfully
+ */
+export async function installAgentsTemplate(repoDir) {
+  const agentsDir = getAgentsDir();
+  const templateSrc = join(repoDir, AGENTS_TEMPLATE_FILE);
+  const templateDest = join(agentsDir, AGENTS_TEMPLATE_FILE);
+
+  // Create agents directory if needed
+  if (!existsSync(agentsDir)) {
+    mkdirSync(agentsDir, { recursive: true });
+  }
+
+  // Check if source exists
+  if (!existsSync(templateSrc)) {
+    return false;
+  }
+
+  // Copy template file
+  copyFileSync(templateSrc, templateDest);
+  return true;
+}
+
+/**
+ * Install the ti-docs-index helper script
+ * @param {string} repoDir - Repository directory
+ * @param {string} binDir - Bin directory path
+ * @returns {Promise<boolean>} True if installed successfully
+ */
+export async function installTiDocsIndexScript(repoDir, binDir) {
+  const scriptSrc = join(repoDir, 'scripts', 'ti-docs-index');
+  const scriptDest = join(binDir, 'ti-docs-index');
+
+  // Check if source exists
+  if (!existsSync(scriptSrc)) {
+    return false;
+  }
+
+  // Create bin directory if needed
+  if (!existsSync(binDir)) {
+    try {
+      mkdirSync(binDir, { recursive: true });
+    } catch {
+      // If we can't create the bin dir, skip script installation
+      return false;
+    }
+  }
+
+  // Try to copy script file
+  try {
+    copyFileSync(scriptSrc, scriptDest);
+  } catch (error) {
+    // If we can't write to binDir (permission denied), skip script installation
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      return false;
+    }
+    throw error;
+  }
+
+  // Make executable (chmod +x)
+  try {
+    const { chmod } = await import('fs/promises');
+    await chmod(scriptDest, 0o755);
+  } catch {
+    // Ignore permission errors
+  }
+
+  return true;
+}
+
+/**
+ * Get the local repository directory if running from source
+ * @returns {string|null} Local repo directory or null
+ */
+export function getLocalRepoDir() {
+  const scriptDir = new URL('..', import.meta.url).pathname;
+  const skillsDir = join(scriptDir, 'skills');
+
+  if (existsSync(skillsDir)) {
+    return scriptDir;
+  }
+
+  return null;
+}
+
+export default {
+  copyDirectory,
+  removeExisting,
+  installSkill,
+  installSkills,
+  installAgent,
+  installAgents,
+  installAgentsTemplate,
+  installTiDocsIndexScript,
+  getLocalRepoDir,
+};