showdar-skills 0.2.1 → 0.2.2

package/bin/showdar.js

@@ -49,6 +49,10 @@ async function main() {
   const version = await packageVersion();
 
   if (command === 'help' || command === '--help' || command === '-h') return printHelp(version);
+  if (command === '--version' || command === '-V') {
+    console.log(version);
+    return;
+  }
   if (args.includes('--help') || args.includes('-h')) return printHelp(version, command);
 
   const scope = ['init', 'status', 'doctor', 'remove'].includes(command) ? scopeAfter(args) : null;
@@ -83,6 +87,10 @@ async function main() {
       ? await initGlobal({ homeRoot: homedir(), packageRoot, profile, ai, skillIds, commandNames, packageVersion: version })
       : await initProject({ projectRoot, packageRoot, profile, ai, skillIds, commandNames, packageVersion: version });
     console.log(`Showdar Skills installed.\nScope: ${scope}\nProfile: ${profile}\nAI: ${ai}\nTargets: ${result.targets.join(', ')}\nSkills: ${result.skills}\nOpenCode commands: ${result.commands}`);
+    if (scope === 'project') {
+      console.log(`Requested: ${result.requestedSkills}\nInstalled in project: ${result.installedSkills}\nSatisfied by global: ${result.satisfiedByGlobal}\nSkipped duplicate copies: ${result.skippedDuplicates}`);
+    }
+    for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
     if (scope === 'global') console.log(`Manifest: ${globalManifestPath()}`);
     if (result.targets.includes('codex')) console.log('Codex: invoke skills directly with $showdar-<name> or let native skill discovery route by description.');
     if (result.targets.includes('opencode')) console.log('OpenCode: use native skill discovery or /showdar/<command>.');
@@ -97,7 +105,9 @@ async function main() {
       return;
     }
     console.log(`Showdar Skills\nScope: ${result.scope}\nProfile: ${result.profile}\nAI: ${result.ai}\nTargets: ${result.targets.join(', ')}\nSkills: ${result.skills}\nCommands: ${result.commands}\nHealth: ${result.healthy ? 'OK' : 'BROKEN'}`);
+    if (scope === 'project') console.log(`Requested: ${result.requestedSkills}\nInstalled in project: ${result.installedSkills}\nSatisfied by global: ${result.satisfiedByGlobal}`);
     for (const issue of result.issues) console.log(`- ${issue}`);
+    for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
     if (command === 'doctor' && !result.healthy) process.exitCode = 1;
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

package/src/project.js

@@ -100,6 +100,15 @@ function ownedPathSet(manifest) {
   return new Set((manifest?.files ?? []).map((entry) => entry.path));
 }
 
+function uniqueRoots(targets, resolveRoot) {
+  const roots = new Map();
+  for (const target of targets) {
+    const root = resolveRoot(target);
+    if (!roots.has(path.resolve(root))) roots.set(path.resolve(root), { root, target });
+  }
+  return [...roots.values()];
+}
+
 function safeOwnedPath(baseRoot, relative, allowedRoots = []) {
   if (typeof relative !== 'string' || !relative) return null;
   const roots = [baseRoot, ...allowedRoots].map((root) => path.resolve(root));
@@ -124,20 +133,45 @@ async function copyOwned({ baseRoot, source, destination, priorOwned, newFiles }
   newFiles.push({ path: relative, hash: await hashTree(destination) });
 }
 
-async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0', scope, skillRootForTarget, commandRoot, managedRoots = [] }) {
+async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0', scope, skillRootForTarget, commandRoot, managedRoots = [], homeRoot = homedir(), globalSkillRootForTarget = null }) {
   await mkdir(baseRoot, { recursive: true });
   const targets = resolveTargets(ai);
   const prior = await readManifest(manifestPath);
   const priorOwned = ownedPathSet(prior);
   const desiredPaths = new Set();
 
-  const skillRoots = new Map();
-  for (const target of targets) {
-    const root = skillRootForTarget(target);
-    skillRoots.set(path.resolve(root), root);
+  const skillRoots = uniqueRoots(targets, skillRootForTarget);
+  const globalManifest = scope === 'project' && globalSkillRootForTarget
+    ? await readManifest(globalManifestPath(homeRoot))
+    : null;
+  const globalOwned = ownedPathSet(globalManifest);
+  const globalSatisfaction = [];
+  const installedSkillIds = new Set();
+  const globallySatisfiedSkillIds = new Set();
+  let skippedDuplicates = 0;
+  const skillDestinations = [];
+
+  for (const skillId of skillIds) {
+    if (!(await exists(path.join(packageRoot, 'skills', skillId, 'SKILL.md')))) throw new Error(`Skill asset not found: ${skillId}`);
   }
-  for (const root of skillRoots.values()) {
-    for (const skillId of skillIds) desiredPaths.add(manifestPathFor(baseRoot, path.join(root, skillId)));
+
+  for (const { root, target } of skillRoots) {
+    for (const skillId of skillIds) {
+      const destination = path.join(root, skillId);
+      const relative = manifestPathFor(baseRoot, destination);
+      const destinationExists = await exists(destination);
+      const globalPath = globalSkillRootForTarget ? path.join(globalSkillRootForTarget(target), skillId) : null;
+      const globalRelative = globalPath ? manifestPathFor(homeRoot, globalPath) : null;
+      const globalAvailable = Boolean(globalPath && globalOwned.has(globalRelative) && await exists(globalPath));
+      if (scope === 'project' && globalAvailable && !destinationExists) {
+        skippedDuplicates += 1;
+        globallySatisfiedSkillIds.add(skillId);
+        globalSatisfaction.push({ skill: skillId, target, path: globalRelative });
+      } else {
+        desiredPaths.add(relative);
+        skillDestinations.push({ destination, skillId });
+      }
+    }
   }
   if (targets.includes('opencode')) {
     for (const name of commandNames) desiredPaths.add(manifestPathFor(baseRoot, path.join(commandRoot(), `${name}.md`)));
@@ -149,12 +183,10 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
   }
 
   const files = [];
-  for (const root of skillRoots.values()) {
-    for (const skillId of skillIds) {
-      const source = path.join(packageRoot, 'skills', skillId);
-      if (!(await exists(path.join(source, 'SKILL.md')))) throw new Error(`Skill asset not found: ${skillId}`);
-      await copyOwned({ baseRoot, source, destination: path.join(root, skillId), priorOwned, newFiles: files });
-    }
+  for (const { destination, skillId } of skillDestinations) {
+    const source = path.join(packageRoot, 'skills', skillId);
+    await copyOwned({ baseRoot, source, destination, priorOwned, newFiles: files });
+    installedSkillIds.add(skillId);
   }
 
   if (targets.includes('opencode')) {
@@ -174,16 +206,27 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
     ai,
     targets,
     skills: [...skillIds],
+    satisfiedByGlobal: globalSatisfaction,
     commands: targets.includes('opencode') ? [...commandNames] : [],
     files,
   };
   await mkdir(path.dirname(manifestPath), { recursive: true });
   await writeJsonAtomic(manifestPath, manifest);
   if (agentsRoot) await writeAgentsBlock(agentsRoot, skillIds);
-  return inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope });
+  const result = await inspectInstallation({
+    baseRoot, manifestPath, agentsRoot, scope, homeRoot,
+    globalSkillRootForTarget,
+  });
+  return {
+    ...result,
+    requestedSkills: skillIds.length,
+    installedSkills: installedSkillIds.size,
+    satisfiedByGlobal: globallySatisfiedSkillIds.size,
+    skippedDuplicates,
+  };
 }
 
-export async function initProject({ projectRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
+export async function initProject({ projectRoot, homeRoot = homedir(), packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
   return initInstallation({
     baseRoot: projectRoot,
     manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
@@ -195,7 +238,9 @@ export async function initProject({ projectRoot, packageRoot, profile, ai, skill
     commandNames,
     packageVersion,
     scope: 'project',
+    homeRoot,
     skillRootForTarget: (target) => skillRootFor(target, projectRoot),
+    globalSkillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
     commandRoot: () => opencodeCommandRoot(projectRoot),
   });
 }
@@ -219,17 +264,79 @@ export async function initGlobal({ homeRoot = homedir(), packageRoot, profile, a
   });
 }
 
-async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope, managedRoots = [] }) {
+async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope, managedRoots = [], homeRoot = homedir(), globalSkillRootForTarget = null }) {
   let manifest;
   try { manifest = await readManifest(manifestPath); }
-  catch (error) { return { installed: true, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, commands: 0, issues: [error.message] }; }
-  if (!manifest) return { installed: false, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, commands: 0, issues: ['Showdar is not installed.'] };
+  catch (error) { return { installed: true, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, requestedSkills: 0, installedSkills: 0, satisfiedByGlobal: 0, commands: 0, issues: [error.message], warnings: [] }; }
+  if (!manifest) return { installed: false, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, requestedSkills: 0, installedSkills: 0, satisfiedByGlobal: 0, commands: 0, issues: ['Showdar is not installed.'], warnings: [] };
 
   const issues = [];
+  const warnings = [];
+  const projectOwned = ownedPathSet(manifest);
+  const targets = manifest.targets?.length ? manifest.targets : manifest.ai ? resolveTargets(manifest.ai) : [];
+  const skillIds = manifest.skills ?? [];
+  const globalManifest = scope === 'project' && globalSkillRootForTarget
+    ? await readManifest(globalManifestPath(homeRoot))
+    : null;
+  const globalOwned = ownedPathSet(globalManifest);
+  const globalSatisfiedPaths = new Set();
+  const installedSkillIds = new Set();
+  const globallySatisfiedSkillIds = new Set();
+  const recordedGlobalSkills = new Set((manifest.satisfiedByGlobal ?? []).map((entry) => entry?.skill).filter(Boolean));
+
+  if (scope === 'project' && globalSkillRootForTarget) {
+    const projectRoots = uniqueRoots(targets, (target) => skillRootFor(target, baseRoot));
+    const globalRoots = uniqueRoots(targets, globalSkillRootForTarget);
+    const globalSkills = new Set();
+    for (const { root } of globalRoots) {
+      const prefix = `${manifestPathFor(homeRoot, root)}/`;
+      for (const entry of globalManifest?.files ?? []) {
+        if (!entry.path.startsWith(prefix)) continue;
+        const skillId = entry.path.slice(prefix.length).split('/')[0];
+        if (!skillId.startsWith('showdar-')) continue;
+        if (globalOwned.has(entry.path) && await exists(path.join(homeRoot, entry.path))) globalSkills.add(skillId);
+      }
+    }
+    const extra = [...globalSkills].filter((skillId) => !skillIds.includes(skillId)).sort();
+    if (extra.length) warnings.push(`Global Showdar installation exposes skills outside project profile "${manifest.profile ?? 'unknown'}": ${extra.join(', ')}. Project deduplication prevents duplicate copies but cannot hide globally installed skills. For strict project profile isolation: showdar remove --scope global`);
+
+    for (const { root, target } of projectRoots) {
+      for (const skillId of skillIds) {
+        const projectPath = path.join(root, skillId);
+        const projectRelative = manifestPathFor(baseRoot, projectPath);
+        const projectExists = await exists(projectPath);
+        const projectIsOwned = projectOwned.has(projectRelative);
+        const globalPath = path.join(globalSkillRootForTarget(target), skillId);
+        const globalRelative = manifestPathFor(homeRoot, globalPath);
+        const globalExists = await exists(globalPath);
+        const globalIsOwned = globalOwned.has(globalRelative);
+
+        if (projectExists && projectIsOwned) installedSkillIds.add(skillId);
+        if (projectExists && projectIsOwned && globalExists && globalIsOwned) {
+          warnings.push(`Duplicate Showdar skill discovery:\n  ${skillId}\n    project: ${projectPath}\n    global: ${globalPath}\n  To prefer project isolation: showdar remove --scope global`);
+        } else if (!projectExists && globalExists && globalIsOwned) {
+          globalSatisfiedPaths.add(projectRelative);
+          globallySatisfiedSkillIds.add(skillId);
+        } else if (!projectExists && !globalExists) {
+          issues.push(recordedGlobalSkills.has(skillId)
+            ? `Globally satisfied skill is missing: ${skillId} (${globalPath})`
+            : `Missing requested skill: ${projectPath}`);
+        } else if (projectExists && !projectIsOwned) {
+          issues.push(`Project skill path is not Showdar-owned: ${projectPath}`);
+        } else if (globalExists && !globalIsOwned) {
+          warnings.push(`Global skill path is not Showdar-owned: ${globalPath}`);
+        }
+      }
+    }
+  }
+
   for (const entry of manifest.files ?? []) {
     const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
     if (!target) { issues.push(`Invalid managed path: ${entry.path}`); continue; }
-    if (!(await exists(target))) { issues.push(`Missing managed path: ${entry.path}`); continue; }
+    if (!(await exists(target))) {
+      if (!globalSatisfiedPaths.has(entry.path)) issues.push(`Missing managed path: ${entry.path}`);
+      continue;
+    }
     const actual = await hashTree(target);
     if (actual !== entry.hash) issues.push(`Managed path drift detected: ${entry.path}`);
   }
@@ -250,9 +357,13 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
     profile: manifest.profile ?? null,
     ai: manifest.ai ?? null,
     targets: manifest.targets ?? [],
-    skills: (manifest.skills ?? []).length,
+    skills: skillIds.length,
+    requestedSkills: skillIds.length,
+    installedSkills: scope === 'project' && globalSkillRootForTarget ? installedSkillIds.size : skillIds.length,
+    satisfiedByGlobal: scope === 'project' && globalSkillRootForTarget ? globallySatisfiedSkillIds.size : 0,
     commands: (manifest.commands ?? []).length,
     issues,
+    warnings,
   };
 }
 
@@ -268,8 +379,15 @@ async function removeInstallation({ baseRoot, manifestPath, agentsRoot, managedR
   if (agentsRoot) await removeAgentsBlock(agentsRoot);
 }
 
-export async function inspectProject(projectRoot) {
-  return inspectInstallation({ baseRoot: projectRoot, manifestPath: path.join(projectRoot, PROJECT_MANIFEST), agentsRoot: projectRoot, scope: 'project' });
+export async function inspectProject(projectRoot, { homeRoot = homedir() } = {}) {
+  return inspectInstallation({
+    baseRoot: projectRoot,
+    manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
+    agentsRoot: projectRoot,
+    scope: 'project',
+    homeRoot,
+    globalSkillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
+  });
 }
 
 export async function inspectGlobal({ homeRoot = homedir() } = {}) {