@rbbtsn0w/adg 0.1.0-alpha.1

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

@@ -0,0 +1,329 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { createHash } from 'crypto';
+import { execSync } from 'child_process';
+import pc from 'picocolors';
+
+const AGENTS_DIR = '.agents';
+const LOCK_FILE = '.skill-lock.json';
+const CURRENT_VERSION = 3; // Bumped from 2 to 3 for folder hash support (GitHub tree SHA)
+
+/**
+ * Represents a single installed skill entry in the lock file.
+ */
+export interface SkillLockEntry {
+  /** Normalized source identifier (e.g., "owner/repo", "mintlify/bun.com") */
+  source: string;
+  /** The provider/source type (e.g., "github", "mintlify", "huggingface", "local") */
+  sourceType: string;
+  /** The original URL used to install the skill (for re-fetching updates) */
+  sourceUrl: string;
+  /** Branch or tag ref used for installation (for ref-aware updates) */
+  ref?: string;
+  /** Subpath within the source repo, if applicable */
+  skillPath?: string;
+  /**
+   * GitHub tree SHA for the entire skill folder.
+   * This hash changes when ANY file in the skill folder changes.
+   * Fetched via GitHub Trees API by the telemetry server.
+   */
+  skillFolderHash: string;
+  /** ISO timestamp when the skill was first installed */
+  installedAt: string;
+  /** ISO timestamp when the skill was last updated */
+  updatedAt: string;
+  /** Name of the plugin this skill belongs to (if any) */
+  pluginName?: string;
+}
+
+/**
+ * Tracks dismissed prompts so they're not shown again.
+ */
+export interface DismissedPrompts {
+  /** Dismissed the find-skills skill installation prompt */
+  findSkillsPrompt?: boolean;
+}
+
+/**
+ * The structure of the skill lock file.
+ */
+export interface SkillLockFile {
+  /** Schema version for future migrations */
+  version: number;
+  /** Map of skill name to its lock entry */
+  skills: Record<string, SkillLockEntry>;
+  /** Tracks dismissed prompts */
+  dismissed?: DismissedPrompts;
+  /** Last selected agents for installation */
+  lastSelectedAgents?: string[];
+}
+
+/**
+ * Get the path to the global skill lock file.
+ *
+ * ADG patch: anchor the lock under `.agents/` in BOTH modes so the skills and
+ * plugins domains always share one universal `~/.agents` (or
+ * `$XDG_STATE_HOME/.agents`) home — matching ADG's `globalPluginsDir()`.
+ * Upstream put the XDG variant at `$XDG_STATE_HOME/skills/`, which broke that
+ * shared root when XDG_STATE_HOME was set. See vendor/skills/PROVENANCE.md.
+ *
+ * Resolves to `$XDG_STATE_HOME/.agents/.skill-lock.json` if set,
+ * otherwise `~/.agents/.skill-lock.json`.
+ */
+export function getSkillLockPath(): string {
+  const root = process.env.XDG_STATE_HOME ?? homedir();
+  return join(root, AGENTS_DIR, LOCK_FILE);
+}
+
+/**
+ * Read the skill lock file.
+ * Returns an empty lock file structure if the file doesn't exist.
+ * Wipes the lock file if it's an old format (version < CURRENT_VERSION).
+ */
+export async function readSkillLock(): Promise<SkillLockFile> {
+  const lockPath = getSkillLockPath();
+
+  try {
+    const content = await readFile(lockPath, 'utf-8');
+    const parsed = JSON.parse(content) as SkillLockFile;
+
+    // Validate version - wipe if old format
+    if (typeof parsed.version !== 'number' || !parsed.skills) {
+      return createEmptyLockFile();
+    }
+
+    // If old version, wipe and start fresh (backwards incompatible change)
+    // v3 adds skillFolderHash - we want fresh installs to populate it
+    if (parsed.version < CURRENT_VERSION) {
+      return createEmptyLockFile();
+    }
+
+    return parsed;
+  } catch (error) {
+    // File doesn't exist or is invalid - return empty
+    return createEmptyLockFile();
+  }
+}
+
+/**
+ * Write the skill lock file.
+ * Creates the directory if it doesn't exist.
+ */
+export async function writeSkillLock(lock: SkillLockFile): Promise<void> {
+  const lockPath = getSkillLockPath();
+
+  // Ensure directory exists
+  await mkdir(dirname(lockPath), { recursive: true });
+
+  // Write with pretty formatting for human readability
+  const content = JSON.stringify(lock, null, 2);
+  await writeFile(lockPath, content, 'utf-8');
+}
+
+/**
+ * Compute SHA-256 hash of content.
+ */
+export function computeContentHash(content: string): string {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+let _ghWarningShown = false;
+
+/** For tests only. Resets the one-shot warning flag. */
+export function resetGhAuthWarning(): void {
+  _ghWarningShown = false;
+}
+
+/**
+ * Get GitHub token from user's environment.
+ * Tries in order:
+ * 1. GITHUB_TOKEN environment variable (silent)
+ * 2. GH_TOKEN environment variable (silent)
+ * 3. gh CLI auth token, if gh is installed. Prints a one-time warning to
+ *    stderr before invoking `gh auth token`, because that subprocess call
+ *    is flagged by some corporate endpoint security tooling (Defender, etc.)
+ *    as credential extraction. Callers should invoke this function lazily
+ *    (e.g. only after an unauthenticated request hits a rate limit) so the
+ *    fallback rarely runs in practice.
+ *
+ * @returns The token string or null if not available
+ */
+export function getGitHubToken(): string | null {
+  // Check environment variables first (silent: user has explicitly opted in)
+  if (process.env.GITHUB_TOKEN) {
+    return process.env.GITHUB_TOKEN;
+  }
+  if (process.env.GH_TOKEN) {
+    return process.env.GH_TOKEN;
+  }
+
+  // Last resort: spawn gh CLI. Warn the user once per process before doing so.
+  // ADG patch: message broadened — this resolver is now also used to reach
+  // private repos, not just to recover from a rate limit.
+  if (!_ghWarningShown) {
+    process.stderr.write(
+      `${pc.yellow('│')}  ${pc.yellow('GitHub authentication needed')} — using your ${pc.cyan('gh')} login to continue.\n` +
+        `${pc.yellow('│')}  ${pc.dim(`Tip: set ${pc.cyan('GITHUB_TOKEN')} to avoid this prompt, or use ${pc.cyan('--full-depth')} to clone instead.\n`)}`
+    );
+    _ghWarningShown = true;
+  }
+  try {
+    const token = execSync('gh auth token', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (token) {
+      return token;
+    }
+  } catch {
+    // gh not installed or not authenticated
+  }
+
+  return null;
+}
+
+/**
+ * Fetch the tree SHA (folder hash) for a skill folder using GitHub's Trees API.
+ * This makes ONE API call to get the entire repo tree, then extracts the SHA
+ * for the specific skill folder.
+ *
+ * @param ownerRepo - GitHub owner/repo (e.g., "vercel-labs/agent-skills")
+ * @param skillPath - Path to skill folder or SKILL.md (e.g., "skills/react-best-practices/SKILL.md")
+ * @param getToken - Optional lazy token resolver. Invoked only if the
+ *                   unauthenticated request hits a rate limit.
+ * @param ref - Optional branch/tag ref. Defaults to trying main then master.
+ * @returns The tree SHA for the skill folder, or null if not found
+ */
+export async function fetchSkillFolderHash(
+  ownerRepo: string,
+  skillPath: string,
+  getToken?: (() => string | null) | null,
+  ref?: string
+): Promise<string | null> {
+  const { fetchRepoTree, getSkillFolderHashFromTree } = await import('./blob.ts');
+  const tree = await fetchRepoTree(ownerRepo, ref, getToken ?? undefined);
+  if (!tree) return null;
+  return getSkillFolderHashFromTree(tree, skillPath);
+}
+
+/**
+ * Add or update a skill entry in the lock file.
+ */
+export async function addSkillToLock(
+  skillName: string,
+  entry: Omit<SkillLockEntry, 'installedAt' | 'updatedAt'>
+): Promise<void> {
+  const lock = await readSkillLock();
+  const now = new Date().toISOString();
+
+  const existingEntry = lock.skills[skillName];
+
+  lock.skills[skillName] = {
+    ...entry,
+    installedAt: existingEntry?.installedAt ?? now,
+    updatedAt: now,
+  };
+
+  await writeSkillLock(lock);
+}
+
+/**
+ * Remove a skill from the lock file.
+ */
+export async function removeSkillFromLock(skillName: string): Promise<boolean> {
+  const lock = await readSkillLock();
+
+  if (!(skillName in lock.skills)) {
+    return false;
+  }
+
+  delete lock.skills[skillName];
+  await writeSkillLock(lock);
+  return true;
+}
+
+/**
+ * Get a skill entry from the lock file.
+ */
+export async function getSkillFromLock(skillName: string): Promise<SkillLockEntry | null> {
+  const lock = await readSkillLock();
+  return lock.skills[skillName] ?? null;
+}
+
+/**
+ * Get all skills from the lock file.
+ */
+export async function getAllLockedSkills(): Promise<Record<string, SkillLockEntry>> {
+  const lock = await readSkillLock();
+  return lock.skills;
+}
+
+/**
+ * Get skills grouped by source for batch update operations.
+ */
+export async function getSkillsBySource(): Promise<
+  Map<string, { skills: string[]; entry: SkillLockEntry }>
+> {
+  const lock = await readSkillLock();
+  const bySource = new Map<string, { skills: string[]; entry: SkillLockEntry }>();
+
+  for (const [skillName, entry] of Object.entries(lock.skills)) {
+    const existing = bySource.get(entry.source);
+    if (existing) {
+      existing.skills.push(skillName);
+    } else {
+      bySource.set(entry.source, { skills: [skillName], entry });
+    }
+  }
+
+  return bySource;
+}
+
+/**
+ * Create an empty lock file structure.
+ */
+function createEmptyLockFile(): SkillLockFile {
+  return {
+    version: CURRENT_VERSION,
+    skills: {},
+    dismissed: {},
+  };
+}
+
+/**
+ * Check if a prompt has been dismissed.
+ */
+export async function isPromptDismissed(promptKey: keyof DismissedPrompts): Promise<boolean> {
+  const lock = await readSkillLock();
+  return lock.dismissed?.[promptKey] === true;
+}
+
+/**
+ * Mark a prompt as dismissed.
+ */
+export async function dismissPrompt(promptKey: keyof DismissedPrompts): Promise<void> {
+  const lock = await readSkillLock();
+  if (!lock.dismissed) {
+    lock.dismissed = {};
+  }
+  lock.dismissed[promptKey] = true;
+  await writeSkillLock(lock);
+}
+
+/**
+ * Get the last selected agents.
+ */
+export async function getLastSelectedAgents(): Promise<string[] | undefined> {
+  const lock = await readSkillLock();
+  return lock.lastSelectedAgents;
+}
+
+/**
+ * Save the selected agents to the lock file.
+ */
+export async function saveSelectedAgents(agents: string[]): Promise<void> {
+  const lock = await readSkillLock();
+  lock.lastSelectedAgents = agents;
+  await writeSkillLock(lock);
+}

package/vendor/skills/src/skills.ts

@@ -0,0 +1,316 @@
+import { readdir, readFile, stat } from 'fs/promises';
+import { join, basename, dirname, resolve, normalize, sep, relative } from 'path';
+import { parseFrontmatter } from './frontmatter.ts';
+import { sanitizeMetadata } from './sanitize.ts';
+import type { Skill } from './types.ts';
+import { getPluginSkillPaths, getPluginGroupings } from './plugin-manifest.ts';
+import { readLocalLock } from './local-lock.ts';
+
+const SKIP_DIRS = ['node_modules', '.git', 'dist', 'build', '__pycache__'];
+
+const AGENT_PROJECT_SKILL_DIRS = [
+  '.agents/skills',
+  '.claude/skills',
+  '.cline/skills',
+  '.codebuddy/skills',
+  '.codex/skills',
+  '.commandcode/skills',
+  '.continue/skills',
+  '.github/skills',
+  '.goose/skills',
+  '.iflow/skills',
+  '.junie/skills',
+  '.kilocode/skills',
+  '.kiro/skills',
+  '.mux/skills',
+  '.neovate/skills',
+  '.opencode/skills',
+  '.openhands/skills',
+  '.pi/skills',
+  '.qoder/skills',
+  '.roo/skills',
+  '.trae/skills',
+  '.windsurf/skills',
+  '.zencoder/skills',
+];
+
+function normalizeSkillName(name: string): string {
+  return name.toLowerCase().replace(/[\s_]+/g, '-');
+}
+
+function normalizeRelativePath(path: string): string {
+  return path.split(sep).join('/').replace(/\/+/g, '/');
+}
+
+/**
+ * Check if internal skills should be installed.
+ * Internal skills are hidden by default unless INSTALL_INTERNAL_SKILLS=1 is set.
+ */
+export function shouldInstallInternalSkills(): boolean {
+  const envValue = process.env.INSTALL_INTERNAL_SKILLS;
+  return envValue === '1' || envValue === 'true';
+}
+
+async function hasSkillMd(dir: string): Promise<boolean> {
+  try {
+    const skillPath = join(dir, 'SKILL.md');
+    const stats = await stat(skillPath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function parseSkillMd(
+  skillMdPath: string,
+  options?: { includeInternal?: boolean }
+): Promise<Skill | null> {
+  try {
+    const content = await readFile(skillMdPath, 'utf-8');
+    const { data } = parseFrontmatter(content);
+
+    if (!data.name || !data.description) {
+      return null;
+    }
+
+    // Ensure name and description are strings (YAML can parse numbers, booleans, etc.)
+    if (typeof data.name !== 'string' || typeof data.description !== 'string') {
+      return null;
+    }
+
+    // ADG patch: narrow `metadata` from the loosely-typed frontmatter (`unknown`)
+    // before reading it, so the file typechecks under the root tsconfig without
+    // changing behavior. See vendor/skills/PROVENANCE.md.
+    const metadata =
+      data.metadata && typeof data.metadata === 'object'
+        ? (data.metadata as Record<string, unknown>)
+        : undefined;
+
+    // Skip internal skills unless:
+    // 1. INSTALL_INTERNAL_SKILLS=1 is set, OR
+    // 2. includeInternal option is true (e.g., when user explicitly requests a skill)
+    const isInternal = metadata?.internal === true;
+    if (isInternal && !shouldInstallInternalSkills() && !options?.includeInternal) {
+      return null;
+    }
+
+    return {
+      name: sanitizeMetadata(data.name),
+      description: sanitizeMetadata(data.description),
+      path: dirname(skillMdPath),
+      rawContent: content,
+      metadata,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function findSkillDirs(dir: string, depth = 0, maxDepth = 5): Promise<string[]> {
+  if (depth > maxDepth) return [];
+
+  try {
+    const [hasSkill, entries] = await Promise.all([
+      hasSkillMd(dir),
+      readdir(dir, { withFileTypes: true }).catch(() => []),
+    ]);
+
+    const currentDir = hasSkill ? [dir] : [];
+
+    // Search subdirectories in parallel
+    const subDirResults = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory() && !SKIP_DIRS.includes(entry.name))
+        .map((entry) => findSkillDirs(join(dir, entry.name), depth + 1, maxDepth))
+    );
+
+    return [...currentDir, ...subDirResults.flat()];
+  } catch {
+    return [];
+  }
+}
+
+export interface DiscoverSkillsOptions {
+  /** Include internal skills (e.g., when user explicitly requests a skill by name) */
+  includeInternal?: boolean;
+  /** Search all subdirectories even when a root SKILL.md exists */
+  fullDepth?: boolean;
+}
+
+/**
+ * Validates that a resolved subpath stays within the base directory.
+ * Prevents path traversal attacks where subpath contains ".." segments
+ * that would escape the cloned repository directory.
+ */
+export function isSubpathSafe(basePath: string, subpath: string): boolean {
+  const normalizedBase = normalize(resolve(basePath));
+  const normalizedTarget = normalize(resolve(join(basePath, subpath)));
+
+  return normalizedTarget.startsWith(normalizedBase + sep) || normalizedTarget === normalizedBase;
+}
+
+export async function discoverSkills(
+  basePath: string,
+  subpath?: string,
+  options?: DiscoverSkillsOptions
+): Promise<Skill[]> {
+  const skills: Skill[] = [];
+  const seenNames = new Set<string>();
+  const localLock = await readLocalLock(basePath);
+  const lockedSkillNames = new Set(Object.keys(localLock.skills).map(normalizeSkillName));
+
+  // Validate subpath doesn't escape basePath (prevent path traversal)
+  if (subpath && !isSubpathSafe(basePath, subpath)) {
+    throw new Error(
+      `Invalid subpath: "${subpath}" resolves outside the repository directory. Subpath must not contain ".." segments that escape the base path.`
+    );
+  }
+
+  const searchPath = subpath ? join(basePath, subpath) : basePath;
+
+  // Get plugin groupings to map skills to their parent plugin
+  // We search for plugin definitions from the base search path
+  const pluginGroupings = await getPluginGroupings(searchPath);
+
+  // Helper to assign plugin name if available
+  const enhanceSkill = (skill: Skill) => {
+    const resolvedPath = resolve(skill.path);
+    if (pluginGroupings.has(resolvedPath)) {
+      skill.pluginName = pluginGroupings.get(resolvedPath);
+    }
+    return skill;
+  };
+
+  const isInstalledProjectSkill = (skill: Skill): boolean => {
+    if (lockedSkillNames.size === 0) return false;
+
+    const relativeDir = normalizeRelativePath(relative(basePath, skill.path));
+    const isAgentSkillPath = AGENT_PROJECT_SKILL_DIRS.some(
+      (dir) => relativeDir === dir || relativeDir.startsWith(`${dir}/`)
+    );
+    if (!isAgentSkillPath) return false;
+
+    const skillName = normalizeSkillName(skill.name);
+    const directoryName = normalizeSkillName(basename(skill.path));
+    return lockedSkillNames.has(skillName) || lockedSkillNames.has(directoryName);
+  };
+
+  // If pointing directly at a skill, add it (and return early unless fullDepth is set).
+  // If the root SKILL.md is an installed project skill tracked by skills-lock.json,
+  // ignore it and continue scanning in case the repo also contains source skills.
+  if (await hasSkillMd(searchPath)) {
+    let skill = await parseSkillMd(join(searchPath, 'SKILL.md'), options);
+    if (skill) {
+      if (!isInstalledProjectSkill(skill)) {
+        skill = enhanceSkill(skill);
+        skills.push(skill);
+        seenNames.add(skill.name);
+        // Only return early if fullDepth is not set
+        if (!options?.fullDepth) {
+          return skills;
+        }
+      }
+    }
+  }
+
+  // Search common skill locations first
+  const prioritySearchDirs = [
+    searchPath,
+    join(searchPath, 'skills'),
+    join(searchPath, 'skills/.curated'),
+    join(searchPath, 'skills/.experimental'),
+    join(searchPath, 'skills/.system'),
+    ...AGENT_PROJECT_SKILL_DIRS.map((dir) => join(searchPath, dir)),
+  ];
+
+  // Known skill container dirs are walked one extra level deep so layouts
+  // like `skills/<category>/<skill>/SKILL.md` are discovered without
+  // requiring `--full-depth`. The repo root (first entry) keeps its
+  // existing depth-1 behavior to avoid surfacing unrelated `SKILL.md`
+  // files (e.g. `examples/foo/SKILL.md`), and plugin-manifest-declared
+  // dirs (appended below) stay at depth-1 to honor the manifest spec.
+  const deepContainerDirs = new Set(prioritySearchDirs.slice(1));
+
+  // Add skill paths declared in plugin manifests
+  prioritySearchDirs.push(...(await getPluginSkillPaths(searchPath)));
+
+  const tryAddSkillAt = async (skillDir: string): Promise<boolean> => {
+    if (!(await hasSkillMd(skillDir))) return false;
+    let skill = await parseSkillMd(join(skillDir, 'SKILL.md'), options);
+    if (!skill || seenNames.has(skill.name)) return true;
+    if (isInstalledProjectSkill(skill)) return true;
+    skill = enhanceSkill(skill);
+    skills.push(skill);
+    seenNames.add(skill.name);
+    return true;
+  };
+
+  for (const dir of prioritySearchDirs) {
+    const walkDeep = deepContainerDirs.has(dir);
+
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        const childDir = join(dir, entry.name);
+        const foundAtChild = await tryAddSkillAt(childDir);
+
+        // Don't descend past a discovered SKILL.md (matches the existing
+        // flat-layout semantics) and don't go deeper inside non-container
+        // priority dirs.
+        if (foundAtChild || !walkDeep) continue;
+        if (SKIP_DIRS.includes(entry.name)) continue;
+
+        // Walk one extra level for catalog layouts.
+        try {
+          const grandEntries = await readdir(childDir, { withFileTypes: true });
+          for (const grand of grandEntries) {
+            if (!grand.isDirectory() || SKIP_DIRS.includes(grand.name)) continue;
+            await tryAddSkillAt(join(childDir, grand.name));
+          }
+        } catch {
+          // Child dir unreadable; skip silently.
+        }
+      }
+    } catch {
+      // Directory doesn't exist
+    }
+  }
+
+  // Fall back to recursive search if nothing found, or if fullDepth is set
+  if (skills.length === 0 || options?.fullDepth) {
+    const allSkillDirs = await findSkillDirs(searchPath);
+
+    for (const skillDir of allSkillDirs) {
+      let skill = await parseSkillMd(join(skillDir, 'SKILL.md'), options);
+      if (skill && !seenNames.has(skill.name) && !isInstalledProjectSkill(skill)) {
+        skill = enhanceSkill(skill);
+        skills.push(skill);
+        seenNames.add(skill.name);
+      }
+    }
+  }
+
+  return skills;
+}
+
+export function getSkillDisplayName(skill: Skill): string {
+  return skill.name || basename(skill.path);
+}
+
+/**
+ * Filter skills based on user input (case-insensitive direct matching).
+ * Multi-word skill names must be quoted on the command line.
+ */
+export function filterSkills(skills: Skill[], inputNames: string[]): Skill[] {
+  const normalizedInputs = inputNames.map((n) => n.toLowerCase());
+
+  return skills.filter((skill) => {
+    const name = skill.name.toLowerCase();
+    const displayName = getSkillDisplayName(skill).toLowerCase();
+
+    return normalizedInputs.some((input) => input === name || input === displayName);
+  });
+}