@rbbtsn0w/adg 0.1.0-alpha.1

package/vendor/skills/src/list.ts

@@ -0,0 +1,231 @@
+import { homedir } from 'os';
+import type { AgentType } from './types.ts';
+import { agents } from './agents.ts';
+import { listInstalledSkills, type InstalledSkill } from './installer.ts';
+import { sanitizeMetadata } from './sanitize.ts';
+import { getAllLockedSkills } from './skill-lock.ts';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[38;5;102m';
+const TEXT = '\x1b[38;5;145m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+
+interface ListOptions {
+  global?: boolean;
+  agent?: string[];
+  json?: boolean;
+}
+
+/**
+ * Shortens a path for display: replaces homedir with ~ and cwd with .
+ */
+function shortenPath(fullPath: string, cwd: string): string {
+  const home = homedir();
+  if (fullPath.startsWith(home)) {
+    return fullPath.replace(home, '~');
+  }
+  if (fullPath.startsWith(cwd)) {
+    return '.' + fullPath.slice(cwd.length);
+  }
+  return fullPath;
+}
+
+/**
+ * Formats a list of items, truncating if too many
+ */
+function formatList(items: string[], maxShow: number = 5): string {
+  if (items.length <= maxShow) {
+    return items.join(', ');
+  }
+  const shown = items.slice(0, maxShow);
+  const remaining = items.length - maxShow;
+  return `${shown.join(', ')} +${remaining} more`;
+}
+
+export function parseListOptions(args: string[]): ListOptions {
+  const options: ListOptions = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-g' || arg === '--global') {
+      options.global = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '-a' || arg === '--agent') {
+      options.agent = options.agent || [];
+      // Collect all following arguments until next flag
+      while (i + 1 < args.length && !args[i + 1]!.startsWith('-')) {
+        options.agent.push(args[++i]!);
+      }
+    }
+  }
+
+  return options;
+}
+
+export async function runList(args: string[]): Promise<void> {
+  const options = parseListOptions(args);
+
+  // Default to project only (local), use -g for global
+  const scope = options.global === true ? true : false;
+
+  // Validate agent filter if provided
+  let agentFilter: AgentType[] | undefined;
+  if (options.agent && options.agent.length > 0) {
+    const validAgents = Object.keys(agents);
+    const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
+
+    if (invalidAgents.length > 0) {
+      console.log(`${YELLOW}Invalid agents: ${invalidAgents.join(', ')}${RESET}`);
+      console.log(`${DIM}Valid agents: ${validAgents.join(', ')}${RESET}`);
+      process.exit(1);
+    }
+
+    agentFilter = options.agent as AgentType[];
+  }
+
+  const installedSkills = await listInstalledSkills({
+    global: scope,
+    agentFilter,
+  });
+
+  // JSON output mode: structured, no ANSI, untruncated agent lists
+  if (options.json) {
+    const jsonOutput = installedSkills.map((skill) => ({
+      name: skill.name,
+      path: skill.canonicalPath,
+      scope: skill.scope,
+      agents: skill.agents.map((a) => agents[a].displayName),
+    }));
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return;
+  }
+
+  // Fetch lock entries to get plugin grouping info
+  const lockedSkills = await getAllLockedSkills();
+
+  const cwd = process.cwd();
+  const scopeLabel = scope ? 'Global' : 'Project';
+
+  if (installedSkills.length === 0) {
+    if (options.json) {
+      console.log('[]');
+      return;
+    }
+    console.log(`${DIM}No ${scopeLabel.toLowerCase()} skills found.${RESET}`);
+    if (scope) {
+      console.log(`${DIM}Try listing project skills without -g${RESET}`);
+    } else {
+      console.log(`${DIM}Try listing global skills with -g${RESET}`);
+    }
+    return;
+  }
+
+  function printSkill(
+    skill: InstalledSkill,
+    indent: boolean = false,
+    maxNameLength: number = 0,
+    maxPathLength: number = 0
+  ): void {
+    const prefix = indent ? '  ' : '';
+    const shortPath = shortenPath(skill.canonicalPath, cwd);
+    const agentNames = skill.agents.map((a) => agents[a].displayName);
+    const agentInfo =
+      skill.agents.length > 0 ? formatList(agentNames) : `${YELLOW}not linked${RESET}`;
+
+    // Pad skill name and path for alignment
+    const paddedName = sanitizeMetadata(skill.name).padEnd(maxNameLength);
+    const paddedPath = shortPath.padEnd(maxPathLength);
+
+    console.log(
+      `${prefix}${CYAN}${paddedName}${RESET} ${DIM}${paddedPath}${RESET} ${DIM}Agents:${RESET} ${agentInfo}`
+    );
+  }
+
+  console.log(`${BOLD}${scopeLabel} Skills${RESET}`);
+  console.log();
+
+  // Group skills by plugin
+  const groupedSkills: Record<string, InstalledSkill[]> = {};
+  const ungroupedSkills: InstalledSkill[] = [];
+
+  for (const skill of installedSkills) {
+    const lockEntry = lockedSkills[skill.name];
+    if (lockEntry?.pluginName) {
+      const group = lockEntry.pluginName;
+      if (!groupedSkills[group]) {
+        groupedSkills[group] = [];
+      }
+      groupedSkills[group].push(skill);
+    } else {
+      ungroupedSkills.push(skill);
+    }
+  }
+
+  const hasGroups = Object.keys(groupedSkills).length > 0;
+
+  if (hasGroups) {
+    // Print groups sorted alphabetically
+    const sortedGroups = Object.keys(groupedSkills).sort();
+    for (const group of sortedGroups) {
+      // Convert kebab-case to Title Case for display header
+      const title = group
+        .split('-')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+
+      console.log(`${BOLD}${title}${RESET}`);
+      const skills = groupedSkills[group];
+      if (skills) {
+        // Calculate max lengths for alignment within this group
+        let maxNameLength = 0;
+        let maxPathLength = 0;
+        for (const skill of skills) {
+          const nameLength = sanitizeMetadata(skill.name).length;
+          const pathLength = shortenPath(skill.canonicalPath, cwd).length;
+          if (nameLength > maxNameLength) maxNameLength = nameLength;
+          if (pathLength > maxPathLength) maxPathLength = pathLength;
+        }
+        for (const skill of skills) {
+          printSkill(skill, true, maxNameLength, maxPathLength);
+        }
+      }
+      console.log();
+    }
+
+    // Print ungrouped skills if any exist
+    if (ungroupedSkills.length > 0) {
+      console.log(`${BOLD}General${RESET}`);
+      // Calculate max lengths for alignment within ungrouped skills
+      let maxNameLength = 0;
+      let maxPathLength = 0;
+      for (const skill of ungroupedSkills) {
+        const nameLength = sanitizeMetadata(skill.name).length;
+        const pathLength = shortenPath(skill.canonicalPath, cwd).length;
+        if (nameLength > maxNameLength) maxNameLength = nameLength;
+        if (pathLength > maxPathLength) maxPathLength = pathLength;
+      }
+      for (const skill of ungroupedSkills) {
+        printSkill(skill, true, maxNameLength, maxPathLength);
+      }
+      console.log();
+    }
+  } else {
+    // No groups, print flat list as before
+    // Calculate max lengths for alignment in flat list
+    let maxNameLength = 0;
+    let maxPathLength = 0;
+    for (const skill of installedSkills) {
+      const nameLength = sanitizeMetadata(skill.name).length;
+      const pathLength = shortenPath(skill.canonicalPath, cwd).length;
+      if (nameLength > maxNameLength) maxNameLength = nameLength;
+      if (pathLength > maxPathLength) maxPathLength = pathLength;
+    }
+    for (const skill of installedSkills) {
+      printSkill(skill, false, maxNameLength, maxPathLength);
+    }
+    console.log();
+  }
+}

