skillshop 2.0.0 → 2.1.0

package/src/legacy-cli.js

@@ -0,0 +1,1234 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { AgentsInstructionsError, applyInstructions, applyLocalFragments, composeAgentsInstructions } from './agents-instructions.js';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skillsContentRoot = path.join(packageRoot, 'skills-content');
+const agentsContentRoot = path.join(packageRoot, 'agents-content');
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+const lockFileName = '.skillshop-lock';
+const legacyLockFileName = '.skillz-lock';
+const registryFileName = 'repositories.json';
+const configFileName = 'config.json';
+const globalSkillsFileName = 'global-skills.json';
+const excludeBlockStart = '# >>> skillshop managed dependencies >>>';
+const excludeBlockEnd = '# <<< skillshop managed dependencies <<<';
+const legacyExcludeBlockStart = '# >>> skillz managed dependencies >>>';
+const legacyExcludeBlockEnd = '# <<< skillz managed dependencies <<<';
+const globalAgentsTargets = [
+  path.join('.codex', 'AGENTS.md'),
+  path.join('.agents', 'AGENTS.md'),
+  path.join('.copilot', 'copilot-instructions.md')
+];
+
+function lockPathFor(root) {
+  const current = path.join(root, lockFileName);
+  const legacy = path.join(root, legacyLockFileName);
+  return fs.existsSync(current) || !fs.existsSync(legacy) ? current : legacy;
+}
+
+function hasLock(root) {
+  return fs.existsSync(path.join(root, lockFileName)) || fs.existsSync(path.join(root, legacyLockFileName));
+}
+const agentOptions = [
+  { id: 'copilot', label: 'Copilot', local: '.github/skills', global: '.copilot/skills' },
+  { id: 'claude', label: 'Claude', local: '.claude/skills', global: '.claude/skills' },
+  { id: 'codex', label: 'Codex', local: '.agents/skills', global: '.agents/skills' },
+  { id: 'opencode', label: 'OpenCode', local: '.agents/skills', global: '.agents/skills' },
+  { id: 'others', label: 'Others', local: '.agents/skills', global: '.agents/skills' }
+];
+
+class CliError extends Error {}
+
+function unquote(value) {
+  const trimmed = value.trim();
+  const match = trimmed.match(/^(['"])(.*)\1$/);
+  return match ? match[2] : trimmed;
+}
+
+function validateSkillName(name) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+    throw new CliError(`invalid skill name: ${name}`);
+  }
+}
+
+function skillMetadata(name) {
+  validateSkillName(name);
+  const sourceDir = path.join(skillsContentRoot, name);
+  const manifestPath = path.join(sourceDir, 'SKILL.md');
+
+  if (!fs.existsSync(manifestPath)) {
+    throw new CliError(`unknown skill: ${name}`);
+  }
+
+  const lines = fs.readFileSync(manifestPath, 'utf8').split(/\r?\n/);
+  if (lines[0] !== '---') {
+    throw new CliError(`${name}/SKILL.md has no front matter`);
+  }
+
+  const frontMatterEnd = lines.indexOf('---', 1);
+  const frontMatter = lines.slice(1, frontMatterEnd === -1 ? lines.length : frontMatterEnd);
+  const metadataStart = frontMatter.findIndex((line) => /^metadata:\s*$/.test(line));
+  let author;
+  let version;
+
+  if (metadataStart !== -1) {
+    for (const line of frontMatter.slice(metadataStart + 1)) {
+      if (line !== '' && !/^\s+/.test(line)) break;
+      const authorMatch = line.match(/^\s+author:\s*(.+)$/);
+      const versionMatch = line.match(/^\s+version:\s*(.+)$/);
+      if (authorMatch) author = unquote(authorMatch[1]);
+      if (versionMatch) version = unquote(versionMatch[1]);
+    }
+  }
+
+  if (!author || !version) {
+    throw new CliError(`${name}/SKILL.md must declare metadata.author and metadata.version`);
+  }
+
+  return { name, author, version, sourceDir };
+}
+
+function availableSkills() {
+  return fs.readdirSync(skillsContentRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => fs.existsSync(path.join(skillsContentRoot, name, 'SKILL.md')))
+    .sort();
+}
+
+function printHelp() {
+  console.log(`Usage:
+  skillshop init
+  skillshop config agents
+  skillshop agents [--global]
+  skillshop <name> [--version <version>] [--global]
+  skillshop install <name> [--version <version>] [--global]
+  skillshop uninstall <name> [--global]
+  skillshop upgrade
+  skillshop update [name]
+  skillshop update --push
+  skillshop migrate [root ...]
+  skillshop list
+
+Install, uninstall, and update skills from the local registry.
+
+Options:
+  -g, --global             Use configured system skill directories without a project lockfile
+      --push               Update every registered repository
+  -v, --version <version>  Require an exact skill version
+  -h, --help               Show this help
+
+Conveniences:
+  skillshop i <name>          Alias for install
+  skillshop add <name>        Alias for install
+  skillshop rm <name>         Alias for uninstall
+  skillshop <name>@<version>  Install an exact version
+
+Available skills:
+  ${availableSkills().join('\n  ')}`);
+}
+
+function skillshopHome() {
+  if (process.env.SKILLSHOP_HOME) return process.env.SKILLSHOP_HOME;
+  if (process.env.SKILLZ_HOME) return process.env.SKILLZ_HOME;
+  const current = path.join(os.homedir(), '.skillshop');
+  const legacy = path.join(os.homedir(), '.skillz');
+  return fs.existsSync(current) || !fs.existsSync(legacy) ? current : legacy;
+}
+
+function configPath() {
+  return path.join(skillshopHome(), configFileName);
+}
+
+function readConfig() {
+  const filePath = configPath();
+  if (!fs.existsSync(filePath)) return null;
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+
+  const knownAgents = new Set(agentOptions.map(({ id }) => id));
+  if (
+    config?.configVersion !== 1 ||
+    !Array.isArray(config.agents) ||
+    config.agents.length === 0 ||
+    config.agents.some((agent) => typeof agent !== 'string' || !knownAgents.has(agent))
+  ) {
+    throw new CliError(`${filePath} is not a supported skillshop config`);
+  }
+
+  return config;
+}
+
+function writeConfig(agents) {
+  const filePath = configPath();
+  const config = { configVersion: 1, agents: [...new Set(agents)] };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function configuredAgents(config) {
+  return config.agents.map((id) => agentOptions.find((option) => option.id === id));
+}
+
+function configuredSkillDirectories(config, scope, root = null) {
+  const base = scope === 'local' ? root : os.homedir();
+  return uniqueDestinations(configuredAgents(config).map((agent) => path.join(base, agent[scope])));
+}
+
+async function selectAgents() {
+  const terminal = createInterface({ input: process.stdin, output: process.stdout });
+  console.log('Which agents do you use? Select one or more:');
+  for (const [index, agent] of agentOptions.entries()) {
+    console.log(`  ${index + 1}. ${agent.label}`);
+  }
+  console.log('You can change this later with `skillshop config agents`.');
+
+  try {
+    while (true) {
+      if (process.stdin.readableEnded) throw new CliError('agent selection requires an answer');
+      let onEnd;
+      const inputEnded = new Promise((_, reject) => {
+        onEnd = () => reject(new CliError('agent selection requires an answer'));
+        process.stdin.once('end', onEnd);
+      });
+      let answer;
+      try {
+        answer = await Promise.race([
+          terminal.question('Enter numbers separated by commas: '),
+          inputEnded
+        ]);
+      } finally {
+        process.stdin.off('end', onEnd);
+      }
+      const indexes = answer.split(',').map((value) => Number(value.trim()) - 1);
+      if (
+        indexes.length > 0 &&
+        indexes.every((index) => Number.isInteger(index) && index >= 0 && index < agentOptions.length)
+      ) {
+        return [...new Set(indexes.map((index) => agentOptions[index].id))];
+      }
+      console.log(`Choose one or more numbers from 1 to ${agentOptions.length}.`);
+    }
+  } finally {
+    terminal.close();
+  }
+}
+
+async function configureAgents() {
+  const agents = await selectAgents();
+  writeConfig(agents);
+  const labels = configuredAgents({ agents }).map(({ label }) => label);
+  console.log(`Configured agents: ${labels.join(', ')}`);
+  console.log(`Wrote ${configPath()}`);
+}
+
+async function initialize() {
+  const config = readConfig();
+  if (!config) {
+    await configureAgents();
+    return;
+  }
+
+  console.log(`Agents already configured: ${configuredAgents(config).map(({ label }) => label).join(', ')}`);
+  console.log('Change this setting with `skillshop config agents`.');
+}
+
+function projectRoot(startDir, { required = true } = {}) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (fs.existsSync(path.join(current, '.git'))) return current;
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      if (!required) return null;
+      throw new CliError(`${path.resolve(startDir)} is not inside a Git repository`);
+    }
+    current = parent;
+  }
+}
+
+function directoriesToRoot(startDir, rootDir) {
+  const directories = [];
+  let current = path.resolve(startDir);
+
+  while (true) {
+    directories.push(current);
+    if (current === rootDir) return directories;
+
+    const parent = path.dirname(current);
+    if (parent === current) return [rootDir];
+    current = parent;
+  }
+}
+
+function findLockRoot(cwd, options) {
+  const root = projectRoot(cwd, options);
+  if (!root) return null;
+  return directoriesToRoot(cwd, root)
+    .find((directory) => hasLock(directory)) ?? null;
+}
+
+function resolveAgentDir(cwd) {
+  const root = projectRoot(cwd);
+  const directories = directoriesToRoot(cwd, root);
+
+  for (const agentDirName of ['.agents', '.github', '.codex']) {
+    for (const directory of directories) {
+      const candidate = path.join(directory, agentDirName);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+        return candidate;
+      }
+    }
+  }
+
+  return path.join(root, '.agents');
+}
+
+function emptyLock() {
+  return { lockfileVersion: 2, registry: 'local', skills: {} };
+}
+
+function readLock(root) {
+  const lockPath = lockPathFor(root);
+  if (!fs.existsSync(lockPath)) return emptyLock();
+
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${lockPath}: ${error.message}`);
+  }
+
+  if (![1, 2].includes(lock?.lockfileVersion) || lock.registry !== 'local' || !lock.skills || Array.isArray(lock.skills)) {
+    throw new CliError(`${lockPath} is not a supported skillshop lockfile`);
+  }
+
+  return lock;
+}
+
+function relativePath(root, target) {
+  return path.relative(root, target).split(path.sep).join('/');
+}
+
+function lockedTargets(root, name, entry) {
+  const paths = Array.isArray(entry?.paths) ? entry.paths : [entry?.path];
+  if (paths.length === 0 || paths.some((targetPath) => typeof targetPath !== 'string')) {
+    throw new CliError(`lock entry for ${name} has no install paths`);
+  }
+
+  return uniqueDestinations(paths.map((targetPath) => {
+    const target = path.resolve(root, targetPath);
+    const relative = path.relative(root, target);
+    if (relative === '' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new CliError(`lock entry for ${name} points outside the project`);
+    }
+    if (path.basename(target) !== name || path.basename(path.dirname(target)) !== 'skills') {
+      throw new CliError(`lock entry for ${name} is not a skills/${name} directory`);
+    }
+    assertLocalDestination(root, target, `lock entry for ${name}`);
+    return target;
+  }));
+}
+
+function inferredSkillDirectories(root, lock, cwd) {
+  const preferredName = lock.skills.skillshop ? 'skillshop' : lock.skills.skillz ? 'skillz' : Object.keys(lock.skills).sort()[0];
+  if (!preferredName) return [path.join(resolveAgentDir(cwd), 'skills')];
+  return lockedTargets(root, preferredName, lock.skills[preferredName]).map((target) => path.dirname(target));
+}
+
+function localSkillDirectories(root, lock, cwd) {
+  const config = readConfig();
+  const directories = config
+    ? configuredSkillDirectories(config, 'local', root)
+    : inferredSkillDirectories(root, lock, cwd);
+  for (const directory of directories) assertLocalDestination(root, directory, 'agent skill directory');
+  return directories;
+}
+
+function writeLock(root, lock) {
+  const skills = Object.fromEntries(
+    Object.entries(lock.skills)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, entry]) => [name, {
+        version: entry.version,
+        author: entry.author,
+        paths: lockedTargets(root, name, entry).map((target) => relativePath(root, target)).sort()
+      }])
+  );
+  const stableLock = { lockfileVersion: 2, registry: 'local', skills };
+  const lockPath = path.join(root, lockFileName);
+  const contents = `${JSON.stringify(stableLock, null, 2)}\n`;
+  if (fs.existsSync(lockPath) && fs.readFileSync(lockPath, 'utf8') === contents) return;
+  const temporaryPath = `${lockPath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, contents);
+  fs.renameSync(temporaryPath, lockPath);
+}
+
+function registryPath() {
+  return path.join(skillshopHome(), registryFileName);
+}
+
+function readRegistry() {
+  const filePath = registryPath();
+  if (!fs.existsSync(filePath)) return { registryVersion: 1, repositories: [] };
+
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+
+  if (
+    registry?.registryVersion !== 1 ||
+    !Array.isArray(registry.repositories) ||
+    registry.repositories.some((repository) => typeof repository !== 'string' || !path.isAbsolute(repository))
+  ) {
+    throw new CliError(`${filePath} is not a supported skillshop repository registry`);
+  }
+
+  return registry;
+}
+
+function canonicalPath(target) {
+  try {
+    return fs.realpathSync.native(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+function canonicalDestination(target) {
+  let existing = path.resolve(target);
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return path.resolve(target);
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  return path.join(canonicalPath(existing), ...missing);
+}
+
+function assertLocalDestination(root, target, label) {
+  const relative = path.relative(canonicalDestination(root), canonicalDestination(target));
+  if (relative === '' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside the project`);
+  }
+}
+
+function uniqueDestinations(targets) {
+  const seen = new Set();
+  return targets.filter((target) => {
+    const destination = canonicalDestination(target);
+    if (seen.has(destination)) return false;
+    seen.add(destination);
+    return true;
+  });
+}
+
+function staleTargets(previousTargets, targetDirs) {
+  const destinations = new Set(targetDirs.map(canonicalDestination));
+  return previousTargets.filter((target) => !destinations.has(canonicalDestination(target)));
+}
+
+function assertTargetsAvailable(name, targetDirs, previousTargets) {
+  const managedDestinations = new Set(previousTargets.map(canonicalDestination));
+  for (const targetDir of targetDirs) {
+    if (fs.existsSync(targetDir) && !managedDestinations.has(canonicalDestination(targetDir))) {
+      throw new CliError(`${targetDir} exists and is not managed as ${name} in ${lockFileName}`);
+    }
+  }
+}
+
+function writeRegistry(repositories) {
+  const filePath = registryPath();
+  const stableRegistry = {
+    registryVersion: 1,
+    repositories: [...new Set(repositories.map(canonicalPath))].sort()
+  };
+  const contents = `${JSON.stringify(stableRegistry, null, 2)}\n`;
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === contents) return;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, contents);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function registerRepository(root) {
+  const registry = readRegistry();
+  writeRegistry([...registry.repositories, root]);
+}
+
+function gitOutput(root, args) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (error) {
+    const detail = error.stderr?.trim();
+    throw new CliError(detail || `cannot inspect Git repository at ${root}`);
+  }
+}
+
+function managedGitPaths(root, lock) {
+  const gitRoot = canonicalPath(gitOutput(root, ['rev-parse', '--show-toplevel']));
+  const scope = relativePath(gitRoot, canonicalPath(root));
+  const scopedPath = (target) => relativePath(gitRoot, path.join(root, target));
+  const paths = [scopedPath(lockFileName)];
+  if (fs.existsSync(path.join(root, legacyLockFileName))) paths.push(scopedPath(legacyLockFileName));
+
+  for (const [name, entry] of Object.entries(lock.skills)) {
+    for (const target of lockedTargets(root, name, entry)) {
+      paths.push(scopedPath(relativePath(root, target)));
+    }
+  }
+
+  if (scope.startsWith('../') || path.isAbsolute(scope)) {
+    throw new CliError(`${root} is outside its Git repository`);
+  }
+
+  return { gitRoot, paths: [...new Set(paths)].sort() };
+}
+
+function gitExcludePattern(relative) {
+  const escaped = relative.replaceAll('\\', '\\\\').replace(/([ !#*?\[\]])/g, '\\$1');
+  return `/${escaped}${[lockFileName, legacyLockFileName].includes(path.posix.basename(relative)) ? '' : '/'}`;
+}
+
+function syncGitExclude(root, lock) {
+  const { paths } = managedGitPaths(root, lock);
+  const excludePathOutput = gitOutput(root, ['rev-parse', '--git-path', 'info/exclude']);
+  const excludePath = path.isAbsolute(excludePathOutput)
+    ? excludePathOutput
+    : path.resolve(root, excludePathOutput);
+  const existing = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, 'utf8') : '';
+  const lines = existing.replace(/\r\n/g, '\n').split('\n');
+  const retained = [];
+  let insideBlock = false;
+
+  for (const line of lines) {
+    if (line === excludeBlockStart || line === legacyExcludeBlockStart) {
+      insideBlock = true;
+      continue;
+    }
+    if (line === excludeBlockEnd || line === legacyExcludeBlockEnd) {
+      insideBlock = false;
+      continue;
+    }
+    if (!insideBlock) retained.push(line);
+  }
+
+  while (retained.at(-1) === '') retained.pop();
+  const block = [excludeBlockStart, ...paths.map(gitExcludePattern), excludeBlockEnd];
+  const contents = `${[...retained, ...(retained.length ? [''] : []), ...block].join('\n')}\n`;
+  fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+  if (contents !== existing) fs.writeFileSync(excludePath, contents);
+}
+
+function untrackManagedPaths(root, lock) {
+  const { gitRoot, paths } = managedGitPaths(root, lock);
+  try {
+    execFileSync(
+      'git',
+      ['rm', '-r', '--cached', '-f', '--ignore-unmatch', '--', ...paths],
+      { cwd: gitRoot, stdio: 'ignore' }
+    );
+  } catch {
+    throw new CliError(`cannot remove managed skill dependencies from the Git index at ${gitRoot}`);
+  }
+}
+
+function maintainRepository(root, lock, { register = true, untrack = false } = {}) {
+  if (untrack) untrackManagedPaths(root, lock);
+  syncGitExclude(root, lock);
+  if (register) registerRepository(root);
+}
+
+function manifestParts(contents, label) {
+  const newline = contents.includes('\r\n') ? '\r\n' : '\n';
+  if (!contents.startsWith(`---${newline}`)) return { lines: [], body: contents, newline };
+  const end = contents.indexOf(`${newline}---`, 3);
+  if (end === -1 || !['', '\n', '\r'].includes(contents[end + newline.length + 3] ?? '')) {
+    throw new CliError(`${label} has unterminated front matter`);
+  }
+  return {
+    lines: contents.slice(3 + newline.length, end).split(newline),
+    body: contents.slice(end + newline.length + 3),
+    newline
+  };
+}
+
+function repairInstalledManifest(name, entry, manifestPath) {
+  const contents = fs.readFileSync(manifestPath, 'utf8');
+  const { lines, body, newline } = manifestParts(contents, manifestPath);
+  const sourcePath = path.join(skillsContentRoot, name, 'SKILL.md');
+  const sourceLines = fs.existsSync(sourcePath)
+    ? manifestParts(fs.readFileSync(sourcePath, 'utf8'), sourcePath).lines
+    : [];
+  const sourceField = (key) => sourceLines.find((line) => line.startsWith(`${key}:`))?.slice(key.length + 1).trim();
+  const setField = (key, value) => {
+    const index = lines.findIndex((line) => line.startsWith(`${key}:`));
+    const replacement = `${key}: ${value}`;
+    if (index === -1) lines.push(replacement);
+    else if (unquote(lines[index].slice(key.length + 1)) !== unquote(value)) lines[index] = replacement;
+  };
+  setField('name', JSON.stringify(name));
+  const description = lines.find((line) => line.startsWith('description:'))?.slice(12).trim();
+  if (!description || ['""', "''", 'null', '~'].includes(description)) {
+    const fallback = sourceField('description');
+    if (!fallback) throw new CliError(`cannot restore description for ${manifestPath}`);
+    setField('description', fallback);
+  }
+
+  let metadataIndex = lines.findIndex((line) => /^metadata:/.test(line));
+  if (metadataIndex === -1) {
+    metadataIndex = lines.length;
+    lines.push('metadata:');
+  } else if (!/^metadata:\s*(?:#.*)?$/.test(lines[metadataIndex])) {
+    throw new CliError(`${manifestPath} must use a metadata block mapping`);
+  }
+  let metadataEnd = metadataIndex + 1;
+  while (metadataEnd < lines.length && /^(\s|$|#)/.test(lines[metadataEnd])) metadataEnd += 1;
+  const indent = lines.slice(metadataIndex + 1, metadataEnd)
+    .find((line) => /^\s+\S/.test(line))?.match(/^\s+/)[0] ?? '  ';
+  const metadata = {};
+  for (const key of ['author', 'version']) {
+    const fieldPrefix = `${indent}${key}:`;
+    const index = lines.findIndex((line, i) => i > metadataIndex && i < metadataEnd && line.startsWith(fieldPrefix));
+    const installed = index === -1 ? null : unquote(lines[index].slice(fieldPrefix.length));
+    const source = sourceLines.find((line) => new RegExp(`^\\s+${key}:`).test(line));
+    const value = typeof entry[key] === 'string' && entry[key].trim()
+      ? entry[key]
+      : installed && !['null', '~'].includes(installed) ? installed
+        : source ? unquote(source.slice(source.indexOf(':') + 1)) : null;
+    if (!value) throw new CliError(`cannot restore metadata.${key} for ${manifestPath}`);
+    metadata[key] = value;
+    const replacement = `${fieldPrefix} ${JSON.stringify(value)}`;
+    if (index === -1) {
+      lines.splice(metadataEnd, 0, replacement);
+      metadataEnd += 1;
+    } else if (installed !== value) lines[index] = replacement;
+  }
+  const separator = body && !body.startsWith(newline) ? newline + newline : '';
+  return { contents: `---${newline}${lines.join(newline)}${newline}---${separator}${body}`, metadata };
+}
+
+function readGlobalSkills() {
+  const filePath = path.join(skillshopHome(), globalSkillsFileName);
+  if (!fs.existsSync(filePath)) return emptyLock();
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+  if (lock?.lockfileVersion !== 2 || lock.registry !== 'local' || !lock.skills || Array.isArray(lock.skills)) {
+    throw new CliError(`${filePath} is not a supported skillshop global manifest`);
+  }
+  return lock;
+}
+
+function globalTargets(name, entry) {
+  validateSkillName(name);
+  if (!Array.isArray(entry?.paths) || !entry.paths.length) {
+    throw new CliError(`global entry for ${name} has no install paths`);
+  }
+  return uniqueDestinations(entry.paths.map((target) => {
+    if (typeof target !== 'string' || !path.isAbsolute(target) ||
+        path.basename(target) !== name || path.basename(path.dirname(target)) !== 'skills') {
+      throw new CliError(`global entry for ${name} is not an absolute skills/${name} directory`);
+    }
+    assertLocalDestination(os.homedir(), target, `global entry for ${name}`);
+    return target;
+  }));
+}
+
+function writeGlobalSkills(lock) {
+  const skills = Object.fromEntries(Object.entries(lock.skills).sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, entry]) => {
+      const paths = globalTargets(name, entry).sort();
+      return [name, { paths, copies: Object.fromEntries(paths.map((target) => [target, entry.copies?.[target] ?? {}])) }];
+    }));
+  const filePath = path.join(skillshopHome(), globalSkillsFileName);
+  const contents = `${JSON.stringify({ ...emptyLock(), skills }, null, 2)}\n`;
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === contents) return;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, contents);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function repairTrackedSkills(root, lock) {
+  const repairs = [];
+  for (const [name, entry] of Object.entries(lock.skills)) {
+    validateSkillName(name);
+    const targets = (root ? lockedTargets(root, name, entry) : globalTargets(name, entry))
+      .filter((target) => fs.existsSync(path.join(target, 'SKILL.md')));
+    if (!targets.length) {
+      delete lock.skills[name];
+      continue;
+    }
+    for (const target of targets) {
+      const manifestPath = path.join(target, 'SKILL.md');
+      assertLocalDestination(root ?? os.homedir(), manifestPath, `manifest for ${name}`);
+      const installation = root ? entry : entry.copies?.[target] ?? {};
+      const repair = repairInstalledManifest(name, installation, manifestPath);
+      if (root) Object.assign(entry, repair.metadata);
+      else {
+        entry.copies ??= {};
+        entry.copies[target] = repair.metadata;
+      }
+      repairs.push({ manifestPath, contents: repair.contents });
+    }
+    entry.paths = targets.map((target) => root ? relativePath(root, target) : target);
+  }
+  for (const { manifestPath, contents } of repairs) {
+    if (fs.readFileSync(manifestPath, 'utf8') !== contents) fs.writeFileSync(manifestPath, contents);
+  }
+}
+
+function reconcileRepository(root, { register = true } = {}) {
+  const lock = readLock(root);
+  repairTrackedSkills(root, lock);
+  writeLock(root, lock);
+  maintainRepository(root, lock, { register });
+}
+
+function reconcileCurrentRepository() {
+  if (fs.existsSync(path.join(skillshopHome(), globalSkillsFileName))) {
+    const globalSkills = readGlobalSkills();
+    repairTrackedSkills(null, globalSkills);
+    writeGlobalSkills(globalSkills);
+  }
+  const root = findLockRoot(process.cwd(), { required: false });
+  if (root) reconcileRepository(root, { register: false });
+  const registryExists = fs.existsSync(registryPath());
+  if (!root && !registryExists) return;
+  const registry = readRegistry();
+  const repositories = registry.repositories.filter((directory) => hasLock(directory));
+  if (root) repositories.push(root);
+  writeRegistry(repositories);
+}
+
+function replaceSkillDirectory(sourceDir, targetDir) {
+  const temporaryDir = `${targetDir}.skillshop-tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+  fs.rmSync(temporaryDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, temporaryDir, { recursive: true, force: true });
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  fs.renameSync(temporaryDir, targetDir);
+}
+
+function installAt(name, requestedVersion, targetDir) {
+  const metadata = skillMetadata(name);
+  if (requestedVersion && requestedVersion !== metadata.version) {
+    throw new CliError(
+      `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${metadata.version}`
+    );
+  }
+
+  const updating = fs.existsSync(targetDir);
+  replaceSkillDirectory(metadata.sourceDir, targetDir);
+  return { ...metadata, targetDir, updating };
+}
+
+function lockEntry(root, results) {
+  const [result] = results;
+  return {
+    version: result.version,
+    author: result.author,
+    paths: results.map(({ targetDir }) => relativePath(root, targetDir)).sort()
+  };
+}
+
+function installGlobal(name, requestedVersion) {
+  const config = readConfig();
+  const skillDirectories = config
+    ? configuredSkillDirectories(config, 'global')
+    : [path.join(os.homedir(), '.agents', 'skills')];
+
+  const globalSkills = readGlobalSkills();
+  for (const skillDirectory of skillDirectories) {
+    const targetDir = path.join(skillDirectory, name);
+    assertLocalDestination(os.homedir(), targetDir, `global installation for ${name}`);
+    const result = installAt(name, requestedVersion, targetDir);
+    const entry = globalSkills.skills[name] ?? { paths: [], copies: {} };
+    entry.paths = [...new Set([...entry.paths, targetDir])];
+    entry.copies[targetDir] = { author: result.author, version: result.version };
+    globalSkills.skills[name] = entry;
+    writeGlobalSkills(globalSkills);
+    console.log(`${result.updating ? 'Updated' : 'Installed'} ${name}@${result.version} at ${targetDir}`);
+  }
+}
+
+function nearestAgentsFile(cwd) {
+  let directory = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(directory, 'AGENTS.md');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function installAgents(cwd, globalInstall) {
+  const composed = composeAgentsInstructions(agentsContentRoot);
+  const targetPaths = [];
+  if (globalInstall) {
+    targetPaths.push(...globalAgentsTargets.map((target) => path.join(os.homedir(), target)));
+  } else {
+    const targetPath = nearestAgentsFile(cwd);
+    if (!targetPath) {
+      console.log(`No AGENTS.md found at or above ${cwd}`);
+      return;
+    }
+    targetPaths.push(targetPath);
+  }
+
+  // Plan every target before writing any of them, so a rejected file leaves all files intact.
+  const planned = targetPaths.map((targetPath) => {
+    const existing = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8') : '';
+    const bundled = applyInstructions(existing, composed.content, packageJson.version);
+    const local = applyLocalFragments(bundled.text, path.dirname(targetPath));
+    const action = existing === local.text ? 'unchanged' : bundled.action === 'installed' || local.action === 'installed' ? 'installed' : 'refreshed';
+    return { targetPath, action, text: local.text };
+  });
+
+  for (const { targetPath, action, text } of planned) {
+    if (action === 'unchanged') {
+      console.log(`Agents instructions already installed at ${targetPath}`);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, text);
+    console.log(
+      action === 'refreshed'
+        ? `Refreshed agents instructions at ${targetPath}`
+        : `Installed agents instructions at ${targetPath}`
+    );
+  }
+}
+
+function installLocal(name, requestedVersion, cwd) {
+  const root = findLockRoot(cwd) ?? projectRoot(cwd);
+  const lock = readLock(root);
+  const config = readConfig();
+  const skillDirectories = localSkillDirectories(root, lock, cwd);
+  const names = [...new Set([...Object.keys(lock.skills), name, 'skillshop'])].sort();
+  const installs = names.map((skillName) => {
+    const metadata = skillMetadata(skillName);
+    const targetDirs = config || !lock.skills[skillName]
+      ? skillDirectories.map((directory) => path.join(directory, skillName))
+      : lockedTargets(root, skillName, lock.skills[skillName]);
+    const previousTargets = lock.skills[skillName]
+      ? lockedTargets(root, skillName, lock.skills[skillName])
+      : [];
+    return { metadata, targetDirs, previousTargets };
+  });
+  const requestedMetadata = installs.find(({ metadata }) => metadata.name === name).metadata;
+  if (requestedVersion && requestedVersion !== requestedMetadata.version) {
+    throw new CliError(
+      `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${requestedMetadata.version}`
+    );
+  }
+  for (const { metadata, targetDirs, previousTargets } of installs) {
+    assertTargetsAvailable(metadata.name, targetDirs, previousTargets);
+  }
+
+  for (const { metadata, targetDirs, previousTargets } of installs) {
+    const version = metadata.name === name ? requestedVersion : null;
+    const results = targetDirs.map((targetDir) => installAt(metadata.name, version, targetDir));
+    for (const staleTarget of staleTargets(previousTargets, targetDirs)) {
+      fs.rmSync(staleTarget, { recursive: true, force: true });
+    }
+    lock.skills[metadata.name] = lockEntry(root, results);
+    for (const result of results) {
+      console.log(
+        `${result.updating ? 'Updated' : 'Installed'} ${result.name}@${result.version} at ${result.targetDir}`
+      );
+    }
+  }
+
+  writeLock(root, lock);
+  maintainRepository(root, lock);
+  console.log(`Wrote ${path.join(root, lockFileName)}`);
+}
+
+function uninstallGlobal(name) {
+  const config = readConfig();
+  const skillDirectories = config
+    ? configuredSkillDirectories(config, 'global')
+    : [path.join(os.homedir(), '.agents', 'skills')];
+  const targets = skillDirectories.map((directory) => path.join(directory, name));
+  const installedTargets = targets.filter((target) => fs.existsSync(target));
+  if (installedTargets.length === 0) {
+    throw new CliError(`${name} is not installed globally in the configured skill directories`);
+  }
+
+  for (const targetDir of installedTargets) {
+    fs.rmSync(targetDir, { recursive: true });
+    console.log(`Uninstalled ${name} from ${targetDir}`);
+  }
+  const globalSkills = readGlobalSkills();
+  if (globalSkills.skills[name]) {
+    const remaining = staleTargets(globalTargets(name, globalSkills.skills[name]), installedTargets);
+    if (remaining.length) globalSkills.skills[name].paths = remaining;
+    else delete globalSkills.skills[name];
+    writeGlobalSkills(globalSkills);
+  }
+}
+
+function uninstallLocal(name, cwd) {
+  const root = findLockRoot(cwd);
+  if (!root) throw new CliError(`no ${lockFileName} found in this project`);
+
+  const lock = readLock(root);
+  if (!lock.skills[name]) {
+    throw new CliError(`${name} is not listed in ${path.join(root, lockFileName)}`);
+  }
+
+  const targetDirs = lockedTargets(root, name, lock.skills[name]);
+  for (const targetDir of targetDirs) fs.rmSync(targetDir, { recursive: true, force: true });
+  delete lock.skills[name];
+  writeLock(root, lock);
+  maintainRepository(root, lock);
+
+  for (const targetDir of targetDirs) console.log(`Uninstalled ${name} from ${targetDir}`);
+  console.log(`Updated ${path.join(root, lockFileName)}`);
+}
+
+function updateLocal(requestedName, cwd, options = {}) {
+  const root = findLockRoot(cwd);
+  if (!root) throw new CliError(`no ${lockFileName} found in this project`);
+
+  const lock = readLock(root);
+  if (requestedName && !lock.skills[requestedName]) {
+    throw new CliError(`${requestedName} is not listed in ${path.join(root, lockFileName)}`);
+  }
+
+  const names = requestedName ? [requestedName] : Object.keys(lock.skills);
+  const config = readConfig();
+  const skillDirectories = localSkillDirectories(root, lock, cwd);
+
+  const updates = [...new Set(names)].sort().map((name) => {
+    const metadata = skillMetadata(name);
+    const targetDirs = config
+      ? skillDirectories.map((directory) => path.join(directory, name))
+      : lockedTargets(root, name, lock.skills[name]);
+    const previousTargets = lockedTargets(root, name, lock.skills[name]);
+    return { metadata, targetDirs, previousTargets };
+  });
+  for (const { metadata, targetDirs, previousTargets } of updates) {
+    assertTargetsAvailable(metadata.name, targetDirs, previousTargets);
+  }
+
+  for (const { metadata, targetDirs, previousTargets } of updates) {
+    const results = targetDirs.map((targetDir) => installAt(metadata.name, null, targetDir));
+    for (const staleTarget of staleTargets(previousTargets, targetDirs)) {
+      fs.rmSync(staleTarget, { recursive: true, force: true });
+    }
+    lock.skills[metadata.name] = lockEntry(root, results);
+    for (const result of results) {
+      console.log(`Updated ${result.name}@${result.version} at ${result.targetDir}`);
+    }
+  }
+
+  writeLock(root, lock);
+  maintainRepository(root, lock, options);
+  console.log(`Updated ${path.join(root, lockFileName)}`);
+}
+
+function updateAllRepositories() {
+  const registry = readRegistry();
+  const retained = [];
+  const failures = [];
+
+  for (const root of registry.repositories) {
+    if (!hasLock(root)) {
+      console.log(`Removed missing repository ${root}`);
+      continue;
+    }
+
+    retained.push(root);
+    console.log(`Updating ${root}`);
+    try {
+      reconcileRepository(root, { register: false });
+      updateLocal(null, root, { register: false });
+    } catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      failures.push(`${root}: ${error.message}`);
+      console.error(`skillshop: ${root}: ${error.message}`);
+    }
+  }
+
+  writeRegistry(retained);
+  if (failures.length) {
+    throw new CliError(`failed to update ${failures.length} registered ${failures.length === 1 ? 'repository' : 'repositories'}`);
+  }
+  console.log(`Updated ${retained.length} registered ${retained.length === 1 ? 'repository' : 'repositories'}`);
+}
+
+const migrationSkipDirectories = new Set([
+  '.git',
+  '.skillshop',
+  '.skillz',
+  '.Trash',
+  'Library',
+  'node_modules'
+]);
+
+function discoverLockRoots(startPath, roots) {
+  let stat;
+  try {
+    stat = fs.statSync(startPath);
+  } catch {
+    return;
+  }
+
+  if (stat.isFile()) {
+    if ([lockFileName, legacyLockFileName].includes(path.basename(startPath))) roots.add(canonicalPath(path.dirname(startPath)));
+    return;
+  }
+  if (!stat.isDirectory()) return;
+
+  if (hasLock(startPath)) roots.add(canonicalPath(startPath));
+
+  let entries;
+  try {
+    entries = fs.readdirSync(startPath, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || migrationSkipDirectories.has(entry.name)) continue;
+    discoverLockRoots(path.join(startPath, entry.name), roots);
+  }
+}
+
+function migrateRepositories(requestedRoots, cwd) {
+  const registry = readRegistry();
+  const roots = new Set(registry.repositories);
+  const searchRoots = requestedRoots.length
+    ? requestedRoots.map((root) => path.resolve(cwd, root))
+    : [os.homedir()];
+
+  for (const searchRoot of searchRoots) discoverLockRoots(searchRoot, roots);
+
+  const migrated = [];
+  const failures = [];
+  for (const root of [...roots].sort()) {
+    if (!hasLock(root)) continue;
+
+    try {
+      reconcileRepository(root, { register: false });
+      const lock = readLock(root);
+      maintainRepository(root, lock, { register: false, untrack: true });
+      migrated.push(root);
+      console.log(`Migrated ${root}`);
+    } catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      failures.push(`${root}: ${error.message}`);
+      console.error(`skillshop: ${root}: ${error.message}`);
+    }
+  }
+
+  writeRegistry(migrated);
+  if (failures.length) {
+    throw new CliError(`failed to migrate ${failures.length} ${failures.length === 1 ? 'repository' : 'repositories'}`);
+  }
+  console.log(`Migrated ${migrated.length} ${migrated.length === 1 ? 'repository' : 'repositories'}`);
+}
+
+function parseSkillSpec(spec, requestedVersion) {
+  const separator = spec.lastIndexOf('@');
+  if (separator <= 0) return { name: spec, version: requestedVersion };
+
+  const name = spec.slice(0, separator);
+  const inlineVersion = spec.slice(separator + 1);
+  if (!inlineVersion) throw new CliError(`missing version in ${spec}`);
+  if (requestedVersion && requestedVersion !== inlineVersion) {
+    throw new CliError(`conflicting versions requested for ${name}`);
+  }
+  return { name, version: inlineVersion };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  let globalInstall = false;
+  let pushUpdate = false;
+  const agentsTargets = [];
+  let requestedVersion = null;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--global' || argument === '-g') {
+      globalInstall = true;
+    } else if (argument === '--push') {
+      pushUpdate = true;
+    } else if (argument === '--codex' || argument === '--copilot') {
+      throw new CliError(`${argument} is no longer supported; use agents --global`);
+    } else if (argument === '--version' || argument === '-v') {
+      requestedVersion = argv[index + 1];
+      if (!requestedVersion) throw new CliError(`${argument} requires a version`);
+      index += 1;
+    } else if (argument.startsWith('--version=')) {
+      requestedVersion = argument.slice('--version='.length);
+      if (!requestedVersion) throw new CliError('--version requires a version');
+    } else if (argument.startsWith('-')) {
+      throw new CliError(`unknown option: ${argument}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+
+  return { positional, globalInstall, pushUpdate, requestedVersion, agentsTargets: [...new Set(agentsTargets)] };
+}
+
+function listSkills() {
+  for (const name of availableSkills()) {
+    const metadata = skillMetadata(name);
+    console.log(`${name}@${metadata.version} — ${metadata.author}`);
+  }
+}
+
+function upgrade() {
+  execFileSync('npm', ['install', '--global', 'skillshop'], { stdio: 'inherit' });
+}
+
+async function main(argv) {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    printHelp();
+    return;
+  }
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  const { positional, globalInstall, pushUpdate, requestedVersion, agentsTargets } = parseArgs(argv);
+  const command = positional[0];
+
+  if (command === 'init') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('init does not accept arguments or options');
+    }
+    await initialize();
+    return;
+  }
+
+  if (command === 'config') {
+    if (positional.length !== 2 || positional[1] !== 'agents' || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('config expects `agents` and does not accept options');
+    }
+    await configureAgents();
+    return;
+  }
+
+  if (command === 'list' || command === 'ls') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('list does not accept skill or install options');
+    }
+    listSkills();
+    return;
+  }
+
+  if (command === 'upgrade') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('upgrade does not accept arguments or options');
+    }
+    upgrade();
+    return;
+  }
+
+  if (command === 'update' || command === 'up') {
+    if (agentsTargets.length) throw new CliError('--codex and --copilot are only valid with agents');
+    if (globalInstall) throw new CliError('global updates are not tracked; reinstall the global skill by name');
+    if (requestedVersion) throw new CliError('update uses the current registry versions and does not accept --version');
+    if (positional.length > 2) throw new CliError('update accepts at most one locked skill name');
+    if (pushUpdate && positional.length !== 1) {
+      throw new CliError('push update does not accept a skill name');
+    }
+    if (pushUpdate) updateAllRepositories();
+    else updateLocal(positional[1] ?? null, process.cwd());
+    return;
+  }
+
+  if (command === 'migrate') {
+    if (requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('migrate does not accept install or update options');
+    }
+    migrateRepositories(positional.slice(1), process.cwd());
+    return;
+  }
+
+  if (command === 'agents') {
+    if (positional.length !== 1 || requestedVersion || pushUpdate) {
+      throw new CliError('agents does not accept skill or update options');
+    }
+    installAgents(process.cwd(), globalInstall);
+    return;
+  }
+
+  const uninstallAliases = new Set(['uninstall', 'remove', 'rm']);
+  if (uninstallAliases.has(command)) {
+    if (agentsTargets.length) throw new CliError('--codex and --copilot are only valid with agents');
+    if (requestedVersion) throw new CliError('uninstall does not accept --version');
+    if (pushUpdate) throw new CliError('--push is only valid with update');
+    if (positional.length !== 2) throw new CliError('uninstall expects exactly one skill name');
+
+    const name = positional[1];
+    validateSkillName(name);
+    if (globalInstall) uninstallGlobal(name);
+    else uninstallLocal(name, process.cwd());
+    return;
+  }
+
+  const installAliases = new Set(['install', 'i', 'add']);
+  if (agentsTargets.length) throw new CliError('--codex and --copilot are only valid with agents');
+  const spec = installAliases.has(command) ? positional[1] : command;
+  const expectedLength = installAliases.has(command) ? 2 : 1;
+  if (!spec || positional.length !== expectedLength) {
+    throw new CliError('expected exactly one skill name');
+  }
+  if (pushUpdate) throw new CliError('--push is only valid with update');
+
+  const { name, version } = parseSkillSpec(spec, requestedVersion);
+  validateSkillName(name);
+  if (globalInstall) installGlobal(name, version);
+  else installLocal(name, version, process.cwd());
+}
+
+export async function runLegacyCli(argv) {
+  try {
+    reconcileCurrentRepository();
+    try {
+      await main(argv);
+    } finally {
+      reconcileCurrentRepository();
+    }
+  } catch (error) {
+    if (!(error instanceof CliError) && !(error instanceof AgentsInstructionsError)) throw error;
+    console.error(`skillshop: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+export function reconcileLegacyState() {
+  reconcileCurrentRepository();
+}