@npeercy/skills 0.1.6 → 0.1.8

package/bin/skills.js

@@ -9,14 +9,14 @@ import {
   cmdEdit, cmdValidate, cmdPublish, cmdImport, cmdDoctor,
   cmdShare, cmdUnshare, cmdVisibility,
 } from '../lib/skills.js';
-import { loadConfig, saveConfig } from '../lib/config.js';
+import { runStartupChecks } from '../lib/startup.js';
 
 const USAGE = `skill-sharer — CLI skill manager for coding agents
 
 Usage: skills <command> [options]
 
 Setup:
-  init [--server <url>] [--token <token>] [--no-import]   Setup skill-sharer
+  init [--server <url>] [--token <token>]                 Setup skill-sharer (local-only; never publishes)
   login [--server <url>] [--token <token>]               Set/refresh token (prompts if missing)
   logout                                                  Remove stored token
 
@@ -51,49 +51,8 @@ const PKG = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
 );
 
-function cmpSemver(a, b) {
-  const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0);
-  const pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0);
-  const len = Math.max(pa.length, pb.length);
-  for (let i = 0; i < len; i++) {
-    const da = pa[i] || 0;
-    const db = pb[i] || 0;
-    if (da > db) return 1;
-    if (da < db) return -1;
-  }
-  return 0;
-}
-
-async function maybeWarnOutdated() {
-  if (process.env.SKILLS_NO_UPDATE_CHECK === '1') return;
-
-  const cfg = loadConfig();
-  const now = Date.now();
-  const oneDayMs = 24 * 60 * 60 * 1000;
-  const lastChecked = cfg.updateCheck?.lastChecked ? Date.parse(cfg.updateCheck.lastChecked) : 0;
-  let latest = cfg.updateCheck?.latestVersion || '';
-
-  if (!lastChecked || now - lastChecked > oneDayMs || !latest) {
-    try {
-      const res = await fetch('https://registry.npmjs.org/@npeercy%2fskills/latest');
-      if (res.ok) {
-        const data = await res.json();
-        latest = data.version || latest;
-        cfg.updateCheck = {
-          lastChecked: new Date(now).toISOString(),
-          latestVersion: latest,
-        };
-        saveConfig(cfg);
-      }
-    } catch {
-      // Silent fail; command should continue even offline.
-    }
-  }
-
-  if (latest && cmpSemver(latest, PKG.version) > 0) {
-    console.log(`⚠ Update available: @npeercy/skills ${PKG.version} → ${latest}`);
-    console.log('  Run: npm install -g @npeercy/skills\n');
-  }
+function hasJsonFlag(args) {
+  return args.includes('--json');
 }
 
 async function main() {
@@ -101,20 +60,24 @@ async function main() {
 
   // `skills` by itself -> list all local skills (managed + unmanaged + bundled)
   if (args.length === 0) {
-    await maybeWarnOutdated();
+    await runStartupChecks({ currentVersion: PKG.version, command: 'list', jsonMode: false });
     await cmdList({ verify: false, outdated: false, json: false });
     return;
   }
 
   if (args[0] === '--help' || args[0] === '-h') {
+    await runStartupChecks({ currentVersion: PKG.version, command: 'help', jsonMode: false });
     console.log(USAGE);
     return;
   }
 
   const cmd = args[0];
   const rest = args.slice(1);
-
-  await maybeWarnOutdated();
+  await runStartupChecks({
+    currentVersion: PKG.version,
+    command: cmd,
+    jsonMode: cmd === 'list' && hasJsonFlag(rest),
+  });
 
   try {
     switch (cmd) {
@@ -122,9 +85,9 @@ async function main() {
         const { values } = parseArgs({ args: rest, options: {
           server: { type: 'string' },
           token: { type: 'string' },
-          'no-import': { type: 'boolean', default: false },
+          'no-import': { type: 'boolean', default: false }, // deprecated compatibility; init never imports
         }, allowPositionals: false });
-        await cmdInit({ server: values.server, token: values.token, noImport: values['no-import'] });
+        await cmdInit({ server: values.server, token: values.token });
         break;
       }
       case 'login': {

package/lib/skills.js

@@ -255,7 +255,35 @@ function bundledBuiltins() {
   return out;
 }
 
-async function installBuiltins(agents) {
+export function getLocalDiagnostics() {
+  const st = loadState();
+  const agents = detectAgents();
+  const bundled = bundledBuiltins();
+  const unmanaged = discoverUnmanaged(agents, st);
+  const conflicts = discoverAgentNameConflicts(agents);
+
+  const installedBuiltinIds = new Set(
+    Object.keys(st.installed).filter(id => id.startsWith('__builtin__/local/')),
+  );
+  const missingBuiltins = bundled.filter(b => !installedBuiltinIds.has(b.id));
+
+  return {
+    state: st,
+    agents,
+    managedCount: Object.keys(st.installed).length,
+    bundledBuiltinsCount: bundled.length,
+    installedBuiltinsCount: installedBuiltinIds.size,
+    missingBuiltinsCount: missingBuiltins.length,
+    hasBuiltinsInstalled: missingBuiltins.length === 0,
+    missingBuiltins,
+    unmanagedCount: unmanaged.size,
+    conflictCount: conflicts.length,
+    unmanaged,
+    conflicts,
+  };
+}
+
+async function installBuiltins(agents, { quiet = false } = {}) {
   const st = loadState();
 
   const installed = [];
@@ -324,14 +352,14 @@ async function installBuiltins(agents) {
 
   saveState(st);
 
-  if (installed.length > 0) {
+  if (!quiet && installed.length > 0) {
     console.log('\nInstalled built-in skills:');
     for (const name of installed) {
       console.log(`  ✓ ${name} → ${Object.keys(agents).join(', ') || '(no agents detected)'}`);
     }
   }
 
-  if (skipped.length > 0) {
+  if (!quiet && skipped.length > 0) {
     console.log('\nSkipped built-ins to avoid skill-name conflicts in agents:');
     for (const s of skipped) {
       const where = s.conflicts.map(c => `${c.agent}/${c.entryName}`).join(', ');
@@ -339,6 +367,22 @@ async function installBuiltins(agents) {
     }
     console.log('  Tip: remove/rename duplicates if you want bundled docs linked automatically.');
   }
+
+  return { installed, skipped };
+}
+
+export async function ensureBuiltinsInstalled({ quiet = true } = {}) {
+  const d = getLocalDiagnostics();
+  if (d.missingBuiltinsCount === 0) {
+    return { changed: false, installed: [], skipped: [] };
+  }
+
+  const result = await installBuiltins(d.agents, { quiet });
+  return {
+    changed: result.installed.length > 0,
+    installed: result.installed,
+    skipped: result.skipped,
+  };
 }
 
 // --- Commands ---
@@ -385,14 +429,17 @@ export async function cmdInit(args) {
     throw new Error(`Token invalid: ${e.message}`);
   }
 
-  // Import existing skills
-  if (!args.noImport) {
-    await cmdImport({ all: true, quiet: false });
-  }
-
-  // Install built-ins
+  // Install built-ins (safe local setup)
   await installBuiltins(agents);
 
+  const unmanaged = discoverUnmanaged(agents, loadState());
+
+  console.log('\nSetup complete.');
+  console.log('Next command: skills');
+  if (unmanaged.size > 0) {
+    console.log(`Optional publish step: skills import   (found ${unmanaged.size} unmanaged local skill(s))`);
+  }
+
   console.log('\nReady! Ask your agent to "install a skill" or "create a new skill".');
 }
 
@@ -417,10 +464,9 @@ export async function cmdLogin(args) {
   console.log(`  Your publish namespace is: ${me.org}/${me.user}/<skillname>`);
 
   // First-time setup guidance
-  const st = loadState();
-  const agents = detectAgents();
-  const unmanaged = discoverUnmanaged(agents, st);
-  const hasBuiltins = Object.keys(st.installed).some(id => id.startsWith('__builtin__/local/'));
+  const diag = getLocalDiagnostics();
+  const unmanaged = diag.unmanaged;
+  const hasBuiltins = diag.hasBuiltinsInstalled;
 
   if (!hasBuiltins || unmanaged.size > 0) {
     console.log('\nSetup not complete yet.');
@@ -429,12 +475,18 @@ export async function cmdLogin(args) {
 
     const doSetup = await promptYesNo('Run guided setup now? (recommended)', true);
     if (doSetup) {
-      await cmdInit({ server: cfg.server, token: cfg.token, noImport: false });
+      await cmdInit({ server: cfg.server, token: cfg.token });
+      if (unmanaged.size > 0) {
+        const doImport = await promptYesNo('Import unmanaged local skills to registry now?', false);
+        if (doImport) {
+          await cmdImport({ all: true, quiet: false });
+        }
+      }
       return;
     }
 
     console.log('\nNext steps:');
-    if (!hasBuiltins) console.log('  skills init --no-import');
+    if (!hasBuiltins) console.log('  skills init');
     if (unmanaged.size > 0) console.log('  skills import');
   }
 }

package/lib/startup.js

@@ -0,0 +1,97 @@
+import { loadConfig, saveConfig } from './config.js';
+import { ensureBuiltinsInstalled, getLocalDiagnostics } from './skills.js';
+
+function cmpSemver(a, b) {
+  const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+
+async function latestPublishedVersion() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 2500);
+  try {
+    const res = await fetch('https://registry.npmjs.org/@npeercy%2fskills/latest', {
+      signal: controller.signal,
+    });
+    if (!res.ok) return '';
+    const data = await res.json();
+    return data.version || '';
+  } catch {
+    return '';
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function runUpdateCheck(currentVersion, { silent = false } = {}) {
+  if (process.env.SKILLS_NO_UPDATE_CHECK === '1') return;
+
+  const cfg = loadConfig();
+  const latestLive = await latestPublishedVersion();
+  const latest = latestLive || cfg.updateCheck?.latestVersion || '';
+
+  if (latestLive) {
+    cfg.updateCheck = {
+      lastChecked: new Date().toISOString(),
+      latestVersion: latestLive,
+    };
+    saveConfig(cfg);
+  }
+
+  if (!silent && latest && cmpSemver(latest, currentVersion) > 0) {
+    console.log(`⚠ Update available: @npeercy/skills ${currentVersion} → ${latest}`);
+    console.log('  Run: npm install -g @npeercy/skills\n');
+  }
+}
+
+async function runAutoHeal(command, { jsonMode = false } = {}) {
+  if (process.env.SKILLS_NO_STARTUP_HEAL === '1') return;
+  if (['init'].includes(command)) return;
+
+  const result = await ensureBuiltinsInstalled({ quiet: true });
+  if (!jsonMode && result.changed) {
+    console.log(`✓ Startup heal: installed ${result.installed.length} missing built-in skill(s).`);
+  }
+}
+
+function printSetupWarnings(command, startupInfo, { jsonMode = false } = {}) {
+  if (jsonMode) return;
+
+  // Avoid noisy preflight banner for direct setup/auth commands.
+  if (['init', 'login'].includes(command)) return;
+
+  const warnings = [];
+  if (!startupInfo.hasBuiltinsInstalled && startupInfo.bundledBuiltinsCount > 0) {
+    warnings.push('Built-in skills are not installed. Run: skills init');
+  }
+  if (startupInfo.unmanagedCount > 0) {
+    warnings.push(`Found ${startupInfo.unmanagedCount} unmanaged local skill(s). Run: skills import`);
+  }
+  if (startupInfo.conflictCount > 0) {
+    warnings.push(`Found ${startupInfo.conflictCount} duplicate skill-name conflict(s). Run: skills doctor`);
+  }
+
+  if (warnings.length > 0) {
+    console.log('⚠ Startup checks:');
+    for (const w of warnings) {
+      console.log(`  - ${w}`);
+    }
+    console.log('');
+  }
+}
+
+export async function runStartupChecks({ currentVersion, command, jsonMode = false }) {
+  await runUpdateCheck(currentVersion, { silent: jsonMode });
+  await runAutoHeal(command, { jsonMode });
+  const startupInfo = getLocalDiagnostics();
+  printSetupWarnings(command, startupInfo, { jsonMode });
+  return startupInfo;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npeercy/skills",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "CLI-first skill marketplace for coding agents",
   "type": "module",
   "bin": {