package/vendor/skills/src/local-lock.ts

@@ -0,0 +1,182 @@
+import { readFile, writeFile, readdir, stat } from 'fs/promises';
+import { join, relative } from 'path';
+import { createHash } from 'crypto';
+
+const LOCAL_LOCK_FILE = 'skills-lock.json';
+const CURRENT_VERSION = 1;
+
+/**
+ * Represents a single skill entry in the local (project) lock file.
+ *
+ * Intentionally minimal and timestamp-free to minimize merge conflicts.
+ * Two branches adding different skills produce non-overlapping JSON keys
+ * that git can auto-merge cleanly.
+ */
+export interface LocalSkillLockEntry {
+  /** Where the skill came from: npm package name, owner/repo, local path, etc. */
+  source: string;
+  /** Branch or tag ref used for installation */
+  ref?: string;
+  /** The provider/source type (e.g., "github", "node_modules", "local") */
+  sourceType: string;
+  /**
+   * Path to the skill's SKILL.md within the source repo (e.g., "skills/pdf/SKILL.md").
+   * Required to re-install only this skill on update — without it, an update would
+   * refetch every skill in the source repo. Optional for backward compatibility with
+   * lock files written before this field existed, and omitted for non-repo sources
+   * (node_modules, local paths) where there is no subfolder to target.
+   */
+  skillPath?: string;
+  /**
+   * SHA-256 hash computed from all files in the skill folder.
+   * Unlike the global lock which uses GitHub tree SHA, the local lock
+   * computes the hash from actual file contents on disk.
+   */
+  computedHash: string;
+}
+
+/**
+ * The structure of the local (project-scoped) skill lock file.
+ * This file is meant to be checked into version control.
+ *
+ * Skills are sorted alphabetically by name when written to produce
+ * deterministic output and minimize merge conflicts.
+ */
+export interface LocalSkillLockFile {
+  /** Schema version for future migrations */
+  version: number;
+  /** Map of skill name to its lock entry (sorted alphabetically) */
+  skills: Record<string, LocalSkillLockEntry>;
+}
+
+/**
+ * Get the path to the local skill lock file for a project.
+ */
+export function getLocalLockPath(cwd?: string): string {
+  return join(cwd || process.cwd(), LOCAL_LOCK_FILE);
+}
+
+/**
+ * Read the local skill lock file.
+ * Returns an empty lock file structure if the file doesn't exist
+ * or is corrupted (e.g., merge conflict markers).
+ */
+export async function readLocalLock(cwd?: string): Promise<LocalSkillLockFile> {
+  const lockPath = getLocalLockPath(cwd);
+
+  try {
+    const content = await readFile(lockPath, 'utf-8');
+    const parsed = JSON.parse(content) as LocalSkillLockFile;
+
+    if (typeof parsed.version !== 'number' || !parsed.skills) {
+      return createEmptyLocalLock();
+    }
+
+    if (parsed.version < CURRENT_VERSION) {
+      return createEmptyLocalLock();
+    }
+
+    return parsed;
+  } catch {
+    return createEmptyLocalLock();
+  }
+}
+
+/**
+ * Write the local skill lock file.
+ * Skills are sorted alphabetically by name for deterministic output.
+ */
+export async function writeLocalLock(lock: LocalSkillLockFile, cwd?: string): Promise<void> {
+  const lockPath = getLocalLockPath(cwd);
+
+  // Sort skills alphabetically for deterministic output / clean diffs
+  const sortedSkills: Record<string, LocalSkillLockEntry> = {};
+  for (const key of Object.keys(lock.skills).sort()) {
+    sortedSkills[key] = lock.skills[key]!;
+  }
+
+  const sorted: LocalSkillLockFile = { version: lock.version, skills: sortedSkills };
+  const content = JSON.stringify(sorted, null, 2) + '\n';
+  await writeFile(lockPath, content, 'utf-8');
+}
+
+/**
+ * Compute a SHA-256 hash from all files in a skill directory.
+ * Reads all files recursively, sorts them by relative path for determinism,
+ * and produces a single hash from their concatenated contents.
+ */
+export async function computeSkillFolderHash(skillDir: string): Promise<string> {
+  const files: Array<{ relativePath: string; content: Buffer }> = [];
+  await collectFiles(skillDir, skillDir, files);
+
+  // Sort by relative path for deterministic hashing
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+
+  const hash = createHash('sha256');
+  for (const file of files) {
+    // Include the path in the hash so renames are detected
+    hash.update(file.relativePath);
+    hash.update(file.content);
+  }
+
+  return hash.digest('hex');
+}
+
+async function collectFiles(
+  baseDir: string,
+  currentDir: string,
+  results: Array<{ relativePath: string; content: Buffer }>
+): Promise<void> {
+  const entries = await readdir(currentDir, { withFileTypes: true });
+
+  await Promise.all(
+    entries.map(async (entry) => {
+      const fullPath = join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip .git and node_modules within skill dirs
+        if (entry.name === '.git' || entry.name === 'node_modules') return;
+        await collectFiles(baseDir, fullPath, results);
+      } else if (entry.isFile()) {
+        const content = await readFile(fullPath);
+        const relativePath = relative(baseDir, fullPath).split('\\').join('/');
+        results.push({ relativePath, content });
+      }
+    })
+  );
+}
+
+/**
+ * Add or update a skill entry in the local lock file.
+ */
+export async function addSkillToLocalLock(
+  skillName: string,
+  entry: LocalSkillLockEntry,
+  cwd?: string
+): Promise<void> {
+  const lock = await readLocalLock(cwd);
+  lock.skills[skillName] = entry;
+  await writeLocalLock(lock, cwd);
+}
+
+/**
+ * Remove a skill from the local lock file.
+ */
+export async function removeSkillFromLocalLock(skillName: string, cwd?: string): Promise<boolean> {
+  const lock = await readLocalLock(cwd);
+
+  if (!(skillName in lock.skills)) {
+    return false;
+  }
+
+  delete lock.skills[skillName];
+  await writeLocalLock(lock, cwd);
+  return true;
+}
+
+function createEmptyLocalLock(): LocalSkillLockFile {
+  return {
+    version: CURRENT_VERSION,
+    skills: {},
+  };
+}

