@maccesar/titools 2.4.1 → 2.5.0

package/bin/titools.js

@@ -12,6 +12,8 @@ import { agentsCommand } from '../lib/commands/agents.js';
 import { updateCommand } from '../lib/commands/update.js';
 import { uninstallCommand } from '../lib/commands/uninstall.js';
 import { autoUpdateCommand } from '../lib/commands/auto-update.js';
+import { statusCommand } from '../lib/commands/status.js';
+import { doctorCommand } from '../lib/commands/doctor.js';
 
 const program = new Command();
 
@@ -59,6 +61,18 @@ program
   .option('-s, --silent', 'Suppress all output except errors')
   .action(autoUpdateCommand);
 
+// Status command
+program
+  .command('status')
+  .description('Show installation status and linked platforms')
+  .action(statusCommand);
+
+// Doctor command
+program
+  .command('doctor')
+  .description('Check installation health and diagnose issues')
+  .action(doctorCommand);
+
 // Parse arguments
 program.parse();
 

package/lib/commands/auto-update.js

@@ -6,7 +6,10 @@
 
 import chalk from 'chalk';
 import ora from 'ora';
-import { execFileSync } from 'child_process';
+import { execFile as execFileCb } from 'child_process';
+import { promisify } from 'util';
+
+const execFile = promisify(execFileCb);
 import { existsSync } from 'fs';
 import { join, resolve } from 'path';
 import {
@@ -51,6 +54,7 @@ export async function autoUpdateCommand(options) {
 
   // Step 1: Check cache
   if (!shouldCheck(cacheDir)) {
+    log(chalk.green('✔'), `Up to date (v${PACKAGE_VERSION})`);
     return;
   }
 
@@ -81,16 +85,17 @@ export async function autoUpdateCommand(options) {
   }
 
   // Step 5: Update CLI (skip in dev mode)
+  spinner.succeed(`Update available: v${PACKAGE_VERSION} → ${latestVersion}`);
+
   if (isDevMode()) {
-    spinner.info(`Dev mode — skipping npm update (latest: ${latestVersion})`);
+    spinner.info(`Dev mode — skipping npm update`);
   } else {
-    spinner.start(`Updating titools v${PACKAGE_VERSION} → ${latestVersion}...`);
+    spinner.start(`Downloading and installing v${latestVersion}...`);
     try {
-      execFileSync('npm', ['update', '-g', '@maccesar/titools'], {
-        stdio: 'pipe',
+      await execFile('npm', ['update', '-g', '@maccesar/titools'], {
         timeout: 60000,
       });
-      spinner.succeed(`Updated to ${latestVersion}`);
+      spinner.succeed(`Updated to v${latestVersion}`);
     } catch (error) {
       spinner.fail(`npm update failed: ${error.message}`);
       return;

package/lib/commands/doctor.js

@@ -0,0 +1,194 @@
+/**
+ * Doctor command
+ * Diagnoses installation health (read-only)
+ */
+
+import chalk from 'chalk';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'fs';
+import { join } from 'path';
+import os from 'os';
+import {
+  SKILLS,
+  PACKAGE_VERSION,
+  TITANIUM_KNOWLEDGE_VERSION,
+  getAgentsSkillsDir,
+  getClaudeAgentsDir,
+  getConfigDir,
+  getPlatforms,
+} from '../config.js';
+import { hasHook } from '../hooks.js';
+import { readLastCheck } from '../cache.js';
+import { isTitaniumProject, blockExists } from '../utils.js';
+
+const CHECK = chalk.green('✓');
+const CROSS = chalk.red('✗');
+const WARN = chalk.yellow('⚠');
+
+function extractIndexVersion(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const match = content.match(/<!-- Version: (v[\d.]+) -->/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function doctorCommand() {
+  const homeDir = os.homedir();
+  const skillsDir = getAgentsSkillsDir(homeDir);
+  const agentsDir = getClaudeAgentsDir(homeDir);
+  const claudeDir = join(homeDir, '.claude');
+  const cacheDir = getConfigDir();
+  const cwd = process.cwd();
+
+  let issues = 0;
+  const symlinkIssues = [];
+
+  console.log('');
+  console.log(chalk.bold('Titanium SDK Skills Doctor'));
+  console.log('');
+  console.log('  Checking installation health...');
+  console.log('');
+
+  // CLI version
+  console.log(`  ${CHECK} CLI version: v${PACKAGE_VERSION}`);
+
+  // Skills check
+  const missingSkills = [];
+  for (const skill of SKILLS) {
+    if (!existsSync(join(skillsDir, skill))) {
+      missingSkills.push(skill);
+    }
+  }
+  const installedCount = SKILLS.length - missingSkills.length;
+  if (missingSkills.length === 0) {
+    console.log(`  ${CHECK} Skills: ${installedCount}/${SKILLS.length} installed in ~/.agents/skills/`);
+  } else {
+    console.log(`  ${CROSS} Skills: ${installedCount}/${SKILLS.length} installed in ~/.agents/skills/ (missing: ${missingSkills.join(', ')})`);
+    issues += missingSkills.length;
+  }
+
+  // Agent check
+  const agentPath = join(agentsDir, 'ti-pro.md');
+  if (existsSync(agentPath)) {
+    console.log(`  ${CHECK} Agent: ti-pro installed`);
+  } else {
+    console.log(`  ${CROSS} Agent: ti-pro not found`);
+    issues++;
+  }
+
+  // Hook check
+  if (hasHook(claudeDir)) {
+    console.log(`  ${CHECK} Hook: SessionStart configured`);
+  } else {
+    console.log(`  ${CROSS} Hook: SessionStart not configured`);
+    issues++;
+  }
+
+  // Cache check
+  const lastCheck = readLastCheck(cacheDir);
+  if (lastCheck) {
+    const hoursAgo = Math.round((Date.now() - lastCheck.lastCheck) / (1000 * 60 * 60));
+    const timeLabel = hoursAgo < 1 ? 'less than an hour ago' : `${hoursAgo} hour${hoursAgo === 1 ? '' : 's'} ago`;
+    console.log(`  ${CHECK} Cache: last check ${timeLabel}`);
+  } else {
+    console.log(`  ${WARN} Cache: no check recorded`);
+  }
+
+  // Platforms
+  console.log('');
+  console.log('  Platforms:');
+  const platforms = getPlatforms(homeDir);
+  for (const platform of platforms) {
+    const missing = [];
+    const broken = [];
+
+    for (const skill of SKILLS) {
+      const linkPath = join(platform.skillsDir, skill);
+      try {
+        const stat = lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+          // Check if target exists
+          if (!existsSync(linkPath)) {
+            broken.push(skill);
+          }
+        }
+        // exists (symlink or directory), count as linked
+      } catch {
+        missing.push(skill);
+      }
+    }
+
+    const linkedCount = SKILLS.length - missing.length - broken.length;
+
+    if (missing.length === 0 && broken.length === 0) {
+      console.log(`    ${CHECK} ${platform.displayName}: ${SKILLS.length}/${SKILLS.length} skills linked`);
+    } else {
+      const problems = [];
+      if (missing.length > 0) problems.push(`missing: ${missing.join(', ')}`);
+      if (broken.length > 0) problems.push(`broken: ${broken.join(', ')}`);
+      console.log(`    ${CROSS} ${platform.displayName}: ${linkedCount}/${SKILLS.length} skills linked (${problems.join('; ')})`);
+      issues += missing.length + broken.length;
+
+      // Collect symlink issues for detailed report
+      for (const skill of broken) {
+        symlinkIssues.push(`${CROSS} ~/${platform.name === 'claude' ? '.claude' : `.${platform.name}`}/skills/${skill} → broken symlink (target missing)`);
+      }
+      for (const skill of missing) {
+        symlinkIssues.push(`${CROSS} ~/${platform.name === 'claude' ? '.claude' : `.${platform.name}`}/skills/${skill} → not found`);
+      }
+    }
+  }
+
+  // Symlink issues detail
+  if (symlinkIssues.length > 0) {
+    console.log('');
+    console.log(`  ${WARN} Symlink issues:`);
+    for (const issue of symlinkIssues) {
+      console.log(`    ${issue}`);
+    }
+  }
+
+  // Project check
+  if (isTitaniumProject(cwd)) {
+    console.log('');
+    console.log('  Project:');
+
+    const mdFiles = ['CLAUDE.md', 'GEMINI.md', 'AGENTS.md'];
+    for (const file of mdFiles) {
+      const filePath = join(cwd, file);
+      if (!existsSync(filePath)) {
+        // Not an issue if file doesn't exist — it's optional
+        continue;
+      }
+
+      if (blockExists(filePath)) {
+        const version = extractIndexVersion(filePath);
+        if (version === TITANIUM_KNOWLEDGE_VERSION) {
+          console.log(`    ${CHECK} ${file}: Knowledge Index present (${version})`);
+        } else if (version) {
+          console.log(`    ${CROSS} ${file}: Knowledge Index outdated (${version})`);
+          issues++;
+        } else {
+          console.log(`    ${CHECK} ${file}: Knowledge Index present`);
+        }
+      } else {
+        console.log(`    ${CROSS} ${file}: no Knowledge Index`);
+        issues++;
+      }
+    }
+  }
+
+  // Summary
+  console.log('');
+  if (issues === 0) {
+    console.log(chalk.green(`  No issues found.`));
+  } else {
+    console.log(chalk.yellow(`  ${issues} issue${issues === 1 ? '' : 's'} found. Run 'titools install' to fix.`));
+  }
+  console.log('');
+}
+
+export default { doctorCommand };

package/lib/commands/status.js

@@ -0,0 +1,136 @@
+/**
+ * Status command
+ * Shows a quick overview of what's installed (read-only)
+ */
+
+import chalk from 'chalk';
+import { existsSync, readdirSync, lstatSync, readFileSync } from 'fs';
+import { join } from 'path';
+import os from 'os';
+import {
+  SKILLS,
+  PACKAGE_VERSION,
+  getAgentsSkillsDir,
+  getClaudeAgentsDir,
+  getConfigDir,
+  getPlatforms,
+  BLOCK_START,
+} from '../config.js';
+import { hasHook } from '../hooks.js';
+import { readLastCheck } from '../cache.js';
+import { isTitaniumProject, detectTitaniumVersion, blockExists } from '../utils.js';
+
+const CHECK = chalk.green('✓');
+const CROSS = chalk.red('✗');
+
+function countInstalledSkills(skillsDir) {
+  let count = 0;
+  for (const skill of SKILLS) {
+    if (existsSync(join(skillsDir, skill))) {
+      count++;
+    }
+  }
+  return count;
+}
+
+function countLinkedSkills(platformSkillsDir) {
+  let count = 0;
+  for (const skill of SKILLS) {
+    const linkPath = join(platformSkillsDir, skill);
+    try {
+      lstatSync(linkPath);
+      count++;
+    } catch {
+      // not found
+    }
+  }
+  return count;
+}
+
+function formatLastCheck(data) {
+  if (!data) return chalk.gray('never');
+  const date = new Date(data.lastCheck);
+  const formatted = date.toISOString().replace('T', ' ').slice(0, 16);
+  return `${formatted} (v${data.latestVersion})`;
+}
+
+function extractIndexVersion(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const match = content.match(/<!-- Version: (v[\d.]+) -->/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function statusCommand() {
+  const homeDir = os.homedir();
+  const skillsDir = getAgentsSkillsDir(homeDir);
+  const agentsDir = getClaudeAgentsDir(homeDir);
+  const claudeDir = join(homeDir, '.claude');
+  const cacheDir = getConfigDir();
+  const cwd = process.cwd();
+
+  // Skills count
+  const installedCount = countInstalledSkills(skillsDir);
+  const totalCount = SKILLS.length;
+
+  // Agent check
+  const agentExists = existsSync(join(agentsDir, 'ti-pro.md'));
+
+  // Hook check
+  const hookExists = hasHook(claudeDir);
+
+  // Cache
+  const lastCheck = readLastCheck(cacheDir);
+
+  console.log('');
+  console.log(chalk.bold('Titanium SDK Skills Status'));
+  console.log('');
+  console.log(`  Version:    v${PACKAGE_VERSION}`);
+  console.log(`  Skills:     ${installedCount}/${totalCount} installed`);
+  console.log(`  Agent:      ti-pro ${agentExists ? CHECK : CROSS}`);
+  console.log(`  Hook:       Claude Code SessionStart ${hookExists ? CHECK : CROSS}`);
+  console.log(`  Last check: ${formatLastCheck(lastCheck)}`);
+
+  // Platforms
+  console.log('');
+  console.log('  Platforms:');
+  const platforms = getPlatforms(homeDir);
+  for (const platform of platforms) {
+    const linked = countLinkedSkills(platform.skillsDir);
+    if (linked > 0) {
+      console.log(`    ${platform.displayName.padEnd(13)} ${CHECK} ${linked} skills linked`);
+    } else {
+      console.log(`    ${platform.displayName.padEnd(13)} ${CROSS} ${chalk.gray('not linked')}`);
+    }
+  }
+
+  // Project
+  console.log('');
+  if (isTitaniumProject(cwd)) {
+    const sdkVersion = detectTitaniumVersion(cwd);
+    console.log(`  Project: ${chalk.cyan('Titanium')} (SDK ${sdkVersion})`);
+
+    const mdFiles = ['CLAUDE.md', 'GEMINI.md', 'AGENTS.md'];
+    for (const file of mdFiles) {
+      const filePath = join(cwd, file);
+      if (!existsSync(filePath)) {
+        console.log(`    ${file.padEnd(11)} ${CROSS} ${chalk.gray('not found')}`);
+      } else if (blockExists(filePath)) {
+        const version = extractIndexVersion(filePath);
+        console.log(`    ${file.padEnd(11)} ${CHECK} Knowledge Index${version ? ` (${version})` : ''}`);
+      } else {
+        console.log(`    ${file.padEnd(11)} ${CROSS} ${chalk.gray('no index')}`);
+      }
+    }
+  } else {
+    console.log(`  Project: ${chalk.gray('(not a Titanium project)')}`);
+  }
+
+  console.log('');
+}
+
+export default { statusCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",