@trendai-crem/claude-skills 0.10.0 → 1.0.0

package/cli.js

@@ -1,265 +1,110 @@
 #!/usr/bin/env node
 
 import { execFileSync } from 'child_process';
-import { readFileSync, readdirSync, writeFileSync, copyFileSync, mkdirSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, copyFileSync, mkdirSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { homedir, tmpdir } from 'os';
 import { renameSync } from 'fs';
 
-const __dir = dirname(fileURLToPath(import.meta.url));
-
-const EXTERNAL_SOURCES = [
-  { repo: 'obra/superpowers', flags: ['--all'], label: 'superpowers' },
-];
-
-const run = (args, label) => {
-  try {
-    execFileSync('npx', args, { stdio: 'inherit' });
-    return true;
-  } catch (error) {
-    console.error(`\nFailed: ${label} (exit ${error.status})`);
-    return false;
-  }
-};
+import { HANDLERS } from './lib/handlers/index.js';
+import { loadSources } from './lib/config.js';
+import { loadManifest, writeManifest } from './lib/manifest.js';
+import { printSummary } from './lib/utils.js';
 
-console.log('Installing team skills...\n');
+const __dir = dirname(fileURLToPath(import.meta.url));
+const MANIFEST_PATH = join(homedir(), '.claude', 'claude-skills-manifest.json');
 
-// 1. External skills — failures are non-fatal
-const externalResults = EXTERNAL_SOURCES.map(({ repo, flags, label }) =>
-  ({ label, ok: run(['skills', 'add', repo, ...flags, '-g', '-y'], label) })
-);
+// ── Orchestrator ──────────────────────────────────────────────────────────────
 
-// 2. Team skills — required, overrides same-named externals
-const teamSkills = readdirSync(join(__dir, 'skills'), { withFileTypes: true })
-  .filter(e => e.isDirectory())
-  .map(e => e.name)
-  .sort();
+console.log('Installing claude-skills...\n');
 
-const teamOk = run(['skills', 'add', __dir, '--all', '-g', '-y'], 'team skills');
+const sources = loadSources(join(__dir, 'sources.json'));
+const manifest = loadManifest(MANIFEST_PATH, join(__dir, 'skills'));
+const allResults = [];
 
-// 3. Marketplace plugins — failures are non-fatal
-let marketplaceResults = [];
-try {
-  marketplaceResults = installMarketplacePlugins();
-} catch (err) {
-  console.error(`\nmarketplace plugin installation failed unexpectedly: ${err.message}`);
-}
+for (const entry of sources) {
+  if (!Object.hasOwn(HANDLERS, entry.type)) {
+    console.warn(`\nWARN: Unknown source type "${entry.type}" (label: ${entry.label}), skipping`);
+    continue;
+  }
 
-// Summary
-console.log('\nResults:');
-externalResults.forEach(({ label, ok }) => console.log(`  ${ok ? '✓' : '✗'} ${label}`));
-if (teamOk) {
-  teamSkills.forEach(name => console.log(`  ✓ ${name}`));
-} else {
-  console.log(`  ✗ team skills`);
-}
-marketplaceResults.forEach(({ plugin, action, ok }) =>
-  console.log(`  ${ok ? '✓' : '✗'} ${plugin} (${action})`)
-);
+  const handler = HANDLERS[entry.type];
+  const { label } = entry;
 
-if (!teamOk) {
-  console.error('\nFATAL: Team skills installation failed.');
-  process.exit(1);
-}
+  const desired  = handler.getDesired(entry, __dir);
+  const previous = new Set(manifest.sources?.[label] ?? []);
 
-const externalFailed = externalResults.filter(r => !r.ok);
-if (externalFailed.length > 0) {
-  console.warn(`\nWARN: ${externalFailed.length} external source(s) failed — team skills installed successfully.`);
-}
+  // Reconcile: uninstall items no longer in desired set.
+  // desired=null means the set couldn't be determined — skip removals, still install.
+  const stale = desired ? [...previous].filter(i => !desired.has(i)) : [];
+  if (stale.length) allResults.push(...handler.uninstall(stale, entry));
 
-const marketplaceFailed = marketplaceResults.filter(r => !r.ok);
-if (marketplaceFailed.length > 0) {
-  console.warn(`\nWARN: ${marketplaceFailed.length} marketplace plugin(s) failed — team skills installed successfully.`);
-}
+  // Install / update
+  allResults.push(...handler.install(entry, __dir));
 
-// Configure update-check hooks
-setupAutoUpdate();
-
-// Reads a JSON file and returns its parsed value if it is a non-null, non-array object.
-// Returns `fallback` on any error (missing file, parse failure, wrong type).
-function readJsonObject(filePath, fallback, label) {
-  if (!existsSync(filePath)) return fallback;
-  try {
-    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
-    console.warn(`\nWARN: Ignoring invalid ${label}: expected JSON object`);
-  } catch (err) {
-    console.warn(`\nWARN: Ignoring invalid ${label}: ${err.message}`);
+  // Update manifest (only when desired is known)
+  if (desired !== null) {
+    manifest.sources[label] = [...desired];
   }
-  return fallback;
 }
 
-// Extracts the registered source for a marketplace from known_marketplaces.json.
-// Handles: plain string, object with string .source, and GitHub registry format
-// { source: { source: "github", repo: "org/repo" } }.
-function getRegisteredMarketplaceSource(known, marketplaceName) {
-  const entry = known[marketplaceName];
-  if (typeof entry === 'string') return entry;
-  if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
-    if (typeof entry.source === 'string') return entry.source;
-    // GitHub registry format: { source: { source: "github", repo: "org/repo" }, ... }
-    if (entry.source?.source === 'github' && typeof entry.source?.repo === 'string') {
-      return entry.source.repo;
+// Post-loop cleanup: handle manifest labels no longer present in sources.json.
+const activeLabels = new Set(sources.map(e => e.label));
+for (const [orphanLabel, items] of Object.entries(manifest.sources ?? {})) {
+  if (activeLabels.has(orphanLabel)) continue;
+
+  if (orphanLabel.startsWith('__v1_')) {
+    // Synthetic migration labels: items are now tracked under real source labels.
+    // Just remove the synthetic entry — do NOT uninstall (items still managed).
+    delete manifest.sources[orphanLabel];
+    continue;
+  }
+
+  // Real orphaned label: source was removed from sources.json.
+  // Uninstall its previously managed items, then remove from manifest.
+  if (Array.isArray(items) && items.length > 0) {
+    const hasAtSign = items.some(i => typeof i === 'string' && i.includes('@'));
+    const handlerType = hasAtSign ? 'marketplace' : 'skills-repo';
+    if (Object.hasOwn(HANDLERS, handlerType)) {
+      allResults.push(...HANDLERS[handlerType].uninstall(items, { label: orphanLabel }));
     }
   }
-  return null;
-}
-
-// Normalizes a marketplace source to a canonical host/path form for comparison.
-// Accepts SSH URLs, HTTPS URLs, and GitHub shorthand (org/repo).
-// Returns null if the source cannot be parsed.
-function normalizeMarketplaceSource(rawSource) {
-  // GitHub shorthand: org/repo (no slashes in org, no protocol)
-  if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(rawSource)) {
-    return rawSource.toLowerCase();
-  }
-  const sshMatch = /^git@([^:]+):(.+?)(?:\.git)?$/.exec(rawSource);
-  if (sshMatch) {
-    return `${sshMatch[1].toLowerCase()}/${sshMatch[2].replace(/^\/+/, '').replace(/\.git$/, '')}`;
-  }
-  try {
-    const url = new URL(rawSource);
-    return `${url.hostname.toLowerCase()}/${url.pathname.replace(/^\/+/, '').replace(/\.git$/, '')}`;
-  } catch {
-    return null;
-  }
+  delete manifest.sources[orphanLabel];
 }
 
-// Installs or updates all plugins for a single marketplace entry.
-// Returns an array of { plugin, action, ok } results.
-function installFromMarketplace(entry, known, installed) {
-  // Input validation + allowlisting (SCD-1, OWASP-A04)
-  // Leading `-` is rejected to prevent argv injection: `claude plugin install -s` parses as flag.
-  const SAFE_NAME = /^(?!-)[A-Za-z0-9_][A-Za-z0-9_-]*$/;
-  const SAFE_SOURCE = /^(git@[\w.-]+:[\w.\-/]+\.git|https:\/\/[\w.-]+\/[\w.\-/]+\.git)$/;
-  const SAFE_GITHUB = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-
-  const { name: marketplaceName, source, plugins } = entry ?? {};
-
-  if (typeof marketplaceName !== 'string' || typeof source !== 'string' || !Array.isArray(plugins)) {
-    console.error('\nInvalid marketplace entry: missing required fields (name, source, plugins[])');
-    return [];
-  }
-  if (!SAFE_NAME.test(marketplaceName) || (!SAFE_SOURCE.test(source) && !SAFE_GITHUB.test(source))) {
-    console.error(`\nInvalid marketplace name or source: ${marketplaceName}`);
-    return [];
-  }
-  // Reject the entire entry on any invalid plugin name (fail-closed, not silent filter).
-  const invalidPlugins = plugins.filter(p => typeof p !== 'string' || !SAFE_NAME.test(p));
-  if (invalidPlugins.length > 0) {
-    console.error(`\nInvalid plugin names for ${marketplaceName}: ${invalidPlugins.map(p => JSON.stringify(p)).join(', ')}`);
-    return [];
-  }
-
-  console.log(`\nInstalling marketplace plugins (${marketplaceName})...\n`);
-
-  // Register marketplace if not already known — verify source matches to prevent supply-chain mismatch (OWASP-A08)
-  const registeredSource = getRegisteredMarketplaceSource(known, marketplaceName);
-  const normalizedSource = normalizeMarketplaceSource(source);
-  const normalizedRegistered = registeredSource ? normalizeMarketplaceSource(registeredSource) : null;
-
-  if (registeredSource && (!normalizedRegistered || normalizedRegistered !== normalizedSource)) {
-    console.error(`\nMarketplace source mismatch for ${marketplaceName}: registered as ${registeredSource}, but marketplace.json specifies ${source}`);
-    return plugins.map(plugin => ({ plugin, action: 'skipped (source mismatch)', ok: false }));
-  }
-
-  if (!registeredSource) {
-    try {
-      execFileSync('claude', ['plugin', 'marketplace', 'add', source, '--scope', 'user'], {
-        stdio: 'inherit',
-      });
-    } catch (error) {
-      const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
-      console.error(`\nFailed to register marketplace: ${marketplaceName} (${exitInfo})`);
-      return plugins.map(plugin => ({ plugin, action: 'skipped (no marketplace)', ok: false }));
-    }
-  }
-
-  // Always update marketplace to pull latest plugin versions before install/update
-  try {
-    execFileSync('claude', ['plugin', 'marketplace', 'update', marketplaceName], { stdio: 'inherit' });
-  } catch (error) {
-    const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
-    console.warn(`\nWARN: Failed to update marketplace ${marketplaceName} (${exitInfo}) — using cached version`);
-  }
-
-  return plugins.map(plugin => {
-    const key = `${plugin}@${marketplaceName}`;
-    const isInstalled = Object.hasOwn(installed, key); // Object.hasOwn avoids prototype chain traversal (SCD-7)
-    const action = isInstalled ? 'update' : 'install';
-    const args = isInstalled
-      ? ['plugin', 'update', key]
-      : ['plugin', 'install', key, '--scope', 'user'];
-    try {
-      execFileSync('claude', args, { stdio: 'inherit' });
-      return { plugin, action, ok: true };
-    } catch (error) {
-      const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
-      console.error(`\nFailed: ${key} ${action} (${exitInfo})`);
-      return { plugin, action, ok: false };
-    }
-  });
+// Skip manifest write if v1 migration was aborted (backup failed) — preserves original file.
+if (!manifest._writeSkipped) {
+  writeManifest(MANIFEST_PATH, manifest);
+} else {
+  console.warn('\nWARN: Manifest not updated — v1 backup failed. Run again to retry migration.');
 }
+printSummary(allResults);
 
-function installMarketplacePlugins() {
-  const configPath = join(__dir, 'marketplace.json');
-  if (!existsSync(configPath)) return [];
+// ── Auto-update hooks ─────────────────────────────────────────────────────────
 
-  // Parse marketplace.json — all failures are non-fatal (SCD-7)
-  const config = readJsonObject(configPath, null, 'marketplace.json');
-  const marketplaces = config?.marketplaces;
-  if (!Array.isArray(marketplaces) || marketplaces.length === 0) {
-    console.warn('\nWARN: marketplace.json has no valid "marketplaces" array, skipping');
-    return [];
-  }
-
-  // Load shared state once: known registry (for source verification) and installed plugins
-  const knownPath = join(homedir(), '.claude', 'plugins', 'known_marketplaces.json');
-  const knownExists = existsSync(knownPath);
-  const known = readJsonObject(knownPath, knownExists ? null : {}, 'known_marketplaces.json');
-  if (knownExists && known === null) {
-    console.error('\nInvalid known_marketplaces.json: refusing to register any marketplace automatically');
-    return marketplaces.flatMap(e =>
-      (e?.plugins ?? []).map(plugin => ({ plugin, action: 'skipped (invalid marketplace registry)', ok: false }))
-    );
-  }
-
-  const installedPath = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
-  const installedData = readJsonObject(installedPath, {}, 'installed_plugins.json');
-  // installed_plugins.json v2 nests under "plugins", v1 is flat
-  const rawInstalled = installedData.plugins ?? installedData;
-  const installed = (typeof rawInstalled === 'object' && rawInstalled !== null && !Array.isArray(rawInstalled))
-    ? rawInstalled
-    : {};
-
-  return marketplaces.flatMap(entry => installFromMarketplace(entry, known, installed));
-}
+setupAutoUpdate();
 
 function setupAutoUpdate() {
   const { version: installedVersion } = JSON.parse(
     readFileSync(join(__dir, 'package.json'), 'utf8')
   );
 
-  const claudeDir      = join(homedir(), '.claude');
-  const hooksDir       = join(claudeDir, 'hooks');
-  const cacheDir       = join(homedir(), '.cache');
-  const installScript  = join(hooksDir, 'claude-skills-install-update.sh');
-  const notifyScript   = join(hooksDir, 'auto-update-claude-skills.sh');
-  const installStamp   = join(cacheDir, 'claude-skills-install-check.json');
-  const notifyStamp    = join(cacheDir, 'claude-skills-version-check.json');
-  const settingsPath   = join(claudeDir, 'settings.json');
+  const claudeDir     = join(homedir(), '.claude');
+  const hooksDir      = join(claudeDir, 'hooks');
+  const cacheDir      = join(homedir(), '.cache');
+  const installScript = join(hooksDir, 'claude-skills-install-update.sh');
+  const notifyScript  = join(hooksDir, 'auto-update-claude-skills.sh');
+  const installStamp  = join(cacheDir, 'claude-skills-install-check.json');
+  const notifyStamp   = join(cacheDir, 'claude-skills-version-check.json');
+  const settingsPath  = join(claudeDir, 'settings.json');
 
   mkdirSync(hooksDir, { recursive: true });
   mkdirSync(cacheDir, { recursive: true });
 
-  // SessionStart: auto-install if update available (24h throttle, synchronous)
   writeFileSync(installScript, buildInstallScript(installStamp, installedVersion), { mode: 0o755 });
+  writeFileSync(notifyScript,  buildNotifyScript(notifyStamp,  installedVersion), { mode: 0o755 });
 
-  // UserPromptSubmit: notify only if update available (2h throttle)
-  writeFileSync(notifyScript, buildNotifyScript(notifyStamp, installedVersion), { mode: 0o755 });
-
-  // Merge hooks into ~/.claude/settings.json (idempotent)
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
@@ -273,25 +118,18 @@ function setupAutoUpdate() {
 
   settings.hooks ??= {};
 
-  // SessionStart — auto-install update (24h throttle)
   settings.hooks.SessionStart ??= [];
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
     e => !e.hooks?.some(h => typeof h.command === 'string' && h.command === installScript)
   );
-  settings.hooks.SessionStart.push({
-    hooks: [{ type: 'command', command: installScript }]
-  });
+  settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: installScript }] });
 
-  // UserPromptSubmit — notify only (2h throttle)
   settings.hooks.UserPromptSubmit ??= [];
   settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
     e => !e.hooks?.some(h => typeof h.command === 'string' && h.command === notifyScript)
   );
-  settings.hooks.UserPromptSubmit.push({
-    hooks: [{ type: 'command', command: notifyScript }]
-  });
+  settings.hooks.UserPromptSubmit.push({ hooks: [{ type: 'command', command: notifyScript }] });
 
-  // Atomic write
   const tmpPath = join(tmpdir(), `claude-settings-${process.pid}.json`);
   writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n');
   renameSync(tmpPath, settingsPath);
@@ -328,11 +166,10 @@ python3 -c "import json,sys; json.dump({'ts': int(sys.argv[1])}, open(sys.argv[2
 LATEST=$(npm view "$PACKAGE" version 2>/dev/null || echo "")
 [ -z "$LATEST" ] && exit 0
 [ "$LATEST" = "$INSTALLED" ] && exit 0
-[[ "$LATEST" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]] || exit 0
+[[ "$LATEST" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]] || exit 0
 
-# Install update synchronously
 INSTALL_DIR="$(mktemp -d)"
-if npm install --prefix "$INSTALL_DIR" "$PACKAGE@$LATEST" --silent 2>/dev/null \
+if npm install --prefix "$INSTALL_DIR" "$PACKAGE@$LATEST" --silent 2>/dev/null \\
    && node "$INSTALL_DIR/node_modules/$PACKAGE/cli.js" 2>/dev/null; then
   rm -rf "$INSTALL_DIR"
   python3 -c "import json,sys; print(json.dumps({'systemMessage': 'claude-skills updated: ' + sys.argv[1] + ' \u2192 ' + sys.argv[2]}))" "$INSTALLED" "$LATEST"
@@ -371,7 +208,7 @@ python3 -c "import json,sys; json.dump({'ts': int(sys.argv[1])}, open(sys.argv[2
 LATEST=$(npm view "$PACKAGE" version 2>/dev/null || echo "")
 [ -z "$LATEST" ] && exit 0
 [ "$LATEST" = "$INSTALLED" ] && exit 0
-[[ "$LATEST" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]] || exit 0
+[[ "$LATEST" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]] || exit 0
 
 python3 -c "import json,sys; print(json.dumps({'systemMessage': 'claude-skills update available: ' + sys.argv[1] + ' \u2192 ' + sys.argv[2] + chr(10) + 'Run: npx @trendai-crem/claude-skills@latest'}))" "$INSTALLED" "$LATEST"
 `;

package/lib/config.js

@@ -0,0 +1,49 @@
+import { readJsonObject } from './utils.js';
+
+/**
+ * Loads and normalizes sources.json.
+ *
+ * Each entry is normalized so:
+ *   - entry.label is always set (= entry.label ?? entry.name ?? entry.type)
+ *   - Entries missing type or a resolvable label are warned and skipped.
+ *
+ * @param {string} filePath - Absolute path to sources.json.
+ * @returns {Array} Normalized source entries (empty array on any failure).
+ */
+export function loadSources(filePath) {
+  const config = readJsonObject(filePath, null, 'sources.json');
+  if (!config) return [];
+
+  const raw = config.sources;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    console.warn('\nWARN: sources.json has no valid "sources" array, skipping all sources');
+    return [];
+  }
+
+  const seen = new Set();
+  const normalized = [];
+
+  for (const entry of raw) {
+    if (typeof entry?.type !== 'string') {
+      console.warn(`\nWARN: Skipping source entry with missing or non-string "type": ${JSON.stringify(entry)}`);
+      continue;
+    }
+
+    // Resolve canonical label — used as manifest key
+    const label = entry.label ?? entry.name;
+    if (typeof label !== 'string' || label.trim() === '') {
+      console.warn(`\nWARN: Skipping source entry of type "${entry.type}" with no resolvable label`);
+      continue;
+    }
+
+    if (seen.has(label)) {
+      console.warn(`\nWARN: Duplicate source label "${label}" — skipping second entry`);
+      continue;
+    }
+    seen.add(label);
+
+    normalized.push({ ...entry, label });
+  }
+
+  return normalized;
+}

package/lib/handlers/index.js

@@ -0,0 +1,9 @@
+import { skillsDirHandler } from './skills-dir.js';
+import { skillsRepoHandler } from './skills-repo.js';
+import { marketplaceHandler } from './marketplace.js';
+
+// Use Object.create(null) to prevent prototype chain traversal on adversarial type values.
+export const HANDLERS = Object.create(null);
+HANDLERS['skills-dir']  = skillsDirHandler;
+HANDLERS['skills-repo'] = skillsRepoHandler;
+HANDLERS['marketplace'] = marketplaceHandler;

package/lib/handlers/marketplace.js

@@ -0,0 +1,160 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { readJsonObject, SAFE_NAME, SAFE_SOURCE, SAFE_GITHUB } from '../utils.js';
+
+// Normalizes a marketplace source to a canonical host/path form for comparison.
+// Accepts SSH URLs, HTTPS URLs, and GitHub shorthand (org/repo).
+function normalizeMarketplaceSource(rawSource) {
+  if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(rawSource)) return rawSource.toLowerCase();
+  const sshMatch = /^git@([^:]+):(.+?)(?:\.git)?$/.exec(rawSource);
+  if (sshMatch) {
+    return `${sshMatch[1].toLowerCase()}/${sshMatch[2].replace(/^\/+/, '').replace(/\.git$/, '')}`;
+  }
+  try {
+    const url = new URL(rawSource);
+    return `${url.hostname.toLowerCase()}/${url.pathname.replace(/^\/+/, '').replace(/\.git$/, '')}`;
+  } catch {
+    return null;
+  }
+}
+
+// Extracts the registered source for a marketplace from known_marketplaces.json.
+function getRegisteredMarketplaceSource(known, marketplaceName) {
+  const entry = known[marketplaceName];
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+    if (typeof entry.source === 'string') return entry.source;
+    if (entry.source?.source === 'github' && typeof entry.source?.repo === 'string') {
+      return entry.source.repo;
+    }
+  }
+  return null;
+}
+
+/**
+ * Handler for marketplace plugin sources (type: "marketplace").
+ * Manages Claude Code plugins from a declared marketplace.
+ */
+export const marketplaceHandler = {
+  /**
+   * Returns the set of plugin@marketplace keys this entry should manage.
+   * Validates all fields against allowlist regexes (SCD-1, OWASP-A04).
+   * @param {object} entry - Source entry with `name`, `source`, `plugins` fields.
+   * @returns {Set<string>|null}
+   */
+  getDesired(entry) {
+    const { name: marketplaceName, source, plugins } = entry ?? {};
+    if (typeof marketplaceName !== 'string' || typeof source !== 'string' || !Array.isArray(plugins)) return null;
+    if (!SAFE_NAME.test(marketplaceName) || (!SAFE_SOURCE.test(source) && !SAFE_GITHUB.test(source))) return null;
+    const invalid = plugins.filter(p => typeof p !== 'string' || !SAFE_NAME.test(p));
+    if (invalid.length > 0) return null;
+    return new Set(plugins.map(p => `${p}@${marketplaceName}`));
+  },
+
+  /**
+   * Installs or updates plugins for this marketplace entry.
+   * All security controls from the original implementation are preserved.
+   * @returns {Array<{label, action, ok}>}
+   */
+  install(entry) {
+    const { name: marketplaceName, source, plugins } = entry ?? {};
+
+    // Full validation (SCD-1, OWASP-A04)
+    if (typeof marketplaceName !== 'string' || typeof source !== 'string' || !Array.isArray(plugins)) {
+      console.error('\nInvalid marketplace entry: missing required fields (name, source, plugins[])');
+      return [];
+    }
+    if (!SAFE_NAME.test(marketplaceName) || (!SAFE_SOURCE.test(source) && !SAFE_GITHUB.test(source))) {
+      console.error(`\nInvalid marketplace name or source: ${marketplaceName}`);
+      return [];
+    }
+    const invalidPlugins = plugins.filter(p => typeof p !== 'string' || !SAFE_NAME.test(p));
+    if (invalidPlugins.length > 0) {
+      console.error(`\nInvalid plugin names for ${marketplaceName}: ${invalidPlugins.map(p => JSON.stringify(p)).join(', ')}`);
+      return [];
+    }
+
+    console.log(`\nInstalling marketplace plugins (${marketplaceName})...\n`);
+
+    // Load known registry — fail-closed if corrupted (OWASP-A08, SCD-7)
+    const knownPath = join(homedir(), '.claude', 'plugins', 'known_marketplaces.json');
+    const knownExists = existsSync(knownPath);
+    const known = readJsonObject(knownPath, knownExists ? null : {}, 'known_marketplaces.json');
+    if (knownExists && known === null) {
+      console.error(`\nInvalid known_marketplaces.json: refusing to register marketplace ${marketplaceName}`);
+      return plugins.map(p => ({ label: `${p}@${marketplaceName}`, action: 'skipped (invalid registry)', ok: false }));
+    }
+
+    // Source mismatch check — prevent supply-chain redirection (OWASP-A08)
+    const registeredSource = getRegisteredMarketplaceSource(known, marketplaceName);
+    const normalizedSource = normalizeMarketplaceSource(source);
+    const normalizedRegistered = registeredSource ? normalizeMarketplaceSource(registeredSource) : null;
+    if (registeredSource && (!normalizedRegistered || normalizedRegistered !== normalizedSource)) {
+      console.error(`\nMarketplace source mismatch for ${marketplaceName}: registered as ${registeredSource}, but sources.json specifies ${source}`);
+      return plugins.map(p => ({ label: `${p}@${marketplaceName}`, action: 'skipped (source mismatch)', ok: false }));
+    }
+
+    // Register if not already known
+    if (!registeredSource) {
+      try {
+        execFileSync('claude', ['plugin', 'marketplace', 'add', source, '--scope', 'user'], { stdio: 'inherit' });
+      } catch (error) {
+        const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+        console.error(`\nFailed to register marketplace: ${marketplaceName} (${exitInfo})`);
+        return plugins.map(p => ({ label: `${p}@${marketplaceName}`, action: 'skipped (no marketplace)', ok: false }));
+      }
+    }
+
+    // Always update marketplace to pull latest plugin versions
+    try {
+      execFileSync('claude', ['plugin', 'marketplace', 'update', marketplaceName], { stdio: 'inherit' });
+    } catch (error) {
+      const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+      console.warn(`\nWARN: Failed to update marketplace ${marketplaceName} (${exitInfo}) — using cached version`);
+    }
+
+    // Load installed registry for install vs update decision (SCD-7)
+    const installedPath = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    const installedData = readJsonObject(installedPath, {}, 'installed_plugins.json');
+    const rawInstalled = installedData.plugins ?? installedData;
+    const installed = (typeof rawInstalled === 'object' && rawInstalled !== null && !Array.isArray(rawInstalled))
+      ? rawInstalled : {};
+
+    return plugins.map(plugin => {
+      const key = `${plugin}@${marketplaceName}`;
+      const isInstalled = Object.hasOwn(installed, key); // prototype-safe (SCD-7)
+      const action = isInstalled ? 'update' : 'install';
+      const args = isInstalled
+        ? ['plugin', 'update', key]
+        : ['plugin', 'install', key, '--scope', 'user'];
+      try {
+        execFileSync('claude', args, { stdio: 'inherit' });
+        return { label: key, action, ok: true };
+      } catch (error) {
+        const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+        console.error(`\nFailed: ${key} ${action} (${exitInfo})`);
+        return { label: key, action, ok: false };
+      }
+    });
+  },
+
+  /**
+   * Uninstalls stale plugin@marketplace keys.
+   * @param {string[]} staleItems - Keys like "plugin@marketplace".
+   * @returns {Array<{label, action, ok}>}
+   */
+  uninstall(staleItems) {
+    return staleItems.map(key => {
+      try {
+        execFileSync('claude', ['plugin', 'uninstall', key], { stdio: 'inherit' });
+        return { label: key, action: 'uninstall', ok: true };
+      } catch (error) {
+        const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+        console.error(`\nFailed to uninstall ${key} (${exitInfo})`);
+        return { label: key, action: 'uninstall', ok: false };
+      }
+    });
+  },
+};

package/lib/handlers/skills-dir.js

@@ -0,0 +1,55 @@
+import { execFileSync } from 'child_process';
+import { readdirSync } from 'fs';
+import { join } from 'path';
+import { uninstallSkills } from '../utils.js';
+
+/**
+ * Handler for local skills directory sources (type: "skills-dir").
+ * Installs all skill subdirectories from a local path.
+ */
+export const skillsDirHandler = {
+  /**
+   * Returns the set of skill names in the directory.
+   * @param {object} entry - Source entry with `path` field.
+   * @param {string} baseDir - Repository base directory.
+   * @returns {Set<string>|null}
+   */
+  getDesired(entry, baseDir) {
+    try {
+      const absPath = join(baseDir, entry.path);
+      const names = readdirSync(absPath, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .sort();
+      return new Set(names);
+    } catch (err) {
+      console.warn(`\nWARN: Cannot read skills directory "${entry.path}": ${err.message}`);
+      return null;
+    }
+  },
+
+  /**
+   * Installs all skills from the directory via `npx skills add`.
+   * @returns {Array<{label, action, ok}>}
+   */
+  install(entry, baseDir) {
+    const absPath = join(baseDir, entry.path);
+    try {
+      execFileSync('npx', ['skills', 'add', absPath, '--all', '-g', '-y'], { stdio: 'inherit' });
+      return [{ label: entry.label, action: 'install-group', ok: true }];
+    } catch (error) {
+      const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+      console.error(`\nFailed: ${entry.label} (${exitInfo})`);
+      return [{ label: entry.label, action: 'install-group', ok: false }];
+    }
+  },
+
+  /**
+   * Removes stale skills. Delegates to shared uninstallSkills utility.
+   * @param {string[]} staleItems - Skill names to remove.
+   * @returns {Array<{label, action, ok}>}
+   */
+  uninstall(staleItems) {
+    return uninstallSkills(staleItems);
+  },
+};

package/lib/handlers/skills-repo.js

@@ -0,0 +1,84 @@
+import { execFileSync } from 'child_process';
+import { SAFE_GITHUB, SAFE_SOURCE, uninstallSkills } from '../utils.js';
+
+// Allowed flags for skills-repo sources (allowlist to prevent flag injection).
+const ALLOWED_REPO_FLAGS = new Set(['--all', '--copy', '--full-depth']);
+
+/**
+ * Handler for remote skill repository sources (type: "skills-repo").
+ * Installs all skills from a GitHub/git repository.
+ */
+export const skillsRepoHandler = {
+  /**
+   * Lists available skills in the repo via --list flag (no install).
+   * Returns null if the query fails — reconcile is skipped but install still runs.
+   * Returns an empty Set if the repo has no skills (reconcile removes all stale).
+   * @param {object} entry - Source entry with `repo` and `flags` fields.
+   * @returns {Set<string>|null}
+   */
+  getDesired(entry) {
+    if (!_validateEntry(entry)) return null;
+    try {
+      const output = execFileSync(
+        'npx', ['skills', 'add', entry.repo, ...(entry.flags ?? []), '-l'],
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      const names = output.split('\n')
+        .filter(l => /^│    [a-z]/.test(l))
+        .map(l => l.replace(/^│\s+/, '').trim());
+      if (names.length === 0) {
+        console.warn(`\nWARN: Could not parse skill list from ${entry.repo} — reconcile skipped`);
+        return null;
+      }
+      return new Set(names);
+    } catch (error) {
+      console.warn(`\nWARN: Cannot list skills from ${entry.repo}: ${error.message}`);
+      return null; // network failure — skip reconcile, still install
+    }
+  },
+
+  /**
+   * Installs all skills from the repo via `npx skills add`.
+   * @returns {Array<{label, action, ok}>}
+   */
+  install(entry) {
+    if (!_validateEntry(entry)) {
+      return [{ label: entry?.label ?? 'skills-repo', action: 'install-group', ok: false }];
+    }
+    try {
+      execFileSync(
+        'npx', ['skills', 'add', entry.repo, ...(entry.flags ?? []), '-g', '-y'],
+        { stdio: 'inherit' }
+      );
+      return [{ label: entry.label, action: 'install-group', ok: true }];
+    } catch (error) {
+      const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+      console.error(`\nFailed: ${entry.label} (${exitInfo})`);
+      return [{ label: entry.label, action: 'install-group', ok: false }];
+    }
+  },
+
+  /**
+   * Removes stale skills via `npx skills remove`. Delegates to shared utility.
+   * @param {string[]} staleItems - Skill names to remove.
+   * @returns {Array<{label, action, ok}>}
+   */
+  uninstall(staleItems) {
+    return uninstallSkills(staleItems);
+  },
+};
+
+// Validates repo and flags fields before passing to execFileSync (SCD-1, OWASP-A04).
+function _validateEntry(entry) {
+  if (typeof entry?.repo !== 'string' ||
+      (!SAFE_GITHUB.test(entry.repo) && !SAFE_SOURCE.test(entry.repo))) {
+    console.error(`\nInvalid skills-repo entry: invalid repo "${entry?.repo}"`);
+    return false;
+  }
+  const flags = entry.flags ?? [];
+  if (!Array.isArray(flags) || flags.some(f => typeof f !== 'string' || !ALLOWED_REPO_FLAGS.has(f))) {
+    console.error(`\nInvalid skills-repo entry: unsupported flags ${JSON.stringify(flags)}`);
+    return false;
+  }
+  return true;
+}

package/lib/manifest.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync, writeFileSync, copyFileSync, readdirSync, renameSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { readJsonObject } from './utils.js';
+
+/**
+ * Loads the manifest from disk, automatically migrating v1 format to v2.
+ * On migration, backs up the original as manifest.json.v1.bak.
+ *
+ * v1 format: { plugins: [...], skills: [...] }
+ * v2 format: { version: 2, sources: { "label": [...items] } }
+ *
+ * @param {string} manifestPath - Absolute path to the manifest file.
+ * @param {string} skillsDirPath - Absolute path to the skills/ directory (for v1 migration attribution).
+ * @returns {{ version: number, sources: object, _writeSkipped?: boolean }}
+ *   If `_writeSkipped` is true, the caller MUST NOT call writeManifest() — the
+ *   original manifest file must be preserved for the next run to retry migration.
+ */
+export function loadManifest(manifestPath, skillsDirPath) {
+  const raw = readJsonObject(manifestPath, null, 'claude-skills-manifest.json');
+
+  // No manifest yet — start fresh
+  if (!raw) return { version: 2, sources: {} };
+
+  // Already v2
+  if (raw.version === 2 && raw.sources && typeof raw.sources === 'object') {
+    return raw;
+  }
+
+  // Migrate v1 → v2
+  console.log('\nMigrating claude-skills manifest from v1 to v2...');
+
+  // Backup before overwriting
+  const backupPath = `${manifestPath}.v1.bak`;
+  try {
+    copyFileSync(manifestPath, backupPath);
+    console.log(`  Backed up v1 manifest to ${backupPath}`);
+  } catch (err) {
+    console.error(`  ERROR: Cannot back up v1 manifest (${err.message}). Skipping migration to preserve data.`);
+    // Signal caller to skip writeManifest so the original v1 file is preserved.
+    // Next run retries migration once the backup succeeds.
+    return { version: 2, sources: {}, _writeSkipped: true };
+  }
+
+  return migrateV1toV2(raw, skillsDirPath);
+}
+
+/**
+ * Migrates a v1 manifest to v2 format.
+ *
+ * Algorithm:
+ *   - skills that exist in skills/ dir → sources["team-skills"]
+ *   - remaining skills → sources["__v1_migrated"] (reconcile-skipped on first run)
+ *   - plugins with @marketplace suffix → sources[marketplace-name]
+ *   - plugins with unknown marketplace → sources["__v1_orphaned"]
+ */
+function migrateV1toV2(v1, skillsDirPath) {
+  const sources = {};
+
+  // Migrate skills
+  if (Array.isArray(v1.skills) && v1.skills.length > 0) {
+    let teamSkillNames = new Set();
+    try {
+      teamSkillNames = new Set(
+        readdirSync(skillsDirPath, { withFileTypes: true })
+          .filter(e => e.isDirectory())
+          .map(e => e.name)
+      );
+    } catch { /* skills dir unreadable — all go to __v1_migrated */ }
+
+    const teamSkills = v1.skills.filter(s => teamSkillNames.has(s));
+    const migratedSkills = v1.skills.filter(s => !teamSkillNames.has(s));
+
+    if (teamSkills.length > 0) sources['team-skills'] = teamSkills;
+    if (migratedSkills.length > 0) {
+      sources['__v1_migrated'] = migratedSkills;
+      console.log(`  ${migratedSkills.length} skills moved to __v1_migrated (will resolve on next full run)`);
+    }
+  }
+
+  // Migrate plugins — distribute by @marketplace-name suffix
+  if (Array.isArray(v1.plugins) && v1.plugins.length > 0) {
+    const byMarketplace = {};
+    const orphaned = [];
+
+    for (const key of v1.plugins) {
+      const atIdx = key.lastIndexOf('@');
+      if (atIdx !== -1) {
+        const mName = key.slice(atIdx + 1);
+        (byMarketplace[mName] ??= []).push(key);
+      } else {
+        orphaned.push(key);
+      }
+    }
+
+    for (const [mName, keys] of Object.entries(byMarketplace)) {
+      sources[mName] = keys;
+    }
+    if (orphaned.length > 0) {
+      sources['__v1_orphaned'] = orphaned;
+      console.log(`  ${orphaned.length} plugins moved to __v1_orphaned (unknown marketplace)`);
+    }
+  }
+
+  return { version: 2, sources };
+}
+
+/**
+ * Writes the manifest atomically (tmp file + rename).
+ *
+ * @param {string} manifestPath - Absolute path to the manifest file.
+ * @param {{ version: number, sources: object }} manifest
+ */
+export function writeManifest(manifestPath, manifest) {
+  const tmp = join(tmpdir(), `claude-skills-manifest-${process.pid}.json`);
+  writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n');
+  renameSync(tmp, manifestPath);
+}

package/lib/utils.js

@@ -0,0 +1,60 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+
+// Shared allowlist constants — all handlers MUST validate entry fields against these
+// before passing to execFileSync (SCD-1, OWASP-A04).
+export const SAFE_NAME   = /^(?!-)[A-Za-z0-9_][A-Za-z0-9_-]*$/;
+export const SAFE_SOURCE = /^(git@[\w.-]+:[\w.\-/]+\.git|https:\/\/[\w.-]+\/[\w.\-/]+\.git)$/;
+export const SAFE_GITHUB = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+/**
+ * Reads a JSON file and returns its parsed value if it is a non-null, non-array object.
+ * Returns `fallback` on any error (missing file, parse failure, wrong type).
+ *
+ * @param {string} filePath - Absolute path to the JSON file.
+ * @param {*} fallback - Value returned when the file is missing or unreadable.
+ * @param {string} label - Human-readable label used in warning messages.
+ * @returns {object|*} The parsed object, or fallback.
+ */
+export function readJsonObject(filePath, fallback, label) {
+  if (!existsSync(filePath)) return fallback;
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+    console.warn(`\nWARN: Ignoring invalid ${label}: expected JSON object`);
+  } catch (err) {
+    console.warn(`\nWARN: Ignoring invalid ${label}: ${err.message}`);
+  }
+  return fallback;
+}
+
+/**
+ * Removes skills by name via `npx skills remove`. Used by skills-dir and skills-repo handlers.
+ *
+ * @param {string[]} staleItems - Skill names to remove.
+ * @returns {Array<{label, action, ok}>}
+ */
+export function uninstallSkills(staleItems) {
+  if (staleItems.length === 0) return [];
+  try {
+    execFileSync('npx', ['skills', 'remove', ...staleItems, '-g', '-y'], { stdio: 'inherit' });
+    return staleItems.map(s => ({ label: s, action: 'uninstall', ok: true }));
+  } catch (error) {
+    const exitInfo = error.status != null ? `exit ${error.status}` : error.code ?? error.message;
+    console.error(`\nFailed to remove stale skills (${exitInfo})`);
+    return staleItems.map(s => ({ label: s, action: 'uninstall', ok: false }));
+  }
+}
+
+/**
+ * Prints the consolidated install/uninstall results summary.
+ *
+ * @param {Array<{label: string, action: string, ok: boolean}>} results
+ */
+export function printSummary(results) {
+  console.log('\nResults:');
+  results.forEach(({ label, action, ok }) => {
+    const suffix = action !== 'install-group' ? ` (${action})` : '';
+    console.log(`  ${ok ? '✓' : '✗'} ${label}${suffix}`);
+  });
+}

package/marketplace.json

@@ -8,8 +8,7 @@
         "atlassian-tools",
         "google-style-guides",
         "l2-automation",
-        "service-doc-generator",
-        "claude-on-teams"
+        "service-doc-generator"
       ]
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trendai-crem/claude-skills",
-  "version": "0.10.0",
+  "version": "1.0.0",
   "description": "Claude Code skills installer for the trendai-crem team",
   "license": "UNLICENSED",
   "repository": {
@@ -12,7 +12,9 @@
   },
   "files": [
     "cli.js",
+    "sources.json",
     "marketplace.json",
+    "lib/",
     "skills/"
   ],
   "type": "module",

package/sources.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "type": "skills-dir",
+      "path": "./skills",
+      "label": "team-skills"
+    },
+    {
+      "type": "skills-repo",
+      "repo": "obra/superpowers",
+      "flags": [
+        "--all"
+      ],
+      "label": "superpowers"
+    },
+    {
+      "type": "marketplace",
+      "name": "ai-skill-marketplace",
+      "source": "git@github.com:trend-ai-taskforce/ai-skill-marketplace.git",
+      "plugins": [
+        "wiki-tools",
+        "atlassian-tools",
+        "google-style-guides",
+        "l2-automation",
+        "service-doc-generator",
+        "claude-on-teams"
+      ]
+    },
+    {
+      "type": "marketplace",
+      "name": "claude-plugins-official",
+      "source": "anthropics/claude-plugins-official",
+      "plugins": [
+        "ralph-loop"
+      ]
+    }
+  ]
+}