package/vendor/skills/src/plugin-manifest.ts

@@ -0,0 +1,183 @@
+import { readFile } from 'fs/promises';
+import { join, dirname, resolve, normalize, sep } from 'path';
+
+/**
+ * Check if a path is contained within a base directory.
+ * Prevents path traversal attacks via `..` segments or absolute paths.
+ */
+function isContainedIn(targetPath: string, basePath: string): boolean {
+  const normalizedBase = normalize(resolve(basePath));
+  const normalizedTarget = normalize(resolve(targetPath));
+  return normalizedTarget.startsWith(normalizedBase + sep) || normalizedTarget === normalizedBase;
+}
+
+/**
+ * Validate that a relative path follows Claude Code conventions.
+ * Paths must start with './' per the plugin manifest spec.
+ */
+function isValidRelativePath(path: string): boolean {
+  return path.startsWith('./');
+}
+
+/**
+ * Plugin manifest types
+ */
+interface PluginManifestEntry {
+  source?: string | { source: string; repo?: string };
+  skills?: string[];
+  /** Optional name for grouping skills (e.g., "document-skills") */
+  name?: string;
+}
+
+interface MarketplaceManifest {
+  metadata?: { pluginRoot?: string };
+  plugins?: PluginManifestEntry[];
+}
+
+interface PluginManifest {
+  skills?: string[];
+  name?: string;
+}
+
+/**
+ * Extract skill search directories from plugin manifests.
+ * Handles both marketplace.json (multi-plugin) and plugin.json (single plugin).
+ * Only resolves local paths - remote sources are skipped.
+ *
+ * Returns directories that CONTAIN skills (to be searched for child SKILL.md files).
+ * For explicit skill paths in manifests, adds the parent directory so the
+ * existing discovery loop finds them.
+ */
+export async function getPluginSkillPaths(basePath: string): Promise<string[]> {
+  const searchDirs: string[] = [];
+
+  // Helper: add skill paths for a plugin at a given base path
+  // Only adds paths that are contained within basePath (security: prevents traversal)
+  const addPluginSkillPaths = (pluginBase: string, skills?: string[]) => {
+    // Validate pluginBase itself is contained
+    if (!isContainedIn(pluginBase, basePath)) return;
+
+    if (skills && skills.length > 0) {
+      // Plugin explicitly declares skill paths - add parent dirs so existing loop finds them
+      for (const skillPath of skills) {
+        // Validate skill path starts with './' (per Claude Code convention)
+        if (!isValidRelativePath(skillPath)) continue;
+
+        const skillDir = dirname(join(pluginBase, skillPath));
+        if (isContainedIn(skillDir, basePath)) {
+          searchDirs.push(skillDir);
+        }
+      }
+    }
+    // Always add conventional skills/ directory for discovery
+    // (deduplication happens via seenNames in discoverSkills)
+    searchDirs.push(join(pluginBase, 'skills'));
+  };
+
+  // Try marketplace.json (multi-plugin catalog)
+  try {
+    const content = await readFile(join(basePath, '.claude-plugin/marketplace.json'), 'utf-8');
+    const manifest: MarketplaceManifest = JSON.parse(content);
+    const pluginRoot = manifest.metadata?.pluginRoot;
+
+    // Validate pluginRoot starts with './' if provided (per Claude Code convention)
+    const validPluginRoot = pluginRoot === undefined || isValidRelativePath(pluginRoot);
+
+    if (validPluginRoot) {
+      for (const plugin of manifest.plugins ?? []) {
+        // Skip remote sources (object with source/repo) - only handle local string paths
+        if (typeof plugin.source !== 'string' && plugin.source !== undefined) continue;
+
+        // Validate source starts with './' if provided (per Claude Code convention)
+        if (plugin.source !== undefined && !isValidRelativePath(plugin.source)) continue;
+
+        const pluginBase = join(basePath, pluginRoot ?? '', plugin.source ?? '');
+        addPluginSkillPaths(pluginBase, plugin.skills);
+      }
+    }
+  } catch {
+    // File doesn't exist or invalid JSON
+  }
+
+  // Try plugin.json (single plugin at root)
+  try {
+    const content = await readFile(join(basePath, '.claude-plugin/plugin.json'), 'utf-8');
+    const manifest: PluginManifest = JSON.parse(content);
+    addPluginSkillPaths(basePath, manifest.skills);
+  } catch {
+    // File doesn't exist or invalid JSON
+  }
+
+  return searchDirs;
+}
+
+/**
+ * Get a map of skill directory paths to plugin names from plugin manifests.
+ * This allows grouping skills by their parent plugin.
+ *
+ * Returns Map<AbsolutePath, PluginName>
+ */
+export async function getPluginGroupings(basePath: string): Promise<Map<string, string>> {
+  const groupings = new Map<string, string>();
+
+  // Try marketplace.json (multi-plugin catalog)
+  try {
+    const content = await readFile(join(basePath, '.claude-plugin/marketplace.json'), 'utf-8');
+    const manifest: MarketplaceManifest = JSON.parse(content);
+    const pluginRoot = manifest.metadata?.pluginRoot;
+
+    // Validate pluginRoot starts with './' if provided (per Claude Code convention)
+    const validPluginRoot = pluginRoot === undefined || isValidRelativePath(pluginRoot);
+
+    if (validPluginRoot) {
+      for (const plugin of manifest.plugins ?? []) {
+        if (!plugin.name) continue;
+
+        // Skip remote sources (object with source/repo) - only handle local string paths
+        if (typeof plugin.source !== 'string' && plugin.source !== undefined) continue;
+
+        // Validate source starts with './' if provided (per Claude Code convention)
+        if (plugin.source !== undefined && !isValidRelativePath(plugin.source)) continue;
+
+        const pluginBase = join(basePath, pluginRoot ?? '', plugin.source ?? '');
+
+        // Validate pluginBase itself is contained
+        if (!isContainedIn(pluginBase, basePath)) continue;
+
+        if (plugin.skills && plugin.skills.length > 0) {
+          for (const skillPath of plugin.skills) {
+            // Validate skill path starts with './' (per Claude Code convention)
+            if (!isValidRelativePath(skillPath)) continue;
+
+            const skillDir = join(pluginBase, skillPath);
+            if (isContainedIn(skillDir, basePath)) {
+              // Store absolute path as key for reliable matching
+              groupings.set(resolve(skillDir), plugin.name);
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // File doesn't exist or invalid JSON
+  }
+
+  // Try plugin.json (single plugin at root)
+  try {
+    const content = await readFile(join(basePath, '.claude-plugin/plugin.json'), 'utf-8');
+    const manifest: PluginManifest = JSON.parse(content);
+    if (manifest.name && manifest.skills && manifest.skills.length > 0) {
+      for (const skillPath of manifest.skills) {
+        if (!isValidRelativePath(skillPath)) continue;
+        const skillDir = join(basePath, skillPath);
+        if (isContainedIn(skillDir, basePath)) {
+          groupings.set(resolve(skillDir), manifest.name);
+        }
+      }
+    }
+  } catch {
+    // File doesn't exist or invalid JSON
+  }
+
+  return groupings;
+}