tokrepo 1.1.0 → 3.0.0

package/bin/tokrepo.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const https = require('https');
 const http = require('http');
 const readline = require('readline');
@@ -23,6 +24,8 @@ const CONFIG_DIR = path.join(require('os').homedir(), '.tokrepo');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const PROJECT_CONFIG = '.tokrepo.json';
 const DEFAULT_API = 'https://api.tokrepo.com';
+const CLI_VERSION = '3.0.0';
+const VERSION_CHECK_FILE = path.join(require('os').homedir(), '.tokrepo', '.version-check');
 
 // ─── Helpers ───
 
@@ -42,9 +45,64 @@ function readConfig() {
 
 function writeConfig(config) {
   if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
   }
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+// Check npm registry for newer version (non-blocking, max once per day)
+async function checkForUpdate() {
+  try {
+    // Only check once per 24 hours
+    if (fs.existsSync(VERSION_CHECK_FILE)) {
+      const stat = fs.statSync(VERSION_CHECK_FILE);
+      const hoursSinceCheck = (Date.now() - stat.mtimeMs) / 3600000;
+      if (hoursSinceCheck < 24) return;
+    }
+    // Touch the file to mark check time
+    if (!fs.existsSync(path.dirname(VERSION_CHECK_FILE))) {
+      fs.mkdirSync(path.dirname(VERSION_CHECK_FILE), { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(VERSION_CHECK_FILE, '', { mode: 0o600 });
+
+    const data = await new Promise((resolve, reject) => {
+      const req = https.get('https://registry.npmjs.org/tokrepo/latest', {
+        headers: { 'Accept': 'application/json' },
+        timeout: 3000,
+      }, (res) => {
+        let body = '';
+        res.on('data', (chunk) => { body += chunk; });
+        res.on('end', () => {
+          try { resolve(JSON.parse(body)); } catch { reject(); }
+        });
+      });
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(); });
+    });
+
+    const latest = data.version;
+    if (latest && latest !== CLI_VERSION) {
+      const cmp = compareVersions(latest, CLI_VERSION);
+      if (cmp > 0) {
+        log('');
+        log(`${C.yellow}!${C.reset} Update available: ${C.dim}${CLI_VERSION}${C.reset} → ${C.green}${latest}${C.reset}`);
+        log(`  Run: ${C.cyan}npm install -g tokrepo${C.reset}`);
+        log('');
+      }
+    }
+  } catch {
+    // Silent fail — update check is best-effort
+  }
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
 }
 
 function readProjectConfig(baseDir = process.cwd()) {
@@ -74,12 +132,16 @@ function apiRequest(method, urlPath, body, token, apiBase) {
   return new Promise((resolve, reject) => {
     const base = apiBase || DEFAULT_API;
     const url = new URL(urlPath, base);
+    // Force HTTPS to prevent token transmission over plain HTTP
+    if (url.protocol === 'http:' && !url.hostname.match(/^(localhost|127\.0\.0\.1)$/)) {
+      url.protocol = 'https:';
+    }
     const isHttps = url.protocol === 'https:';
     const mod = isHttps ? https : http;
 
     const headers = {
       'Content-Type': 'application/json',
-      'User-Agent': 'tokrepo-cli/1.1.0',
+      'User-Agent': 'tokrepo-cli/2.0.0',
     };
     if (token) {
       headers['Authorization'] = `Bearer ${token}`;
@@ -144,7 +206,8 @@ function detectFileType(filename) {
 
 // Guess tag from file type
 function guessTag(fileType) {
-  const map = { skill: 'Skills', prompt: 'Prompts', script: 'Scripts', config: 'Configs' };
+  // Use lowercase singular names to match backend tag slugs
+  const map = { skill: 'skill', prompt: 'prompt', script: 'script', config: 'config', mcp: 'mcp' };
   return map[fileType] || null;
 }
 
@@ -253,6 +316,11 @@ function collectFiles(paths, baseDir) {
 
   for (const p of paths) {
     const resolved = path.resolve(baseDir, p);
+    // Prevent path traversal — resolved must be within baseDir
+    if (!resolved.startsWith(path.resolve(baseDir) + path.sep) && resolved !== path.resolve(baseDir)) {
+      warn(`Skipped (outside project): ${p}`);
+      continue;
+    }
     if (!fs.existsSync(resolved)) {
       warn(`Not found: ${p}`);
       continue;
@@ -513,6 +581,226 @@ async function cmdPull() {
   }
 }
 
+// ─── Search ───
+
+async function cmdSearch() {
+  const query = process.argv.slice(3).join(' ');
+  if (!query) error('Usage: tokrepo search <keyword>');
+
+  log(`\n${C.bold}tokrepo search${C.reset} "${query}"\n`);
+
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+
+  try {
+    const encoded = encodeURIComponent(query);
+    const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=1&page_size=20&sort_by=views`, null, config?.token, apiBase);
+
+    if (!data.list || data.list.length === 0) {
+      info('No assets found.');
+      log(`\n  ${C.dim}Try different keywords or browse: https://tokrepo.com/en/featured${C.reset}\n`);
+      return;
+    }
+
+    log(`  ${C.bold}${data.total}${C.reset} results:\n`);
+
+    for (let i = 0; i < data.list.length; i++) {
+      const wf = data.list[i];
+      const tags = (wf.tags || []).map(t => t.name).join(', ');
+      const views = wf.view_count || 0;
+      const votes = wf.vote_count || 0;
+
+      log(`  ${C.dim}${String(i + 1).padStart(2)}.${C.reset} ${C.bold}${wf.title}${C.reset}`);
+      if (tags) log(`      ${C.cyan}${tags}${C.reset}  ${C.dim}★${votes} 👁${views}${C.reset}`);
+      log(`      ${C.dim}tokrepo install ${wf.uuid}${C.reset}`);
+      log('');
+    }
+  } catch (e) {
+    error(`Search failed: ${e.message}`);
+  }
+}
+
+// ─── Install (smart pull with correct placement) ───
+
+async function cmdInstall() {
+  const target = process.argv[3];
+  if (!target) {
+    error(`Usage: tokrepo install <name-or-uuid>
+
+Examples:
+  tokrepo install awesome-cursor-rules
+  tokrepo install ca000374-f5d8-4d75-a30c-460fda0b6b0e
+  tokrepo install https://tokrepo.com/en/workflows/ca000374-...`);
+  }
+
+  log(`\n${C.bold}tokrepo install${C.reset}\n`);
+
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+
+  // Resolve target to UUID
+  let uuid = target;
+
+  // URL format
+  const urlMatch = target.match(/workflows\/([a-f0-9-]+)/);
+  if (urlMatch) {
+    uuid = urlMatch[1];
+  }
+  // UUID format check
+  else if (!/^[a-f0-9-]{36}$/.test(target)) {
+    // Search by name
+    info(`Searching for "${target}"...`);
+    try {
+      const encoded = encodeURIComponent(target);
+      const searchData = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=1&page_size=5&sort_by=views`, null, config?.token, apiBase);
+
+      if (!searchData.list || searchData.list.length === 0) {
+        error(`No asset found matching "${target}". Try: tokrepo search ${target}`);
+      }
+
+      // If exact title match, use it directly
+      const exact = searchData.list.find(w => w.title.toLowerCase().includes(target.toLowerCase()));
+      const chosen = exact || searchData.list[0];
+
+      uuid = chosen.uuid;
+      info(`Found: ${C.bold}${chosen.title}${C.reset}`);
+    } catch (e) {
+      error(`Search failed: ${e.message}`);
+    }
+  }
+
+  // Fetch the asset
+  info(`Fetching ${uuid.substring(0, 8)}...`);
+
+  let workflow, files;
+  try {
+    const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${uuid}`, null, config?.token, apiBase);
+    workflow = data.workflow;
+    files = data.workflow.files || [];
+  } catch (e) {
+    error(`Fetch failed: ${e.message}`);
+  }
+
+  log(`\n  ${C.bold}${workflow.title}${C.reset}`);
+  if (workflow.description) log(`  ${C.dim}${workflow.description.substring(0, 100)}${C.reset}`);
+
+  // Determine asset type from tags
+  let assetType = 'other';
+  if (workflow.tags && workflow.tags.length > 0) {
+    assetType = (workflow.tags[0].slug || workflow.tags[0].name || '').toLowerCase();
+  }
+
+  // Get content — prefer files, fallback to steps
+  const contents = [];
+
+  if (files.length > 0) {
+    for (const f of files) {
+      if (f.content && !f.content.startsWith('PK')) {
+        contents.push({ name: f.name, content: f.content, type: f.file_type || f.fileType || 'other' });
+      }
+    }
+  }
+
+  if (contents.length === 0 && workflow.steps) {
+    for (const step of workflow.steps) {
+      const content = step.prompt_template || step.promptTemplate;
+      if (content && !content.startsWith('PK')) {
+        const name = (step.title || `step-${step.step_order}`).replace(/[/\\?%*:|"<>]/g, '-');
+        contents.push({ name, content, type: assetType });
+      }
+    }
+  }
+
+  if (contents.length === 0) {
+    error('No installable content found in this asset.');
+  }
+
+  log('');
+
+  // Smart install based on asset type
+  let installed = 0;
+
+  for (const item of contents) {
+    let destDir = process.cwd();
+    let fileName = item.name;
+
+    // Ensure file has extension
+    if (!path.extname(fileName)) fileName += '.md';
+
+    switch (assetType) {
+      case 'skills':
+      case 'skill': {
+        // Install to .claude/skills/ if it exists, otherwise current dir
+        const claudeSkillsDir = path.join(process.cwd(), '.claude', 'skills');
+        if (fs.existsSync(path.join(process.cwd(), '.claude'))) {
+          if (!fs.existsSync(claudeSkillsDir)) {
+            fs.mkdirSync(claudeSkillsDir, { recursive: true });
+          }
+          destDir = claudeSkillsDir;
+        }
+        break;
+      }
+      case 'mcp':
+      case 'mcp configs': {
+        // Security warning for MCP configs
+        warn('MCP server config detected. Review the configuration carefully before adding to your project.');
+        warn('MCP servers can execute arbitrary code. Only install from trusted sources.');
+        // Save as mcp config, hint about manual merge
+        if (!fileName.endsWith('.json')) fileName = fileName.replace(/\.md$/, '.json');
+        break;
+      }
+      case 'configs':
+      case 'config': {
+        // Save to project root
+        break;
+      }
+      case 'scripts':
+      case 'script': {
+        // Save and make executable
+        if (!path.extname(fileName) || fileName.endsWith('.md')) {
+          // Detect language from content
+          if (item.content.startsWith('#!/usr/bin/env python') || item.content.includes('import ')) {
+            fileName = fileName.replace(/\.md$/, '.py');
+          } else if (item.content.startsWith('#!/bin/bash') || item.content.startsWith('#!/bin/sh')) {
+            fileName = fileName.replace(/\.md$/, '.sh');
+          }
+        }
+        break;
+      }
+      case 'prompts':
+      case 'prompt': {
+        // Save as markdown
+        if (!fileName.endsWith('.md') && !fileName.endsWith('.prompt')) fileName += '.md';
+        break;
+      }
+    }
+
+    // Sanitize fileName to prevent path traversal from API response
+    fileName = path.basename(fileName);
+    const destPath = path.join(destDir, fileName);
+
+    // Don't overwrite without warning
+    if (fs.existsSync(destPath)) {
+      warn(`File exists: ${path.relative(process.cwd(), destPath)} (overwriting)`);
+    }
+
+    fs.writeFileSync(destPath, item.content);
+
+    // Make scripts executable
+    if (assetType === 'script' || assetType === 'scripts') {
+      try { fs.chmodSync(destPath, 0o755); } catch {}
+    }
+
+    const relPath = path.relative(process.cwd(), destPath);
+    success(`Installed: ${relPath}`);
+    installed++;
+  }
+
+  log('');
+  success(`${installed} file(s) installed from ${C.bold}${workflow.title}${C.reset}`);
+  log(`  ${C.dim}Source: https://tokrepo.com/en/workflows/${uuid}${C.reset}\n`);
+}
+
 async function cmdWhoami() {
   const config = readConfig();
   if (!config || !config.token) error('Not logged in. Run: tokrepo login');
@@ -633,43 +921,367 @@ async function cmdTags() {
   }
 }
 
+// ─── Sync: scan directory, diff with remote, upsert changes ───
+
+function computeHash(files) {
+  const h = crypto.createHash('sha256');
+  for (const f of files) {
+    h.update(f.name);
+    h.update('\0');
+    h.update(f.content);
+    h.update('\0');
+  }
+  return h.digest('hex');
+}
+
+function scanDirectory(dirPath) {
+  const assets = [];
+  const SKIP_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 'dist', 'build']);
+  const SKIP_FILES = new Set(['.DS_Store', 'Thumbs.db', 'package-lock.json', 'yarn.lock']);
+
+  // Each subdirectory = one asset; loose files = one asset per file
+  let entries;
+  try { entries = fs.readdirSync(dirPath, { withFileTypes: true }); } catch { return assets; }
+
+  const looseFiles = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name)) continue;
+
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      // Subdirectory = one asset (e.g., ~/.claude/skills/my-skill/)
+      const files = collectAssetFiles(fullPath);
+      if (files.length === 0) continue;
+
+      const title = guessAssetTitle(files, entry.name);
+      const hash = computeHash(files);
+      const detectedTags = new Set();
+      for (const f of files) {
+        const ft = detectFileType(f.name);
+        const tag = guessTag(ft);
+        if (tag) detectedTags.add(tag);
+      }
+
+      assets.push({ title, files, hash, tags: Array.from(detectedTags), sourcePath: fullPath });
+    } else if (entry.isFile()) {
+      // Loose file
+      const ext = path.extname(entry.name).toLowerCase();
+      const validExts = ['.md', '.sh', '.py', '.js', '.mjs', '.ts', '.json', '.yaml', '.yml', '.toml', '.prompt'];
+      if (validExts.includes(ext) || entry.name === '.cursorrules' || entry.name === '.windsurfrules') {
+        looseFiles.push({ path: fullPath, name: entry.name });
+      }
+    }
+  }
+
+  // Each loose file = one asset
+  for (const f of looseFiles) {
+    let content;
+    try { content = fs.readFileSync(f.path, 'utf8'); } catch { continue; }
+    if (!content.trim()) continue;
+
+    const files = [{ name: f.name, content, type: detectFileType(f.name) }];
+    const title = guessAssetTitle(files, path.basename(f.name, path.extname(f.name)));
+    const hash = computeHash(files);
+    const ft = detectFileType(f.name);
+    const tag = guessTag(ft);
+
+    assets.push({ title, files, hash, tags: tag ? [tag] : [], sourcePath: f.path });
+  }
+
+  return assets;
+}
+
+function collectAssetFiles(dirPath) {
+  const files = [];
+  const SKIP = new Set(['.DS_Store', 'node_modules', '.git', '__pycache__']);
+
+  function walk(dir, relBase) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || SKIP.has(entry.name)) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        const validExts = ['.md', '.sh', '.py', '.js', '.mjs', '.ts', '.json', '.yaml', '.yml', '.toml', '.prompt', '.rb', '.go', '.rs'];
+        if (validExts.includes(ext) || entry.name === '.cursorrules') {
+          let content;
+          try { content = fs.readFileSync(fullPath, 'utf8'); } catch { continue; }
+          if (!content.trim()) continue;
+          files.push({ name: relPath, content, type: detectFileType(relPath) });
+        }
+      }
+    }
+  }
+
+  walk(dirPath, '');
+  return files;
+}
+
+function guessAssetTitle(files, fallbackName) {
+  // Try to find a heading in the first .md file
+  for (const f of files) {
+    if (f.name.toLowerCase().endsWith('.md')) {
+      const match = f.content.match(/^#\s+(.+)$/m);
+      if (match) return match[1].trim();
+    }
+  }
+  // Clean up fallback name
+  return fallbackName
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+async function cmdSync() {
+  const args = parseArgs(process.argv);
+  const config = readConfig();
+  if (!config || !config.token) error(`Not logged in. Run: ${C.cyan}tokrepo login${C.reset}`);
+
+  const targetDir = args.positional[0]
+    ? path.resolve(args.positional[0])
+    : path.join(require('os').homedir(), '.claude', 'skills');
+
+  if (!fs.existsSync(targetDir)) {
+    error(`Directory not found: ${targetDir}`);
+  }
+
+  const visibility = args.flags.public ? 1 : 0; // default private for sync
+
+  log(`\n${C.bold}tokrepo sync${C.reset}\n`);
+  info(`Scanning ${targetDir}...`);
+
+  const assets = scanDirectory(targetDir);
+  if (assets.length === 0) {
+    info('No assets found in directory.');
+    return;
+  }
+
+  log(`  Found ${C.bold}${assets.length}${C.reset} assets\n`);
+
+  // Step 1: Diff with remote
+  info('Comparing with remote...');
+  const diffPayload = assets.map(a => ({ title: a.title, content_hash: a.hash }));
+
+  let diffResults;
+  try {
+    const data = await apiRequest('POST', '/api/v1/tokenboard/push/diff', { assets: diffPayload }, config.token, config.api);
+    diffResults = data.results;
+  } catch (e) {
+    // Fallback: if diff endpoint not available, treat all as new
+    warn(`Diff API not available (${e.message}), treating all as new`);
+    diffResults = assets.map(a => ({ title: a.title, status: 'new' }));
+  }
+
+  // Build status map
+  const statusMap = {};
+  for (const r of diffResults) {
+    statusMap[r.title] = r;
+  }
+
+  // Show status
+  let newCount = 0, updatedCount = 0, unchangedCount = 0;
+
+  for (const asset of assets) {
+    const status = statusMap[asset.title]?.status || 'new';
+    if (status === 'new') {
+      log(`  ${C.green}+ new${C.reset}       ${asset.title} ${C.dim}(${asset.files.length} files)${C.reset}`);
+      newCount++;
+    } else if (status === 'updated') {
+      log(`  ${C.yellow}~ updated${C.reset}   ${asset.title}`);
+      updatedCount++;
+    } else {
+      log(`  ${C.dim}= unchanged ${asset.title}${C.reset}`);
+      unchangedCount++;
+    }
+  }
+
+  log('');
+  log(`  ${C.green}${newCount} new${C.reset}  ${C.yellow}${updatedCount} updated${C.reset}  ${C.dim}${unchangedCount} unchanged${C.reset}`);
+
+  if (newCount === 0 && updatedCount === 0) {
+    log('');
+    success('Everything is up to date!');
+    return;
+  }
+
+  log('');
+
+  // Confirm unless -y
+  if (!args.flags.yes) {
+    const confirm = await ask(`Push ${newCount + updatedCount} assets? (y/N):`);
+    if (confirm.toLowerCase() !== 'y') { log('Aborted.'); return; }
+  }
+
+  // Step 2: Upsert each changed asset
+  let successCount = 0;
+  let failCount = 0;
+
+  for (const asset of assets) {
+    const status = statusMap[asset.title]?.status || 'new';
+    if (status === 'unchanged') continue;
+
+    const totalChars = asset.files.reduce((sum, f) => sum + f.content.length, 0);
+
+    try {
+      const data = await apiRequest('POST', '/api/v1/tokenboard/push/upsert', {
+        title: asset.title,
+        files: asset.files,
+        tags: asset.tags,
+        token_cost: String(Math.round(totalChars / 4)),
+        visibility,
+      }, config.token, config.api);
+
+      const action = data.action === 'created' ? C.green + '+ created' : C.yellow + '~ updated';
+      log(`  ${action}${C.reset}  ${asset.title}  ${C.dim}${data.url}${C.reset}`);
+      successCount++;
+    } catch (e) {
+      log(`  ${C.red}✗ failed${C.reset}   ${asset.title}: ${e.message}`);
+      failCount++;
+    }
+  }
+
+  log('');
+  if (failCount === 0) {
+    success(`Synced ${successCount} assets!`);
+  } else {
+    warn(`${successCount} synced, ${failCount} failed`);
+  }
+  log('');
+}
+
+async function cmdStatus() {
+  const args = parseArgs(process.argv);
+  const config = readConfig();
+  if (!config || !config.token) error(`Not logged in. Run: ${C.cyan}tokrepo login${C.reset}`);
+
+  const targetDir = args.positional[0]
+    ? path.resolve(args.positional[0])
+    : path.join(require('os').homedir(), '.claude', 'skills');
+
+  if (!fs.existsSync(targetDir)) {
+    error(`Directory not found: ${targetDir}`);
+  }
+
+  log(`\n${C.bold}tokrepo status${C.reset}\n`);
+  info(`Scanning ${targetDir}...`);
+
+  const assets = scanDirectory(targetDir);
+  if (assets.length === 0) {
+    info('No assets found in directory.');
+    return;
+  }
+
+  // Diff with remote
+  info('Comparing with remote...\n');
+  const diffPayload = assets.map(a => ({ title: a.title, content_hash: a.hash }));
+
+  let diffResults;
+  try {
+    const data = await apiRequest('POST', '/api/v1/tokenboard/push/diff', { assets: diffPayload }, config.token, config.api);
+    diffResults = data.results;
+  } catch (e) {
+    error(`Diff API error: ${e.message}`);
+  }
+
+  const statusMap = {};
+  for (const r of diffResults) {
+    statusMap[r.title] = r;
+  }
+
+  let newCount = 0, updatedCount = 0, unchangedCount = 0;
+
+  for (const asset of assets) {
+    const status = statusMap[asset.title]?.status || 'new';
+    const uuid = statusMap[asset.title]?.remote_uuid || '';
+    const uuidShort = uuid ? ` ${C.dim}(${uuid.substring(0, 8)})${C.reset}` : '';
+
+    if (status === 'new') {
+      log(`  ${C.green}+ new${C.reset}       ${asset.title} ${C.dim}(${asset.files.length} files)${C.reset}`);
+      newCount++;
+    } else if (status === 'updated') {
+      log(`  ${C.yellow}~ modified${C.reset}  ${asset.title}${uuidShort}`);
+      updatedCount++;
+    } else {
+      log(`  ${C.dim}  unchanged ${asset.title}${uuidShort}${C.reset}`);
+      unchangedCount++;
+    }
+  }
+
+  log('');
+  log(`  ${C.bold}${assets.length}${C.reset} local assets: ${C.green}${newCount} new${C.reset}  ${C.yellow}${updatedCount} modified${C.reset}  ${C.dim}${unchangedCount} synced${C.reset}`);
+
+  if (newCount > 0 || updatedCount > 0) {
+    log(`\n  Run ${C.cyan}tokrepo sync ${args.positional[0] || ''}${C.reset} to push changes`);
+  }
+  log('');
+}
+
 function showHelp() {
   log(`
-${C.bold}tokrepo${C.reset} — Push AI assets to tokrepo.com
+${C.bold}tokrepo${C.reset} — AI assets for humans and agents. Like GitHub, for AI experience.
 
 ${C.bold}QUICK START${C.reset}
-  ${C.cyan}tokrepo login${C.reset}                          # one-time: paste your token
-  ${C.cyan}tokrepo push --public .${C.reset}                # push current directory
-  ${C.cyan}tokrepo push --public README.md script.py${C.reset}  # push specific files
+  ${C.cyan}tokrepo search cursor rules${C.reset}             # find assets
+  ${C.cyan}tokrepo install awesome-cursor-rules${C.reset}    # install to your project
+  ${C.cyan}tokrepo push --public .${C.reset}                 # share your own assets
 
 ${C.bold}USAGE${C.reset}
-  tokrepo push [files/dirs...] [options]
-
-${C.bold}OPTIONS${C.reset}
+  tokrepo <command> [args] [options]
+
+${C.bold}DISCOVER & INSTALL${C.reset}
+  ${C.cyan}search${C.reset} <query>      Search assets by keyword
+  ${C.cyan}install${C.reset} <name|uuid> Smart install (auto-detects type & placement)
+  ${C.cyan}pull${C.reset} <url|uuid>     Download raw asset files
+
+${C.bold}PUBLISH & SYNC${C.reset}
+  ${C.cyan}push${C.reset} [files...]     Push files/directory (creates new asset)
+  ${C.cyan}sync${C.reset} [dir]          Sync directory to TokRepo (smart upsert)
+  ${C.cyan}status${C.reset} [dir]        Show local vs remote diff
+  ${C.cyan}init${C.reset}                Create .tokrepo.json project config
+  ${C.cyan}update${C.reset} <uuid> [f]   Update existing asset by UUID
+  ${C.cyan}delete${C.reset} <uuid>       Delete an asset
+
+${C.bold}ACCOUNT${C.reset}
+  ${C.cyan}login${C.reset}               Save API token
+  ${C.cyan}list${C.reset}                List your published assets
+  ${C.cyan}tags${C.reset}                List available tags
+  ${C.cyan}whoami${C.reset}              Show current user
+  ${C.cyan}help${C.reset}                Show this help
+
+${C.bold}PUSH OPTIONS${C.reset}
   ${C.cyan}--public${C.reset}            Make asset publicly visible (default)
   ${C.cyan}--private${C.reset}           Make asset private
   ${C.cyan}--title${C.reset} "..."       Set title (auto-detected from README or dir name)
   ${C.cyan}--desc${C.reset} "..."        Set description
-  ${C.cyan}--tag${C.reset} Skills        Add tag (repeatable: --tag Skills --tag MCP)
-  ${C.cyan}-y, --yes${C.reset}           Skip confirmation prompts
-
-${C.bold}COMMANDS${C.reset}
-  ${C.cyan}login${C.reset}              Save API token
-  ${C.cyan}push${C.reset} [files...]    Push files/directory (default: current dir)
-  ${C.cyan}init${C.reset}               Create .tokrepo.json project config
-  ${C.cyan}pull${C.reset} <url>         Download asset to local files
-  ${C.cyan}list${C.reset}               List your assets
-  ${C.cyan}update${C.reset} <uuid> [f]  Update existing asset
-  ${C.cyan}delete${C.reset} <uuid>      Delete an asset
-  ${C.cyan}tags${C.reset}               List available tags
-  ${C.cyan}whoami${C.reset}             Show current user
-  ${C.cyan}help${C.reset}               Show this help
+  ${C.cyan}--tag${C.reset} Skills        Add tag (repeatable)
+
+${C.bold}INSTALL BEHAVIOR${C.reset}
+  Skills   → .claude/skills/    (if .claude/ exists)
+  Scripts  → current dir        (chmod +x)
+  Configs  → project root
+  MCP      → current dir        (.json)
+  Prompts  → current dir        (.md)
+
+${C.bold}SYNC (the killer feature)${C.reset}
+  ${C.cyan}tokrepo sync ~/.claude/skills/${C.reset}          # Sync all skills (default: private)
+  ${C.cyan}tokrepo sync ~/.claude/skills/ --public${C.reset} # Sync as public assets
+  ${C.cyan}tokrepo sync . -y${C.reset}                       # Sync current dir, skip confirm
+  ${C.cyan}tokrepo status${C.reset}                          # Show what would change
+
+  Sync scans a directory, detects new/modified assets, and pushes only
+  what changed. Each subdirectory becomes one asset. Loose files become
+  individual assets. Like ${C.bold}git push${C.reset} for your AI assets.
 
 ${C.bold}EXAMPLES${C.reset}
-  tokrepo push --public .                     # Push all files in current dir
+  tokrepo search "mcp server"                 # Find MCP configs
+  tokrepo install ca000374-f5d8-...           # Install by UUID
+  tokrepo push --public .                     # Push current directory
   tokrepo push --public --title "My MCP" .    # Push with custom title
-  tokrepo push --public src/ README.md        # Push specific paths
-  tokrepo push                                # Uses .tokrepo.json if exists
 
 ${C.bold}FILE TYPE AUTO-DETECTION${C.reset}
   .sh .py .js .ts .mjs .go .rs  →  script
@@ -692,17 +1304,26 @@ async function main() {
     case 'login': await cmdLogin(); break;
     case 'init': await cmdInit(); break;
     case 'push': await cmdPush(); break;
+    case 'sync': await cmdSync(); break;
+    case 'status': case 'st': await cmdStatus(); break;
     case 'pull': await cmdPull(); break;
+    case 'search': case 'find': await cmdSearch(); break;
+    case 'install': case 'i': await cmdInstall(); break;
     case 'list': await cmdList(); break;
     case 'update': await cmdUpdate(); break;
     case 'delete': await cmdDelete(); break;
     case 'tags': await cmdTags(); break;
     case 'whoami': await cmdWhoami(); break;
+    case '--version': case '-v': case 'version':
+      log(`tokrepo ${CLI_VERSION}`); break;
     case 'help': case '--help': case '-h': case undefined:
       showHelp(); break;
     default:
       error(`Unknown command: ${command}. Run: tokrepo help`);
   }
+
+  // Non-blocking update check after command completes
+  checkForUpdate();
 }
 
 main().catch((e) => { error(e.message); });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tokrepo",
-  "version": "1.1.0",
-  "description": "Push AI assets to tokrepo.com — Skills, Prompts, MCP Configs, Scripts",
+  "version": "3.0.0",
+  "description": "AI assets for humans and agents — sync, search, install, push. Like git push for your AI skills.",
   "bin": {
     "tokrepo": "bin/tokrepo.js"
   },