@ghl-ai/aw 0.1.0

package/commands/pull.mjs

@@ -0,0 +1,252 @@
+// commands/pull.mjs — Pull content from registry
+
+import { mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import * as config from '../config.mjs';
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { sparseCheckout, cleanup, includeToSparsePaths } from '../git.mjs';
+import { walkRegistryTree } from '../registry.mjs';
+import { matchesAny } from '../glob.mjs';
+import { computePlan } from '../plan.mjs';
+import { applyActions } from '../apply.mjs';
+import { update as updateManifest } from '../manifest.mjs';
+import { resolveInput } from '../paths.mjs';
+import { linkWorkspace } from '../link.mjs';
+import { generateCommands, copyInstructions } from '../integrate.mjs';
+
+export function pullCommand(args) {
+  const input = args._positional?.[0] || '';
+  const cwd = process.cwd();
+  const workspaceDir = join(cwd, '.aw_registry');
+  const dryRun = args['--dry-run'] === true;
+  const verbose = args['-v'] === true || args['--verbose'] === true;
+  const renameNamespace = args._renameNamespace || null;
+
+  // No args = re-pull everything in sync config
+  if (!input) {
+    const cfg = config.load(workspaceDir);
+    if (!cfg) fmt.cancel('No .sync-config.json found. Run: aw init');
+    if (cfg.include.length === 0) {
+      fmt.cancel('Nothing to pull. Add paths first:\n\n  aw pull <path>');
+    }
+    fmt.logInfo(`Pulling ${chalk.cyan(cfg.include.length)} synced path${cfg.include.length > 1 ? 's' : ''}...`);
+    for (const p of cfg.include) {
+      pullCommand({ ...args, _positional: [p], _skipIntegrate: true });
+    }
+    // Post-pull IDE integration (once after all paths pulled)
+    linkWorkspace(cwd);
+    generateCommands(cwd);
+    copyInstructions(cwd, null, cfg.namespace);
+    return;
+  }
+
+  // Resolve input — accepts both local and registry paths
+  const resolved = resolveInput(input, workspaceDir);
+  let pattern = resolved.registryPath;
+
+  if (!pattern) {
+    fmt.cancel(`Could not resolve "${input}" to a registry path`);
+  }
+
+  // Ensure workspace exists
+  if (!existsSync(workspaceDir)) {
+    mkdirSync(workspaceDir, { recursive: true });
+  }
+
+  // Load config
+  const cfg = config.load(workspaceDir);
+  if (!cfg) {
+    fmt.cancel('No .sync-config.json found. Run: aw init');
+  }
+
+  // Fetch from registry
+  const s = fmt.spinner();
+  s.start('Fetching from registry...');
+
+  const sparsePaths = includeToSparsePaths([pattern]);
+  let tempDir;
+  try {
+    tempDir = sparseCheckout(cfg.repo, sparsePaths);
+  } catch (e) {
+    s.stop(chalk.red('Fetch failed'));
+    fmt.cancel(e.message);
+  }
+
+  try {
+    const registryDirs = [];
+    const regBase = join(tempDir, 'registry');
+
+    if (existsSync(regBase)) {
+      for (const name of listDirs(regBase)) {
+        registryDirs.push({ name, path: join(regBase, name) });
+      }
+    }
+
+    if (registryDirs.length === 0) {
+      s.stop(chalk.red('Not found'));
+      if (args._silent) return;
+      fmt.cancel(`Nothing found in registry for ${chalk.cyan(pattern)}`);
+    }
+
+    // Rename namespace if requested (e.g., [template] → dev)
+    if (renameNamespace) {
+      for (const rd of registryDirs) {
+        if (rd.name === pattern) {
+          rd.name = renameNamespace;
+        }
+      }
+      // Also remap pattern for include filter matching
+      pattern = renameNamespace;
+    }
+
+    // Validate pattern matches actual content
+    let hasMatch = false;
+    for (const { name, path } of registryDirs) {
+      const entries = walkRegistryTree(path, name);
+      if (entries.some(e => matchesAny(e.registryPath, [pattern]))) {
+        hasMatch = true;
+        break;
+      }
+    }
+
+    if (!hasMatch) {
+      s.stop(chalk.red('Not found'));
+      cleanup(tempDir);
+      if (args._silent) return;
+      fmt.cancel(`Nothing found in registry for ${chalk.cyan(pattern)}\n\n  Check the pattern exists in the registry repo.`);
+    }
+
+    const fetched = registryDirs.map(d => chalk.cyan(d.name)).join(', ');
+    s.stop(`Fetched ${fetched}`);
+
+    // Add to config if not already there
+    if (!cfg.include.includes(pattern)) {
+      config.addPattern(workspaceDir, pattern);
+      fmt.logSuccess(`Added ${chalk.cyan(pattern)} to config`);
+    }
+
+    // Compute plan
+    const { actions } = computePlan(registryDirs, workspaceDir, [pattern], {
+      skipOrphans: true,
+    });
+
+    if (dryRun) {
+      printDryRun(actions, verbose);
+      return;
+    }
+
+    // Apply
+    const s2 = fmt.spinner();
+    s2.start('Applying changes...');
+    const conflictCount = applyActions(actions);
+    updateManifest(workspaceDir, actions, cfg.namespace);
+    s2.stop('Changes applied');
+
+    // MCP registration (second-class — skip if not available)
+    if (cfg.namespace) {
+      registerMcp(cfg.namespace);
+    }
+
+    // Summary
+    printSummary(actions, verbose, conflictCount);
+
+    // Post-pull IDE integration (skip if called from batch re-pull)
+    if (!args._skipIntegrate) {
+      linkWorkspace(cwd);
+      generateCommands(cwd);
+      copyInstructions(cwd, null, cfg.namespace);
+    }
+
+  } finally {
+    cleanup(tempDir);
+  }
+}
+
+function listDirs(dir) {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+    .map(d => d.name);
+}
+
+function registerMcp(namespace) {
+  const mcpUrl = process.env.GHL_MCP_URL;
+  if (!mcpUrl) return;
+  try {
+    execSync(`TEAM_NAME=${namespace} node scripts/register-team-mcp.mjs`, { stdio: 'pipe' });
+    fmt.logSuccess('MCP registration complete');
+  } catch {
+    fmt.logWarn('MCP registration failed (pull still successful)');
+  }
+}
+
+function printDryRun(actions, verbose) {
+  const counts = { ADD: 0, UPDATE: 0, CONFLICT: 0, ORPHAN: 0, UNCHANGED: 0 };
+  const lines = [];
+
+  for (const type of ['agents', 'skills', 'commands', 'blueprints', 'evals']) {
+    const items = actions.filter(a => a.type === type);
+    if (items.length === 0) continue;
+
+    lines.push(chalk.bold(`${type}/`));
+    for (const act of items.sort((a, b) => a.targetFilename.localeCompare(b.targetFilename))) {
+      counts[act.action] = (counts[act.action] || 0) + 1;
+      if (!verbose && act.action === 'UNCHANGED') continue;
+      const ns = act.namespacePath ? chalk.dim(` [${act.namespacePath}]`) : '';
+      lines.push(`  ${fmt.actionLabel(act.action)} ${act.targetFilename}${ns}`);
+    }
+  }
+
+  if (lines.length > 0) {
+    fmt.note(lines.join('\n'), 'Dry Run');
+  }
+
+  fmt.logInfo(`Summary: ${fmt.countSummary(counts)}`);
+  fmt.logWarn('No files modified (--dry-run)');
+}
+
+function printSummary(actions, verbose, conflictCount) {
+  const conflicts = actions.filter(a => a.action === 'CONFLICT');
+
+  for (const type of ['agents', 'skills', 'commands', 'blueprints', 'evals']) {
+    const typeActions = actions.filter(a => a.type === type);
+    if (typeActions.length === 0) continue;
+
+    const counts = { ADD: 0, UPDATE: 0, CONFLICT: 0, ORPHAN: 0, UNCHANGED: 0 };
+    for (const a of typeActions) counts[a.action]++;
+
+    const parts = [];
+    if (counts.ADD > 0) parts.push(chalk.green(`${counts.ADD} new`));
+    if (counts.UPDATE > 0) parts.push(chalk.cyan(`${counts.UPDATE} updated`));
+    if (counts.CONFLICT > 0) parts.push(chalk.red(`${counts.CONFLICT} conflict`));
+    const detail = parts.length > 0 ? ` (${parts.join(', ')})` : '';
+
+    fmt.logSuccess(`${typeActions.length} ${type} pulled${detail}`);
+
+    if (verbose) {
+      for (const a of typeActions.filter(a => a.action !== 'UNCHANGED')) {
+        const ns = a.namespacePath ? chalk.dim(` [${a.namespacePath}]`) : '';
+        fmt.logMessage(`  ${fmt.actionLabel(a.action)} ${a.targetFilename}${ns}`);
+      }
+    }
+  }
+
+  if (conflicts.length > 0) {
+    const conflictLines = conflicts.map(c => {
+      return `${chalk.red('both modified:')}  ${c.type}/${c.targetFilename}`;
+    }).join('\n');
+
+    fmt.note(
+      conflictLines + '\n\n' +
+      chalk.dim('Fix conflicts, then re-run pull to verify.\n') +
+      chalk.dim('grep -r "<<<<<<< " .aw_registry/'),
+      chalk.red('Merge Conflicts')
+    );
+
+    fmt.outro(chalk.red('Pull completed with conflicts — resolve and re-run'));
+    process.exit(1);
+  }
+
+  fmt.outro('Pull complete');
+}

package/commands/push.mjs

@@ -0,0 +1,214 @@
+// commands/push.mjs — Push local agent/skill to registry via PR
+
+import { existsSync, statSync, mkdirSync, cpSync, mkdtempSync, readFileSync, appendFileSync } from 'node:fs';
+import { basename, dirname, resolve, join } from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { REGISTRY_REPO, REGISTRY_BASE_BRANCH } from '../constants.mjs';
+import { resolveInput } from '../paths.mjs';
+import { load as loadManifest } from '../manifest.mjs';
+import { hashFile } from '../registry.mjs';
+
+export function pushCommand(args) {
+  const input = args._positional?.[0];
+  const dryRun = args['--dry-run'] === true;
+  const repo = args['--repo'] || REGISTRY_REPO;
+  const cwd = process.cwd();
+  const workspaceDir = join(cwd, '.aw_registry');
+
+  fmt.intro('aw push');
+
+  // No args = find and list modified files for user to push
+  if (!input) {
+    const manifest = loadManifest(workspaceDir);
+    const modified = [];
+    for (const [key, entry] of Object.entries(manifest.files || {})) {
+      const filePath = join(workspaceDir, key);
+      if (!existsSync(filePath)) continue;
+      const currentHash = hashFile(filePath);
+      if (currentHash !== entry.sha256) {
+        modified.push(key);
+      }
+    }
+    if (modified.length === 0) {
+      fmt.cancel('Nothing to push — no modified files.\n\n  To push a specific file:\n  aw push <path>');
+    }
+    fmt.logInfo(`${chalk.bold(modified.length)} modified file${modified.length > 1 ? 's' : ''}:`);
+    for (const m of modified) {
+      fmt.logMessage(`  ${chalk.yellow(m)}`);
+    }
+    fmt.cancel(`\nSpecify which file to push:\n  aw push .aw_registry/${modified[0]}`);
+  }
+
+  // Resolve input — accept both registry path and local path
+  const resolved = resolveInput(input, workspaceDir);
+
+  if (!resolved.registryPath) {
+    const hint = input.startsWith('.claude/') || input.startsWith('.cursor/') || input.startsWith('.codex/')
+      ? `\n\n  Tip: Use the .aw_registry/ path instead:\n  aw push .aw_registry/${input.split('/').slice(1).join('/')}`
+      : '';
+    fmt.cancel(`Could not resolve "${input}" to a registry path.${hint}\n\n  Only files inside .aw_registry/ can be pushed.`);
+  }
+
+  // Find the local file to upload
+  let absPath = resolved.localAbsPath;
+  if (!absPath || !existsSync(absPath)) {
+    // Try resolving with .md extension for flat files
+    if (absPath && !absPath.endsWith('.md') && existsSync(absPath + '.md')) {
+      absPath = absPath + '.md';
+    } else {
+      fmt.cancel(`File not found: ${absPath || input}\n\n  Only files inside .aw_registry/ can be pushed.\n  Use ${chalk.dim('aw status')} to see modified files.`);
+    }
+  }
+
+  // Parse registry path to get type, namespace, slug
+  const regParts = resolved.registryPath.split('/');
+  let typeIdx = -1;
+  const validTypes = ['agents', 'skills', 'commands', 'blueprints', 'evals'];
+  for (let i = 0; i < regParts.length; i++) {
+    if (validTypes.includes(regParts[i])) { typeIdx = i; break; }
+  }
+
+  if (typeIdx === -1 || typeIdx + 1 >= regParts.length) {
+    fmt.cancel(`Could not determine type from path: ${resolved.registryPath}`);
+  }
+
+  const namespaceParts = regParts.slice(0, typeIdx);
+  const parentDir = regParts[typeIdx];
+  const slug = regParts[typeIdx + 1];
+  const namespacePath = namespaceParts.join('/');
+  const topNamespace = namespaceParts[0];
+
+  if (topNamespace === 'ghl') {
+    fmt.cancel("Cannot push to 'ghl' namespace — it is the shared platform layer");
+  }
+
+  const isDir = statSync(absPath).isDirectory();
+  const registryTarget = isDir
+    ? `registry/${namespacePath}/${parentDir}/${slug}`
+    : `registry/${namespacePath}/${parentDir}/${slug}.md`;
+
+  fmt.note(
+    [
+      `${chalk.dim('source:')}     ${absPath}`,
+      `${chalk.dim('type:')}       ${parentDir}`,
+      `${chalk.dim('namespace:')}  ${namespacePath}`,
+      `${chalk.dim('slug:')}       ${slug}`,
+      `${chalk.dim('target:')}     ${registryTarget}`,
+    ].join('\n'),
+    'Upload mapping'
+  );
+
+  if (dryRun) {
+    fmt.logWarn('No changes made (--dry-run)');
+    fmt.outro(chalk.dim('Remove --dry-run to upload'));
+    return;
+  }
+
+  const s = fmt.spinner();
+  s.start('Cloning registry...');
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'aw-upload-'));
+
+  try {
+    execSync(`gh repo clone ${repo} ${tempDir} -- --filter=blob:none --no-checkout`, { stdio: 'pipe' });
+    execSync(`git checkout ${REGISTRY_BASE_BRANCH}`, { cwd: tempDir, stdio: 'pipe' });
+    s.stop('Repository cloned');
+
+    const shortId = Date.now().toString(36).slice(-5);
+    const branch = `upload/${namespacePath.replace(/\//g, '-')}-${parentDir}-${slug}-${shortId}`;
+    execSync(`git checkout -b ${branch}`, { cwd: tempDir, stdio: 'pipe' });
+
+    const s2 = fmt.spinner();
+    s2.start('Preparing upload...');
+
+    // Copy to target
+    const targetFull = join(tempDir, registryTarget);
+    if (isDir) {
+      mkdirSync(targetFull, { recursive: true });
+      cpSync(absPath, targetFull, { recursive: true });
+    } else {
+      mkdirSync(dirname(targetFull), { recursive: true });
+      cpSync(absPath, targetFull);
+    }
+
+    // Check if this is a new namespace — auto-add CODEOWNERS entry
+    let newNamespace = false;
+    const nsDir = join(tempDir, 'registry', topNamespace);
+    const codeownersPath = join(tempDir, 'CODEOWNERS');
+    if (!existsSync(nsDir) || isNewNamespaceInCodeowners(codeownersPath, topNamespace)) {
+      newNamespace = true;
+      const ghUser = getGitHubUser();
+      if (ghUser && existsSync(codeownersPath)) {
+        const line = `/registry/${topNamespace}/ @${ghUser}\n`;
+        appendFileSync(codeownersPath, line);
+        execSync('git add CODEOWNERS', { cwd: tempDir, stdio: 'pipe' });
+      }
+    }
+
+    // Stage + commit + push + PR
+    execSync(`git add "${registryTarget}"`, { cwd: tempDir, stdio: 'pipe' });
+
+    const commitMsg = newNamespace
+      ? `registry: create namespace ${topNamespace} + add ${parentDir}/${slug}`
+      : `registry: add ${parentDir}/${slug} to ${namespacePath}`;
+    execSync(`git commit -m "${commitMsg}"`, { cwd: tempDir, stdio: 'pipe' });
+
+    s2.stop('Upload prepared');
+
+    const s3 = fmt.spinner();
+    s3.start('Pushing and creating PR...');
+
+    execSync(`git push -u origin ${branch}`, { cwd: tempDir, stdio: 'pipe' });
+
+    const bodyParts = [
+      '## Registry Upload',
+      '',
+      `- **Type:** ${parentDir}`,
+      `- **Slug:** ${slug}`,
+      `- **Namespace:** ${namespacePath}`,
+      `- **Path:** \`${registryTarget}\``,
+    ];
+    if (newNamespace) {
+      bodyParts.push('', '> **New namespace** — CODEOWNERS entry auto-added.');
+    }
+    bodyParts.push('', 'Uploaded via `aw push`');
+
+    const prTitle = `Add ${slug} (${parentDir}) to ${namespacePath}`;
+    const prBody = bodyParts.join('\n');
+    const prUrl = execFileSync('gh', [
+      'pr', 'create',
+      '--base', REGISTRY_BASE_BRANCH,
+      '--title', prTitle,
+      '--body', prBody,
+    ], { cwd: tempDir, encoding: 'utf8' }).trim();
+
+    s3.stop('PR created');
+
+    if (newNamespace) {
+      fmt.logInfo(`New namespace ${chalk.cyan(topNamespace)} — CODEOWNERS entry added`);
+    }
+    fmt.logSuccess(`PR: ${chalk.cyan(prUrl)}`);
+    fmt.outro('Upload complete');
+  } catch (e) {
+    fmt.cancel(`Upload failed: ${e.message}`);
+  } finally {
+    execSync(`rm -rf "${tempDir}"`, { stdio: 'pipe' });
+  }
+}
+
+function getGitHubUser() {
+  try {
+    return execSync('gh api user --jq .login', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function isNewNamespaceInCodeowners(codeownersPath, namespace) {
+  if (!existsSync(codeownersPath)) return true;
+  const content = readFileSync(codeownersPath, 'utf8');
+  return !content.includes(`/registry/${namespace}/`);
+}

package/commands/search.mjs

@@ -0,0 +1,183 @@
+// commands/search.mjs — Search local workspace + remote registry
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import * as config from '../config.mjs';
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_REPO } from '../constants.mjs';
+
+export function searchCommand(args) {
+  const query = (args._positional || []).join(' ').toLowerCase();
+
+  if (!query) {
+    fmt.cancel('Missing search query. Usage: aw search <query>');
+  }
+
+  fmt.intro('aw search');
+
+  const cwd = process.cwd();
+  const workspaceDir = join(cwd, '.aw_registry');
+
+  // ── Local search ──
+  const localResults = searchLocal(workspaceDir, query);
+
+  // ── Remote search ──
+  const s = fmt.spinner();
+  s.start('Searching registry...');
+  const cfg = config.load(workspaceDir);
+  const repo = cfg?.repo || REGISTRY_REPO;
+  const remoteResults = searchRemote(repo, query);
+  s.stop('Registry searched');
+
+  // Build set of local files for "already pulled" detection
+  const localPaths = new Set(localResults.map(r => r.registryPath.replace(/\.md$/, '')));
+
+  // ── Display local results ──
+  if (localResults.length > 0) {
+    const lines = localResults.slice(0, 20).map(r => {
+      const desc = r.description
+        ? chalk.dim(` — ${r.description.slice(0, 70)}${r.description.length > 70 ? '...' : ''}`)
+        : '';
+      return `${chalk.cyan(r.localPath)}${desc}`;
+    });
+    if (localResults.length > 20) {
+      lines.push(chalk.dim(`... and ${localResults.length - 20} more`));
+    }
+    fmt.note(lines.join('\n'), `Local (${localResults.length})`);
+  } else {
+    fmt.logInfo(chalk.dim('No local matches'));
+  }
+
+  // ── Display remote results ──
+  if (remoteResults.length > 0) {
+    // Mark items already pulled
+    const lines = remoteResults.slice(0, 20).map(r => {
+      const pulled = localPaths.has((r.path || '').replace(/\.md$/, ''));
+      const icon = pulled ? chalk.green('✓') : chalk.yellow('↓');
+      const desc = r.description
+        ? chalk.dim(` — ${r.description.slice(0, 60)}${r.description.length > 60 ? '...' : ''}`)
+        : '';
+      return `${icon} ${chalk.cyan(r.path)}${desc}`;
+    });
+    if (remoteResults.length > 20) {
+      lines.push(chalk.dim(`... and ${remoteResults.length - 20} more`));
+    }
+    fmt.note(
+      lines.join('\n') + '\n\n' + chalk.dim(`${chalk.green('✓')} = pulled  ${chalk.yellow('↓')} = available`),
+      `Registry (${remoteResults.length})`
+    );
+  } else if (remoteResults !== null) {
+    fmt.logInfo(chalk.dim('No registry matches'));
+  }
+
+  if (localResults.length === 0 && remoteResults.length === 0) {
+    fmt.outro(chalk.dim('Try a different query'));
+  } else {
+    fmt.outro(`${chalk.dim('aw pull <path>')} to download`);
+  }
+}
+
+/**
+ * Search local .aw_registry/ files by name, slug, and frontmatter.
+ */
+function searchLocal(workspaceDir, query) {
+  const results = [];
+  if (!existsSync(workspaceDir)) return results;
+
+  const queryTerms = query.split(' ');
+
+  // Walk namespace dirs
+  for (const nsEntry of readdirSync(workspaceDir, { withFileTypes: true })) {
+    if (!nsEntry.isDirectory() || nsEntry.name.startsWith('.')) continue;
+    const ns = nsEntry.name;
+
+    for (const type of ['agents', 'skills', 'commands', 'blueprints', 'evals']) {
+      const typeDir = join(workspaceDir, ns, type);
+      if (!existsSync(typeDir)) continue;
+
+      for (const entry of readdirSync(typeDir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.')) continue;
+
+        const fullPath = join(typeDir, entry.name);
+        const isDir = entry.isDirectory();
+        const slug = isDir ? entry.name : entry.name.replace(/\.md$/, '');
+
+        // Build searchable text
+        let haystack = `${ns} ${slug}`.replace(/-/g, ' ').toLowerCase();
+
+        // Read frontmatter for name/description
+        let description = '';
+        const mdPath = isDir ? join(fullPath, 'SKILL.md') : fullPath;
+        if (existsSync(mdPath)) {
+          const meta = extractFrontmatter(mdPath);
+          if (meta.name) haystack += ` ${meta.name.toLowerCase()}`;
+          if (meta.description) {
+            haystack += ` ${meta.description.toLowerCase()}`;
+            description = meta.description;
+          }
+        }
+
+        haystack += ` ${type}`;
+
+        if (queryTerms.every(q => haystack.includes(q))) {
+          const registryPath = `${ns}/${type}/${slug}`;
+          results.push({
+            localPath: `${ns}/${type}/${entry.name}`,
+            registryPath,
+            type,
+            slug,
+            description,
+          });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Search remote registry.json via GitHub API (no clone needed).
+ */
+function searchRemote(repo, query) {
+  try {
+    const raw = execSync(
+      `gh api "repos/${repo}/contents/registry/registry.json?ref=${REGISTRY_BASE_BRANCH}" --jq .content -H "Accept: application/vnd.github.v3+json"`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const content = Buffer.from(raw.trim(), 'base64').toString('utf8');
+    const registry = JSON.parse(content);
+
+    const queryTerms = query.split(' ');
+    return (registry.entries || []).filter(e => {
+      const haystack = `${e.name || ''} ${e.slug || ''} ${e.description || ''} ${e.type || ''} ${e.scope || ''} ${e.scopeName || ''} ${e.path || ''}`.toLowerCase();
+      return queryTerms.every(q => haystack.includes(q));
+    });
+  } catch {
+    // gh not available, not authenticated, or registry.json doesn't exist
+    return [];
+  }
+}
+
+/**
+ * Extract name and description from frontmatter.
+ */
+function extractFrontmatter(filePath) {
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    if (!content.startsWith('---')) return {};
+    const endIdx = content.indexOf('---', 3);
+    if (endIdx === -1) return {};
+    const fm = content.slice(3, endIdx);
+    const nameMatch = fm.match(/^name:\s*(.+)$/m);
+    const descMatch = fm.match(/^description:\s*(.+)$/m);
+    return {
+      name: nameMatch ? nameMatch[1].trim().replace(/^["']|["']$/g, '') : '',
+      description: descMatch ? descMatch[1].trim().replace(/^["']|["']$/g, '') : '',
+    };
+  } catch {
+    return {};
+  }
+}