@deerdesign/deertools 1.2.26 → 1.2.31

package/src/skill-commands.js

@@ -6,6 +6,7 @@ const skillsHub = require('./skills-hub');
 const { parseFrontmatterName } = require('./openapi');
 const { resolveProducts } = require('./registry');
 const { fetchText } = require('./http');
+const embedding = require('./embedding');
 
 const { compareSemver } = require('./updater');
 
@@ -92,6 +93,82 @@ function readSkillVersion(filePath, lock, skill) {
   return '1.0.0';
 }
 
+/**
+ * Skanuje lokalne katalogi w poszukiwaniu skilli na dysku.
+ * Zwraca mapę slug -> { slug, version, dir, filePath, summary }.
+ */
+function scanLocalSkills(cwd = process.cwd(), agents = [], hubSlugs = null) {
+  const localSkills = new Map();
+
+  function inspectDir(skillDir, isAgentDir = false) {
+    const skillMd = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) return;
+    try {
+      const content = fs.readFileSync(skillMd, 'utf8');
+      let slug = path.basename(skillDir);
+      let version = '1.0.0';
+      let summary = '';
+      if (content.startsWith('---')) {
+        const parts = content.split('---', 2);
+        if (parts.length >= 2) {
+          const nameMatch = parts[1].match(/^name:\s*(.+)$/m);
+          if (nameMatch) slug = nameMatch[1].trim();
+          const verMatch = parts[1].match(/^version:\s*['"]?([0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.]+)?)/im);
+          if (verMatch) version = verMatch[1].trim();
+          const descMatch = parts[1].match(/^description:\s*(.+)$/m);
+          if (descMatch) summary = descMatch[1].trim();
+        }
+      }
+
+      // Jeśli skanujemy katalog zewnętrznego agenta (~/.gemini/...): bierzemy tylko skille Deer Design lub znane w Hubie
+      if (isAgentDir) {
+        const isDeer = slug.startsWith('deer') || slug.startsWith('rendermind') || slug.startsWith('@');
+        const isKnown = hubSlugs && (hubSlugs.has(slug) || hubSlugs.has(slug.replace(/^@[^/]+\//, '')));
+        if (!isDeer && !isKnown) return;
+      }
+
+      if (!localSkills.has(slug)) {
+        localSkills.set(slug, {
+          slug,
+          version,
+          dir: skillDir,
+          filePath: skillMd,
+          summary,
+        });
+      }
+    } catch (_) {}
+  }
+
+  // 1. Sprawdź .agents/skills w bieżącym projekcie
+  const projectAgentsSkills = path.join(cwd, '.agents', 'skills');
+  if (fs.existsSync(projectAgentsSkills)) {
+    try {
+      const entries = fs.readdirSync(projectAgentsSkills, { withFileTypes: true });
+      for (const ent of entries) {
+        if (ent.isDirectory() && !ent.name.startsWith('.')) {
+          inspectDir(path.join(projectAgentsSkills, ent.name), false);
+        }
+      }
+    } catch (_) {}
+  }
+
+  // 2. Sprawdź katalogi wykrytych agentów (tylko skille powiązane z Hubem lub Deer Design)
+  for (const agent of agents) {
+    if (agent.targetDir && fs.existsSync(agent.targetDir)) {
+      try {
+        const entries = fs.readdirSync(agent.targetDir, { withFileTypes: true });
+        for (const ent of entries) {
+          if (ent.isDirectory() && !ent.name.startsWith('.')) {
+            inspectDir(path.join(agent.targetDir, ent.name), true);
+          }
+        }
+      } catch (_) {}
+    }
+  }
+
+  return localSkills;
+}
+
 /**
  * Bada stan instalacji i wersję skilla u wszystkich zadanych agentów.
  */
@@ -101,6 +178,7 @@ function inspectSkillForAgents(agents, skill, lock) {
   let upToDateCount = 0;
   let outdatedCount = 0;
   let missingCount = 0;
+  let aheadCount = 0;
 
   for (const agent of agents) {
     const filePath = findSkillFileForAgent(agent, skill);
@@ -122,7 +200,7 @@ function inspectSkillForAgents(agents, skill, lock) {
     const installedVer = readSkillVersion(filePath, lock, skill);
     const cmp = compareSemver(installedVer, skill.latest_version);
 
-    if (cmp >= 0) {
+    if (cmp === 0) {
       agentStatuses[agent.id] = {
         agentId: agent.id,
         agentName: agent.name,
@@ -133,6 +211,19 @@ function inspectSkillForAgents(agents, skill, lock) {
         badge: `\x1b[32m[✓ ${agent.id}: v${installedVer}]\x1b[0m`,
       };
       upToDateCount += 1;
+    } else if (cmp > 0) {
+      agentStatuses[agent.id] = {
+        agentId: agent.id,
+        agentName: agent.name,
+        installed: true,
+        version: installedVer,
+        status: 'ahead',
+        hub_version: skill.latest_version,
+        filePath,
+        badge: `\x1b[35m[★ ${agent.id}: v${installedVer} > Hub v${skill.latest_version}]\x1b[0m`,
+      };
+      upToDateCount += 1;
+      aheadCount += 1;
     } else {
       agentStatuses[agent.id] = {
         agentId: agent.id,
@@ -152,7 +243,10 @@ function inspectSkillForAgents(agents, skill, lock) {
   let overallBadge = '\x1b[90m[○ Niezainstalowany]\x1b[0m';
 
   if (installedCount > 0) {
-    if (installedCount === agents.length && outdatedCount === 0) {
+    if (aheadCount > 0) {
+      overallStatus = 'ahead';
+      overallBadge = `\x1b[35m[★ Nowszy lokalnie (${aheadCount})]\x1b[0m`;
+    } else if (installedCount === agents.length && outdatedCount === 0) {
       overallStatus = 'up_to_date';
       overallBadge = `\x1b[32m[✓ Aktualny (${installedCount}/${agents.length})]\x1b[0m`;
     } else if (outdatedCount > 0) {
@@ -170,27 +264,148 @@ function inspectSkillForAgents(agents, skill, lock) {
     upToDateCount,
     outdatedCount,
     missingCount,
+    aheadCount,
     overallStatus,
     overallBadge,
   };
 }
 
+/**
+ * Sprawdza czy dany skill pasuje do zapytania tekstowego.
+ * Przeszukuje kompleksowo:
+ *  1. Nazwę (slug, full_slug, title)
+ *  2. Opis (summary / description - pełny tekst opisu z SKILL.md)
+ *  3. Tagi (zarówno całe tagi, jak i dopasowania cząstkowe, np. 'matrycowy' w 'cennik-matrycowy')
+ *  4. Kategorie (nazwa kategorii oraz jej slug)
+ *  5. Namespace oraz autora (owner_name, owner_email)
+ */
+function matchSkillQuery(skill, query) {
+  if (!query) return true;
+  const q = String(query).toLowerCase().trim();
+  if (!q) return true;
+
+  // 1. Nazwa, slug, full_slug, title
+  if (skill.slug && String(skill.slug).toLowerCase().includes(q)) return true;
+  if (skill.full_slug && String(skill.full_slug).toLowerCase().includes(q)) return true;
+  if (skill.title && String(skill.title).toLowerCase().includes(q)) return true;
+
+  // 2. Opis (summary / description)
+  if (skill.summary && String(skill.summary).toLowerCase().includes(q)) return true;
+  if (skill.description && String(skill.description).toLowerCase().includes(q)) return true;
+
+  // 3. Tagi (zarówno dopasowanie pełne, jak i podciąg wewnątrz tagu)
+  if (Array.isArray(skill.tags)) {
+    for (const tag of skill.tags) {
+      if (String(tag).toLowerCase().includes(q)) return true;
+    }
+  }
+
+  // 4. Kategoria
+  if (skill.categories) {
+    if (skill.categories.name && String(skill.categories.name).toLowerCase().includes(q)) return true;
+    if (skill.categories.slug && String(skill.categories.slug).toLowerCase().includes(q)) return true;
+  }
+  if (skill.category && typeof skill.category === 'string' && skill.category.toLowerCase().includes(q)) return true;
+
+  // 5. Namespace i właściciel
+  if (skill.namespace && String(skill.namespace).toLowerCase().includes(q)) return true;
+  if (skill.owner_name && String(skill.owner_name).toLowerCase().includes(q)) return true;
+  if (skill.owner_email && String(skill.owner_email).toLowerCase().includes(q)) return true;
+
+  return false;
+}
+
 async function cmdSkillList(flags, out, err) {
-  if (!flags.json) out('Pobieram listę skilli z DeerSkills Hub...');
-  const res = await skillsHub.listSkills({
-    query: flags.query,
-    tag: flags.tag,
-    category: flags.category,
-    scope: flags.scope,
-    limit: flags.limit || 100,
-  });
+  const searchQuery = flags.query ? String(flags.query).trim() : '';
+  const isSearch = Boolean(searchQuery);
 
-  if (!res.ok) {
-    err(`✗ Błąd pobierania skilli (${res.status}): ${res.data?.error || 'Brak dostępu'}`);
-    return;
+  if (!flags.json) {
+    if (isSearch) {
+      out(`Wyszukuję skille w DeerSkills Hub dla frazy „${searchQuery}” (hybrydowo: wektory + tekst)...`);
+    } else {
+      out('Pobieram listę skilli z DeerSkills Hub...');
+    }
+  }
+
+  let items = [];
+
+  if (isSearch) {
+    // 1. Serwerowe wyszukiwanie wektorowo-hybrydowe (PostgreSQL pgvector + trigram + keyword boost)
+    let queryEmbedding = null;
+    if (flags.semantic) {
+      if (!flags.json) out('Generuję wektor semantyczny zapytania...');
+      queryEmbedding = embedding.computeEmbedding(searchQuery);
+    }
+
+    const hybridRes = await skillsHub.searchSkillsHybrid({
+      queryText: searchQuery,
+      queryEmbedding,
+      threshold: queryEmbedding ? 0.1 : 0.05,
+      count: flags.limit || 50,
+    });
+
+    if (hybridRes.ok && Array.isArray(hybridRes.data)) {
+      items = hybridRes.data;
+
+      // 2. Jeśli zapytanie tekstowe dało 0 wyników, a dostępne jest lokalne generowanie wektorów — ponów semantycznie
+      if (items.length === 0 && !flags.semantic && embedding.isEmbeddingAvailable()) {
+        const autoEmb = embedding.computeEmbedding(searchQuery);
+        if (autoEmb) {
+          const semRes = await skillsHub.searchSkillsHybrid({
+            queryText: searchQuery,
+            queryEmbedding: autoEmb,
+            threshold: 0.12,
+            count: flags.limit || 50,
+          });
+          if (semRes.ok && Array.isArray(semRes.data) && semRes.data.length > 0) {
+            items = semRes.data;
+          }
+        }
+      }
+
+      if (flags.tag) {
+        items = items.filter((s) => Array.isArray(s.tags) && s.tags.includes(flags.tag));
+      }
+      if (flags.category) {
+        const cat = String(flags.category).toLowerCase();
+        items = items.filter((s) => s.category_slug === cat || (s.category_name && s.category_name.toLowerCase().includes(cat)));
+      }
+      if (flags.scope) {
+        items = items.filter((s) => s.scope === flags.scope);
+      }
+    } else {
+      // Fallback do pobierania pełnej listy i lokalnego przeszukiwania
+      const res = await skillsHub.listSkills({
+        tag: flags.tag,
+        category: flags.category,
+        scope: flags.scope,
+        limit: flags.limit || 200,
+      });
+
+      if (!res.ok) {
+        err(`✗ Błąd pobierania skilli (${res.status}): ${res.data?.error || 'Brak dostępu'}`);
+        return;
+      }
+
+      const allItems = Array.isArray(res.data) ? res.data : (res.data?.skills || []);
+      items = allItems.filter((s) => matchSkillQuery(s, searchQuery));
+    }
+  } else {
+    const res = await skillsHub.listSkills({
+      tag: flags.tag,
+      category: flags.category,
+      scope: flags.scope,
+      limit: flags.limit || 200,
+    });
+
+    if (!res.ok) {
+      err(`✗ Błąd pobierania skilli (${res.status}): ${res.data?.error || 'Brak dostępu'}`);
+      return;
+    }
+
+    items = Array.isArray(res.data) ? res.data : (res.data?.skills || []);
   }
 
-  const items = Array.isArray(res.data) ? res.data : (res.data?.skills || []);
   const agents = detectAgents({
     dir: flags.dir,
     agent: flags.agent,
@@ -203,6 +418,9 @@ async function cmdSkillList(flags, out, err) {
       const insp = inspectSkillForAgents(agents, s, lock);
       return {
         ...s,
+        similarity: s.similarity != null ? s.similarity : null,
+        vector_score: s.vector_score != null ? s.vector_score : null,
+        text_score: s.text_score != null ? s.text_score : null,
         overall_status: insp.overallStatus,
         agents: Object.fromEntries(
           Object.entries(insp.agents).map(([id, data]) => [
@@ -234,9 +452,22 @@ async function cmdSkillList(flags, out, err) {
     };
   }
 
-  out(`\n=== Dostępne Skille w DeerSkills Hub (${items.length}) ===\n`);
+  const titleHeader = isSearch
+    ? `=== Wyniki wyszukiwania w DeerSkills Hub dla „${searchQuery}” (${items.length}) ===`
+    : `=== Dostępne Skille w DeerSkills Hub (${items.length}) ===`;
+  out(`\n${titleHeader}\n`);
+
+  if (items.length === 0 && isSearch) {
+    out(`  Nie znaleziono żadnego skilla pasującego do frazy „${searchQuery}”.`);
+    out(`  (Przeszukano: wektory semantyczne, nazwy/slugi, opisy [summary], tagi oraz kategorie).`);
+    out(`\n💡 Wskazówka: Uruchom \x1b[36mdeertools skill list\x1b[0m aby zobaczyć wszystkie dostępne skille.`);
+    out('─'.repeat(78) + '\n');
+    return;
+  }
+
   for (const s of items) {
-    const badge = s.scope === 'global' ? '★ GLOBAL' : `@${s.namespace}`;
+    const namespace = s.namespace || (s.full_slug?.startsWith('@') ? s.full_slug.split('/')[0].slice(1) : '');
+    const badge = s.scope === 'global' ? '★ GLOBAL' : (namespace ? `@${namespace}` : (s.scope === 'team' ? '[Team]' : '[User]'));
     const latestVer = s.latest_version ? `v${s.latest_version}` : 'v1.0.0';
     const insp = inspectSkillForAgents(agents, s, lock);
 
@@ -248,8 +479,12 @@ async function cmdSkillList(flags, out, err) {
     }
 
     const agentBadges = agents.map((a) => insp.agents[a.id].badge).join(' ');
+    const simBadge = (s.similarity != null && isSearch)
+      ? `\x1b[36m[Trafność: ${Math.round(s.similarity * 100)}%]\x1b[0m`
+      : '';
 
-    out(`  • ${s.full_slug.padEnd(36)} ${latestVer.padEnd(10)} ${badge.padEnd(14)} ${insp.overallBadge}`);
+    const fullSlug = s.full_slug || s.slug || '';
+    out(`  • ${fullSlug.padEnd(36)} ${latestVer.padEnd(10)} ${badge.padEnd(14)} ${insp.overallBadge}${simBadge ? ' ' + simBadge : ''}`);
     out(`    Agenci: ${agentBadges}`);
     if (s.summary) out(`    ${s.summary.slice(0, 95)}...`);
     if (s.tags && s.tags.length) out(`    Tagi: ${s.tags.join(', ')}`);
@@ -279,9 +514,17 @@ async function cmdSkillList(flags, out, err) {
     out(`   • ${(a.name + ' (' + a.id + '):').padEnd(36)} ${badgeText}`);
   }
 
+  const anyAhead = items.some((s) => {
+    const insp = inspectSkillForAgents(agents, s, lock);
+    return insp.overallStatus === 'ahead';
+  });
+
   if (anyOutdated || anyMissing) {
     out(`\n💡 Aby zainstalować brakujące i zaktualizować wszystkie skille u agentów:`);
     out(`   \x1b[36mdeertools skill sync\x1b[0m   (lub: \x1b[36mdeertools sync\x1b[0m)`);
+  } else if (anyAhead) {
+    out(`\n💡 Wykryto skille nowsze lokalnie niż w Hubie:`);
+    out(`   \x1b[35mdeertools sync --push\x1b[0m   (aby wypchnąć je do DeerSkills Hub)`);
   } else {
     out(`\n✓ Wszystkie skille zespołu (${items.length}) są zainstalowane i aktualne u wszystkich wykrytych agentów.`);
   }
@@ -327,6 +570,18 @@ async function installSingleSkill(slug, requestedVersion, flags, out, err, { sil
 
   let count = 0;
   for (const agent of agents) {
+    // Bezpieczeństwo: jeśli lokalna wersja na dysku jest nowsza niż w Hubie, chroń przed nadpisaniem (wymagaj --force)
+    const existingFile = findSkillFileForAgent(agent, skill);
+    if (existingFile && !flags.force && !requestedVersion) {
+      const currentDiskVer = readSkillVersion(existingFile, readLock(flags.dir), skill);
+      if (currentDiskVer && compareSemver(currentDiskVer, versionData.version) > 0) {
+        if (!silentSummary) {
+          out(`  \x1b[35m★ [${agent.id}]\x1b[0m Pominięto instalację ${skill.slug}: wersja na dysku (v${currentDiskVer}) jest nowsza niż w Hubie (v${versionData.version}). Użyj --force aby nadpisać.`);
+        }
+        continue;
+      }
+    }
+
     try {
       const dest = installSkillContent(agent, skill.slug, versionData.skill_md_content);
       if (!silentSummary) {
@@ -372,8 +627,10 @@ async function installSingleSkill(slug, requestedVersion, flags, out, err, { sil
 
 /**
  * Instaluje lub synchronizuje wszystkie skille zespołu z DeerSkills Hub.
+ * Wspiera flagę --push (lub --auto-push): automatycznie publikuje nowsze lokalne wersje do Hubu.
  */
 async function cmdSkillSync(flags, out, err) {
+  const shouldPush = Boolean(flags.push || flags['auto-push']);
   out('Pobieram pełną listę skilli zespołu z DeerSkills Hub...');
   const res = await skillsHub.listSkills({ limit: 100 });
   if (!res.ok) {
@@ -399,14 +656,20 @@ async function cmdSkillSync(flags, out, err) {
     return;
   }
 
-  const lock = readLock(flags.dir);
+  const cwd = flags.dir || process.cwd();
+  const lock = readLock(cwd);
+  const hubSlugs = new Set(items.flatMap((s) => [s.slug, s.full_slug, s.slug.replace(/^@[^/]+\//, '')]));
+  const localSkills = scanLocalSkills(cwd, agents, hubSlugs);
+
   out(`Platformy docelowe: \x1b[36m${agents.map((a) => a.name || a.id).join(', ')}\x1b[0m`);
-  out(`Rozpoczynam synchronizację ${items.length} skilli zespołu...\n`);
+  out(`Rozpoczynam synchronizację ${items.length} skilli zespołu...${shouldPush ? ' \x1b[35m[Tryb dwukierunkowy: --push]\x1b[0m' : ''}\n`);
 
   let installedCount = 0;
   let updatedCount = 0;
   let unchangedCount = 0;
   let failedCount = 0;
+  let pushedCount = 0;
+  const aheadSkills = [];
 
   for (const s of items) {
     const slug = s.slug;
@@ -415,16 +678,74 @@ async function cmdSkillSync(flags, out, err) {
     const currentVer = current?.version;
     const latestVer = s.latest_version || '1.0.0';
 
-    if (currentVer && currentVer === latestVer && !flags.force) {
-      out(`  \x1b[32m✓\x1b[0m ${s.full_slug.padEnd(38)} v${currentVer.padEnd(8)} [Aktualny]`);
+    // Sprawdź wersję lokalną na dysku u agentów lub w .agents/skills
+    const localSkill = localSkills.get(slug) || localSkills.get(fullSlug) || localSkills.get(slug.replace(/^@[^/]+\//, ''));
+    let localDiskVer = localSkill?.version || null;
+
+    if (!localDiskVer) {
+      for (const agent of agents) {
+        const fp = findSkillFileForAgent(agent, s);
+        if (fp) {
+          const v = readSkillVersion(fp, lock, s);
+          if (v) { localDiskVer = v; break; }
+        }
+      }
+    }
+
+    const effectiveLocalVer = localDiskVer || currentVer;
+    const cmpLocalToHub = effectiveLocalVer ? compareSemver(effectiveLocalVer, latestVer) : -1;
+
+    // 1. Ochrona bezpieczeństwa: Lokalna wersja jest nowsza niż w Hubie (AHEAD)
+    if (cmpLocalToHub > 0) {
+      const pushDir = localSkill?.dir || (localSkill?.filePath ? path.dirname(localSkill.filePath) : null) || path.join(cwd, '.agents', 'skills', slug);
+      aheadSkills.push({
+        slug: s.full_slug || s.slug,
+        localVersion: effectiveLocalVer,
+        hubVersion: latestVer,
+        dir: pushDir,
+      });
+
+      if (shouldPush) {
+        try {
+          out(`  \x1b[35m↑ PUSH\x1b[0m ${s.full_slug.padEnd(36)} v${effectiveLocalVer} → Hub (wypychanie lokalnej nowości)...`);
+          const pushRes = await skillsHub.pushSkill(pushDir, {
+            version: effectiveLocalVer,
+            changelog: flags.changelog || `Synchronizacja dwukierunkowa: wypchnięto lokalną wersję v${effectiveLocalVer}`,
+          });
+          if (pushRes.ok) {
+            out(`  \x1b[32m✓ PUSHED\x1b[0m ${s.full_slug.padEnd(34)} v${effectiveLocalVer} opublikowano w DeerSkills Hub.`);
+            pushedCount += 1;
+            lock.skills[slug] = {
+              fullSlug: s.full_slug,
+              version: effectiveLocalVer,
+              installedAt: new Date().toISOString(),
+            };
+            writeLock(lock, cwd);
+          } else {
+            out(`  \x1b[31m✗ PUSH BŁĄD\x1b[0m ${s.full_slug}: ${pushRes.data?.error || 'Błąd publikacji'}`);
+          }
+        } catch (pe) {
+          out(`  \x1b[31m✗ PUSH BŁĄD\x1b[0m ${s.full_slug}: ${pe.message}`);
+        }
+      } else {
+        out(`  \x1b[35m★\x1b[0m ${s.full_slug.padEnd(38)} v${effectiveLocalVer.padEnd(8)} [Lokalnie nowszy niż w Hubie (Hub: v${latestVer})]`);
+      }
+      unchangedCount += 1;
+      continue;
+    }
+
+    // 2. Wersje identyczne - aktualny
+    if (effectiveLocalVer && cmpLocalToHub === 0 && !flags.force) {
+      out(`  \x1b[32m✓\x1b[0m ${s.full_slug.padEnd(38)} v${effectiveLocalVer.padEnd(8)} [Aktualny]`);
       unchangedCount += 1;
       continue;
     }
 
+    // 3. Wersja w Hubie nowsza niż lokalna - pobieramy downstream
     try {
       await installSingleSkill(s.full_slug || s.slug, latestVer, flags, out, err, { silentSummary: true });
-      if (currentVer) {
-        out(`  \x1b[33m↑\x1b[0m ${s.full_slug.padEnd(38)} v${latestVer.padEnd(8)} [Zaktualizowano z v${currentVer}]`);
+      if (effectiveLocalVer) {
+        out(`  \x1b[33m↑\x1b[0m ${s.full_slug.padEnd(38)} v${latestVer.padEnd(8)} [Zaktualizowano z v${effectiveLocalVer}]`);
         updatedCount += 1;
       } else {
         out(`  \x1b[36m+\x1b[0m ${s.full_slug.padEnd(38)} v${latestVer.padEnd(8)} [Zainstalowano]`);
@@ -436,17 +757,89 @@ async function cmdSkillSync(flags, out, err) {
     }
   }
 
+  // 4. Sprawdź lokalne skille, których w ogóle nie ma w Hubie
+  const unpushedLocalSkills = [];
+  for (const [lSlug, lk] of localSkills.entries()) {
+    if (!hubSlugs.has(lSlug)) {
+      unpushedLocalSkills.push(lk);
+    }
+  }
+
+  if (unpushedLocalSkills.length > 0) {
+    for (const ul of unpushedLocalSkills) {
+      if (shouldPush) {
+        try {
+          out(`  \x1b[35m↑ PUSH\x1b[0m ${ul.slug.padEnd(36)} v${ul.version} → Hub (nowy skill lokalny)...`);
+          const pushRes = await skillsHub.pushSkill(ul.dir, {
+            version: ul.version,
+            changelog: flags.changelog || `Inicjalna publikacja skilla lokalnego v${ul.version}`,
+          });
+          if (pushRes.ok) {
+            out(`  \x1b[32m✓ PUSHED\x1b[0m ${ul.slug.padEnd(34)} v${ul.version} opublikowano w DeerSkills Hub.`);
+            pushedCount += 1;
+          } else {
+            out(`  \x1b[31m✗ PUSH BŁĄD\x1b[0m ${ul.slug}: ${pushRes.data?.error || 'Błąd publikacji'}`);
+          }
+        } catch (pe) {
+          out(`  \x1b[31m✗ PUSH BŁĄD\x1b[0m ${ul.slug}: ${pe.message}`);
+        }
+      } else {
+        out(`  \x1b[90m○\x1b[0m ${ul.slug.padEnd(38)} v${ul.version.padEnd(8)} [Tylko lokalnie (brak w Hubie)]`);
+      }
+    }
+  }
+
   out('\n' + '─'.repeat(72));
   out(`\x1b[1m✓ Podsumowanie synchronizacji ekosystemu Deer Design:\x1b[0m`);
   out(`   • Nowo zainstalowane:       \x1b[36m${installedCount}\x1b[0m`);
   out(`   • Zaktualizowane:          \x1b[33m${updatedCount}\x1b[0m`);
   out(`   • Aktualne bez zmian:      \x1b[32m${unchangedCount}\x1b[0m`);
+  if (pushedCount > 0) {
+    out(`   • Wypchnięte do Hubu:      \x1b[35m${pushedCount}\x1b[0m`);
+  }
   if (failedCount > 0) {
     out(`   • Błędy instalacji:        \x1b[31m${failedCount}\x1b[0m`);
   }
   out(`   • Agenci docelowi:         ${agents.map((a) => a.id).join(', ')}`);
   out(`   • Zapisano w rejestrze:    ${LOCK_FILE}`);
-  out('─'.repeat(72) + '\n');
+  out('─'.repeat(72));
+
+  // Alert i komunikat o możliwości wypchnięcia (jeśli nie użyto --push, a wykryto lokalne nowości)
+  if (!shouldPush && (aheadSkills.length > 0 || unpushedLocalSkills.length > 0)) {
+    out('\n\x1b[35m┌─────────────────────────────────────────────────────────────────────────────┐\x1b[0m');
+    out('\x1b[35m│\x1b[0m  \x1b[1m💡 WYKRYTO SKILLE Z LOKALNYMI ZMIANAMI GOTOWYMI DO WYPCHNIĘCIA (AHEAD)\x1b[0m     \x1b[35m│\x1b[0m');
+    out('\x1b[35m├─────────────────────────────────────────────────────────────────────────────┤\x1b[0m');
+    out('\x1b[35m│\x1b[0m  Domyślny \x1b[36msync\x1b[0m pobiera nowości z Hubu i chroni Twoje lokalne pliki.          \x1b[35m│\x1b[0m');
+    out('\x1b[35m│\x1b[0m  Posiadasz skille nowsze niż w rejestrze firmowym DeerSkills Hub:           \x1b[35m│\x1b[0m');
+
+    const allNotices = [];
+    for (const a of aheadSkills) {
+      allNotices.push(`  • ${a.slug}: lokalnie v${a.localVersion} > w Hubie v${a.hubVersion}`);
+    }
+    for (const u of unpushedLocalSkills) {
+      allNotices.push(`  • ${u.slug}: lokalnie v${u.version} (nowy, brak w Hubie)`);
+    }
+
+    const maxToShow = 6;
+    for (let i = 0; i < Math.min(allNotices.length, maxToShow); i++) {
+      out(`\x1b[35m│\x1b[0m  \x1b[33m${allNotices[i].padEnd(73)}\x1b[0m\x1b[35m│\x1b[0m`);
+    }
+    if (allNotices.length > maxToShow) {
+      const moreText = `  ... i jeszcze ${allNotices.length - maxToShow} innych skilli z lokalnymi zmianami`;
+      out(`\x1b[35m│\x1b[0m  \x1b[90m${moreText.padEnd(73)}\x1b[0m\x1b[35m│\x1b[0m`);
+    }
+
+    out('\x1b[35m├─────────────────────────────────────────────────────────────────────────────┤\x1b[0m');
+    out('\x1b[35m│\x1b[0m  \x1b[1mAby wypchnąć zmiany do Hubu dla zespołu / firmy:\x1b[0m                           \x1b[35m│\x1b[0m');
+    if (aheadSkills.length > 0) {
+      out(`\x1b[35m│\x1b[0m    ▶ Pojedynczo:  \x1b[36mdeertools skill push ${aheadSkills[0].dir}\x1b[0m`);
+    }
+    out('\x1b[35m│\x1b[0m    ▶ Automatycznie (dwukierunkowo):                                         \x1b[35m│\x1b[0m');
+    out('\x1b[35m│\x1b[0m       \x1b[32mdeertools sync --push\x1b[0m   (lub: \x1b[32mdeertools skill sync --push\x1b[0m)                \x1b[35m│\x1b[0m');
+    out('\x1b[35m└─────────────────────────────────────────────────────────────────────────────┘\x1b[0m\n');
+  } else {
+    out('');
+  }
 }
 
 async function cmdSkillInstall(target, flags, out, err) {
@@ -985,4 +1378,7 @@ module.exports = {
   cmdSkillShare,
   checkSkillUpdates,
   updateSkills,
+  scanLocalSkills,
+  inspectSkillForAgents,
+  matchSkillQuery,
 };