skillshop 2.2.0 → 4.0.0

package/src/personal-library.js

@@ -0,0 +1,591 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const libraryConfigFileName = 'skillshop-library.json';
+export const librarySelectionFileName = 'library-selection.json';
+export const libraryOriginsFileName = 'skillshop-library-sources.json';
+
+export class PersonalLibraryError extends Error {}
+
+function cliError(message) {
+  return new PersonalLibraryError(message);
+}
+
+function safeName(name) {
+  return typeof name === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+function validOrigin(origin) {
+  return origin && typeof origin.repository === 'string' &&
+    /^https:\/\/github\.com\/[A-Za-z0-9-]+\/skillshop-library\.git$/.test(origin.repository) &&
+    typeof origin.commit === 'string' && /^[a-f0-9]{40,64}$/.test(origin.commit);
+}
+
+function ensureNoSymlink(root, target, label) {
+  const absoluteRoot = path.resolve(root);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(absoluteRoot, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw cliError(`${label} escapes its library root`);
+  }
+  let current = absoluteRoot;
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) throw cliError(`${label} contains a symlink`);
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+}
+
+function validateTree(root, target = root) {
+  ensureNoSymlink(root, target, 'skill source');
+  let stat;
+  try {
+    stat = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw cliError(`skill source does not exist: ${target}`);
+    throw error;
+  }
+  if (stat.isSymbolicLink()) throw cliError(`skill source contains a symlink: ${target}`);
+  if (stat.isDirectory()) {
+    for (const entry of fs.readdirSync(target)) validateTree(root, path.join(target, entry));
+    return;
+  }
+  if (!stat.isFile()) throw cliError(`skill source contains a non-regular file: ${target}`);
+}
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && ((trimmed[0] === '"' && trimmed.at(-1) === '"') || (trimmed[0] === "'" && trimmed.at(-1) === "'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function skillManifest(skillDirectory, name) {
+  const manifestPath = path.join(skillDirectory, 'SKILL.md');
+  let stat;
+  try {
+    stat = fs.lstatSync(manifestPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw cliError(`${name}/SKILL.md is missing`);
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw cliError(`${name}/SKILL.md must be a regular file`);
+  const contents = fs.readFileSync(manifestPath, 'utf8');
+  const lines = contents.split(/\r?\n/);
+  if (lines[0] !== '---') throw cliError(`${name}/SKILL.md has no front matter`);
+  const end = lines.indexOf('---', 1);
+  if (end < 0) throw cliError(`${name}/SKILL.md has unterminated front matter`);
+  const frontMatter = lines.slice(1, end);
+  const field = (key) => frontMatter.find((line) => new RegExp(`^${key}:\\s*`).test(line))?.replace(new RegExp(`^${key}:\\s*`), '');
+  const declaredName = unquote(field('name') ?? '');
+  const description = field('description');
+  if (declaredName !== name) throw cliError(`${name}/SKILL.md name must match its directory`);
+  if (!description || !unquote(description)) throw cliError(`${name}/SKILL.md must declare a description`);
+  const metadataStart = frontMatter.findIndex((line) => /^metadata:\s*$/.test(line));
+  let author;
+  let version;
+  if (metadataStart >= 0) {
+    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]);
+    }
+  }
+  return { name, description: unquote(description), ...(author ? { author } : {}), ...(version ? { version } : {}), sourceDir: skillDirectory };
+}
+
+function parseConfig(root) {
+  const configPath = path.join(root, libraryConfigFileName);
+  let config;
+  try {
+    const stat = fs.lstatSync(configPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw cliError(`${configPath} must be a regular file`);
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    if (error instanceof SyntaxError) throw cliError(`cannot parse ${configPath}: ${error.message}`);
+    throw error;
+  }
+  if (config?.schemaVersion !== 1 || typeof config.skillsDirectory !== 'string' || !config.skillsDirectory.trim()) {
+    throw cliError(`${configPath} is not a supported Skillshop personal library config`);
+  }
+  if (path.isAbsolute(config.skillsDirectory)) throw cliError(`${configPath} skillsDirectory must be relative`);
+  const skillsDirectory = path.resolve(root, config.skillsDirectory);
+  const relative = path.relative(root, skillsDirectory);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw cliError(`${configPath} skillsDirectory escapes the library root`);
+  }
+  ensureNoSymlink(root, skillsDirectory, 'library skills directory');
+  let stat;
+  try {
+    stat = fs.lstatSync(skillsDirectory);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw cliError(`library skillsDirectory does not exist: ${skillsDirectory}`);
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw cliError(`library skillsDirectory is not a directory: ${skillsDirectory}`);
+  return { skillsDirectory, config };
+}
+
+function checkLibraryRoot(root) {
+  const absolute = path.resolve(root);
+  let stat;
+  try {
+    stat = fs.lstatSync(absolute);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw cliError(`personal library directory does not exist: ${absolute}`);
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw cliError(`library root is not a regular directory: ${absolute}`);
+  return absolute;
+}
+
+function sourceSkills(root, skillsDirectory) {
+  ensureNoSymlink(root, skillsDirectory, 'library skills directory');
+  return fs.readdirSync(skillsDirectory, { withFileTypes: true })
+    .map((entry) => {
+      if (entry.isSymbolicLink()) throw cliError(`library skills directory contains a symlink: ${path.join(skillsDirectory, entry.name)}`);
+      if (!entry.isDirectory() || !safeName(entry.name)) return null;
+      const skillDirectory = path.join(skillsDirectory, entry.name);
+      const manifestPath = path.join(skillDirectory, 'SKILL.md');
+      let manifestStat;
+      try {
+        manifestStat = fs.lstatSync(manifestPath);
+      } catch (error) {
+        if (error.code === 'ENOENT') return null;
+        throw error;
+      }
+      if (manifestStat.isSymbolicLink()) throw cliError(`${manifestPath} contains a symlink`);
+      if (!manifestStat.isFile()) throw cliError(`${manifestPath} must be a regular file`);
+      validateTree(root, skillDirectory);
+      return skillManifest(skillDirectory, entry.name);
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function inspectPersonalLibrary(directory) {
+  const root = path.resolve(directory);
+  let rootStat;
+  try {
+    rootStat = fs.lstatSync(root);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { root, exists: false, configured: false, skillsDirectory: path.join(root, 'skills'), skills: [] };
+    throw error;
+  }
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw cliError(`library root is not a regular directory: ${root}`);
+
+  const config = parseConfig(root);
+  if (config) return { root, exists: true, configured: true, ...config, skills: sourceSkills(root, config.skillsDirectory) };
+  if (fs.readdirSync(root).length === 0) {
+    return { root, exists: true, configured: false, skillsDirectory: path.join(root, 'skills'), skills: [] };
+  }
+
+  const direct = directSkillNames(root);
+  const nested = nestedSkillNames(root);
+  const nestedDirectory = path.join(root, 'skills');
+  let nestedExists = false;
+  try {
+    fs.lstatSync(nestedDirectory);
+    nestedExists = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (direct.length && (nested.length || nestedExists)) {
+    throw cliError('library has both direct skill directories and skills/; set skillsDirectory in skillshop-library.json');
+  }
+  const skillsDirectory = direct.length ? root : nestedDirectory;
+  return { root, exists: true, configured: false, skillsDirectory, skills: direct.length ? sourceSkills(root, root) : nested };
+}
+
+export function readPersonalLibraryOrigins(root) {
+  const filePath = path.join(root, libraryOriginsFileName);
+  ensureNoSymlink(root, filePath, 'library provenance');
+  let contents;
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw cliError(`${filePath} must be a regular provenance file`);
+    contents = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { schemaVersion: 1, skills: {} };
+    throw error;
+  }
+  let origins;
+  try {
+    origins = JSON.parse(contents);
+  } catch (error) {
+    throw cliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+  if (origins?.schemaVersion !== 1 || !origins.skills || typeof origins.skills !== 'object' || Array.isArray(origins.skills)) {
+    throw cliError(`${filePath} is not a supported provenance file`);
+  }
+  for (const [name, origin] of Object.entries(origins.skills)) {
+    if (!safeName(name) || !validOrigin(origin)) throw cliError(`${filePath} contains invalid provenance for ${name}`);
+  }
+  return origins;
+}
+
+export function validatePersonalSkillDirectory(root, directory, name) {
+  ensureNoSymlink(root, directory, `personal skill ${name}`);
+  let stat;
+  try {
+    stat = fs.lstatSync(directory);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw cliError(`personal skill ${name} does not exist: ${directory}`);
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw cliError(`personal skill source is not a regular directory: ${directory}`);
+  validateTree(root, directory);
+  return skillManifest(directory, name);
+}
+
+export function commitDownloadedPersonalSkill(root, skillsDirectory, name, stagedDirectory, origin, { force = false } = {}) {
+  if (!safeName(name)) throw cliError(`invalid skill name: ${name}`);
+  if (!validOrigin(origin)) throw cliError('download provenance is invalid');
+  const libraryRoot = checkLibraryRoot(root);
+  const config = parseConfig(libraryRoot);
+  if (!config || path.resolve(config.skillsDirectory) !== path.resolve(skillsDirectory)) {
+    throw cliError(`library skills directory changed during download: ${libraryRoot}`);
+  }
+  const target = path.resolve(skillsDirectory, name);
+  const relative = path.relative(libraryRoot, target);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw cliError(`download target escapes personal library: ${target}`);
+  }
+  if (path.resolve(skillsDirectory) === libraryRoot && [libraryConfigFileName, 'README.md', libraryOriginsFileName].includes(name)) {
+    throw cliError(`skill name collides with library metadata: ${name}`);
+  }
+  validatePersonalSkillDirectory(stagedDirectory, stagedDirectory, name);
+  const origins = readPersonalLibraryOrigins(libraryRoot);
+  const existingOrigin = origins.skills[name];
+  if (existingOrigin && existingOrigin.repository !== origin.repository && !force) {
+    throw cliError(`${name} already has a different GitHub source; use --force to replace it`);
+  }
+
+  let targetExists = false;
+  try {
+    const stat = fs.lstatSync(target);
+    targetExists = true;
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw cliError(`download target is not a regular skill directory: ${target}`);
+    validatePersonalSkillDirectory(libraryRoot, target, name);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (targetExists && !force) throw cliError(`${name} already exists in the personal library; use --force to replace it`);
+
+  const nextOrigins = { schemaVersion: 1, skills: { ...origins.skills, [name]: origin } };
+  const transactionDirectory = fs.mkdtempSync(path.join(libraryRoot, '.skillshop-download-'));
+  const temporaryTarget = path.join(transactionDirectory, 'skill');
+  const temporaryOrigins = path.join(transactionDirectory, 'sources.json');
+  const backupTarget = path.join(transactionDirectory, 'previous-skill');
+  const backupOrigins = path.join(transactionDirectory, 'previous-sources.json');
+  const originsPath = path.join(libraryRoot, libraryOriginsFileName);
+  let targetBackedUp = false;
+  let originsBackedUp = false;
+  let newTargetInstalled = false;
+  let newOriginsInstalled = false;
+  try {
+    copyTree(stagedDirectory, temporaryTarget);
+    fs.writeFileSync(temporaryOrigins, `${JSON.stringify(nextOrigins, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    ensureNoSymlink(libraryRoot, originsPath, 'library provenance');
+    try {
+      const stat = fs.lstatSync(originsPath);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw cliError(`${originsPath} must be a regular provenance file`);
+      fs.renameSync(originsPath, backupOrigins);
+      originsBackedUp = true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (targetExists) {
+      fs.renameSync(target, backupTarget);
+      targetBackedUp = true;
+    }
+    fs.renameSync(temporaryTarget, target);
+    newTargetInstalled = true;
+    fs.renameSync(temporaryOrigins, originsPath);
+    newOriginsInstalled = true;
+    try { fs.rmSync(backupTarget, { recursive: true, force: true }); } catch {}
+    try { fs.rmSync(backupOrigins, { force: true }); } catch {}
+    return { target, origin };
+  } catch (error) {
+    if (newOriginsInstalled) fs.rmSync(originsPath, { force: true });
+    if (originsBackedUp && fs.existsSync(backupOrigins)) fs.renameSync(backupOrigins, originsPath);
+    if (newTargetInstalled) fs.rmSync(target, { recursive: true, force: true });
+    if (targetBackedUp && fs.existsSync(backupTarget)) fs.renameSync(backupTarget, target);
+    throw error;
+  } finally {
+    try { fs.rmSync(transactionDirectory, { recursive: true, force: true }); } catch {}
+  }
+}
+
+export function importTrackedPersonalSkill(root, sourceDirectory, name) {
+  if (!safeName(name)) throw cliError(`invalid skill name: ${name}`);
+  const libraryRoot = checkLibraryRoot(root);
+  const config = parseConfig(libraryRoot);
+  if (!config) throw cliError(`personal library is not initialized: ${libraryRoot}`);
+  const skillsDirectory = config.skillsDirectory;
+  ensureNoSymlink(libraryRoot, skillsDirectory, 'library skills directory');
+  validatePersonalSkillDirectory(sourceDirectory, sourceDirectory, name);
+  const target = path.join(skillsDirectory, name);
+  if (path.resolve(skillsDirectory) === libraryRoot && [libraryConfigFileName, 'README.md', libraryOriginsFileName].includes(name)) {
+    throw cliError(`skill name collides with library metadata: ${name}`);
+  }
+  ensureNoSymlink(libraryRoot, target, `personal skill ${name}`);
+  try {
+    fs.lstatSync(target);
+    throw cliError(`personal library already contains ${name}; its source was not replaced`);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const transaction = fs.mkdtempSync(path.join(skillsDirectory, '.skillshop-adopt-'));
+  const staged = path.join(transaction, 'skill');
+  try {
+    copyTree(sourceDirectory, staged);
+    validatePersonalSkillDirectory(libraryRoot, staged, name);
+    fs.renameSync(staged, target);
+    return target;
+  } finally {
+    try { fs.rmSync(transaction, { recursive: true, force: true }); } catch {}
+  }
+}
+
+function atomicJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function copyTree(source, target) {
+  const stat = fs.lstatSync(source);
+  if (stat.isSymbolicLink()) throw cliError(`template contains a symlink: ${source}`);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true, mode: stat.mode & 0o777 });
+    for (const entry of fs.readdirSync(source)) copyTree(path.join(source, entry), path.join(target, entry));
+    fs.chmodSync(target, stat.mode & 0o777);
+    return;
+  }
+  if (!stat.isFile()) throw cliError(`template contains a non-regular file: ${source}`);
+  fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
+  fs.chmodSync(target, stat.mode & 0o777);
+}
+
+function copyLibraryTemplate(source, target, { includeExample = true } = {}) {
+  const stat = fs.lstatSync(source);
+  if (!stat.isDirectory()) throw cliError(`template root is not a directory: ${source}`);
+  fs.mkdirSync(target, { recursive: true, mode: stat.mode & 0o777 });
+  for (const entry of fs.readdirSync(source)) {
+    if (!includeExample && entry === 'skills') {
+      const sourceSkills = path.join(source, entry);
+      const skillsStat = fs.lstatSync(sourceSkills);
+      if (!skillsStat.isDirectory() || skillsStat.isSymbolicLink()) throw cliError(`template contains an unsafe skills directory: ${sourceSkills}`);
+      const targetSkills = path.join(target, entry);
+      fs.mkdirSync(targetSkills, { recursive: true, mode: skillsStat.mode & 0o777 });
+      for (const skillEntry of fs.readdirSync(sourceSkills)) {
+        if (skillEntry !== 'example') copyTree(path.join(sourceSkills, skillEntry), path.join(targetSkills, skillEntry));
+      }
+      fs.chmodSync(targetSkills, skillsStat.mode & 0o777);
+    } else {
+      copyTree(path.join(source, entry), path.join(target, entry));
+    }
+  }
+  fs.chmodSync(target, stat.mode & 0o777);
+}
+
+function directSkillNames(root) {
+  const names = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.isSymbolicLink() && fs.existsSync(path.join(root, entry.name, 'SKILL.md'))) {
+      throw cliError(`library contains a symlinked skill directory: ${path.join(root, entry.name)}`);
+    }
+    if (!entry.isDirectory() || entry.name === '.git' || entry.name === 'skills') continue;
+    if (fs.existsSync(path.join(root, entry.name, 'SKILL.md'))) {
+      skillManifest(path.join(root, entry.name), entry.name);
+      names.push(entry.name);
+    }
+  }
+  return names;
+}
+
+function nestedSkillNames(root) {
+  const directory = path.join(root, 'skills');
+  let stat;
+  try {
+    stat = fs.lstatSync(directory);
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw cliError(`${directory} must be a regular directory`);
+  return sourceSkills(root, directory).map(({ name }) => name);
+}
+
+function writeSelection(stateHome, root) {
+  atomicJson(path.join(stateHome, librarySelectionFileName), { selectionVersion: 1, root });
+}
+
+export function selectedLibraryRoot(stateHome) {
+  const filePath = path.join(stateHome, librarySelectionFileName);
+  let selectionStat;
+  try {
+    selectionStat = fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (selectionStat.isSymbolicLink() || !selectionStat.isFile()) {
+    throw cliError(`${filePath} must be a regular file`);
+  }
+  let selection;
+  try {
+    selection = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw cliError(`cannot parse ${filePath}: ${error.message}`);
+    throw error;
+  }
+  if (selection?.selectionVersion !== 1 || typeof selection.root !== 'string' || !path.isAbsolute(selection.root)) {
+    throw cliError(`${filePath} is not a supported personal library selection`);
+  }
+  const root = checkLibraryRoot(selection.root);
+  if (!parseConfig(root)) throw cliError(`personal library is missing ${libraryConfigFileName}: ${root}`);
+  return root;
+}
+
+export function initPersonalLibrary(directory, stateHome, templateRoot, { includeExample = true } = {}) {
+  const root = path.resolve(directory ?? path.join(os.homedir(), 'skillshop-library'));
+  const rootExists = fs.existsSync(root);
+  if (rootExists) checkLibraryRoot(root);
+
+  const templateConfigPath = path.join(templateRoot, libraryConfigFileName);
+  if (!fs.existsSync(templateConfigPath)) throw cliError(`bundled library template is missing: ${templateRoot}`);
+  const existing = rootExists ? parseConfig(root) : null;
+  let skillsDirectory;
+  if (existing) {
+    skillsDirectory = existing.skillsDirectory;
+    sourceSkills(root, skillsDirectory);
+  } else if (rootExists && fs.readdirSync(root).length === 0) {
+    copyLibraryTemplate(templateRoot, root, { includeExample });
+    skillsDirectory = path.join(root, parseConfig(root).config.skillsDirectory);
+    sourceSkills(root, skillsDirectory);
+  } else if (rootExists) {
+    const direct = directSkillNames(root);
+    const nested = nestedSkillNames(root);
+    const nestedDirectoryExists = fs.existsSync(path.join(root, 'skills'));
+    if (direct.length && (nested.length || nestedDirectoryExists)) {
+      throw cliError('library has both direct skill directories and skills/; set skillsDirectory in skillshop-library.json');
+    }
+    const relativeSkillsDirectory = direct.length ? '.' : 'skills';
+    skillsDirectory = path.resolve(root, relativeSkillsDirectory);
+    if (!fs.existsSync(skillsDirectory)) fs.mkdirSync(skillsDirectory, { recursive: true });
+    const configPath = path.join(root, libraryConfigFileName);
+    if (fs.existsSync(configPath)) throw cliError(`invalid existing config: ${configPath}`);
+
+    // Validate every existing source before adding config or selecting the root.
+    sourceSkills(root, skillsDirectory);
+    const config = { schemaVersion: 1, skillsDirectory: relativeSkillsDirectory };
+    atomicJson(configPath, config);
+    const readmeTarget = path.join(root, 'README.md');
+    if (!fs.existsSync(readmeTarget)) {
+      const templateReadme = path.join(templateRoot, 'README.md');
+      if (fs.existsSync(templateReadme)) copyTree(templateReadme, readmeTarget);
+    }
+  } else {
+    const parent = path.dirname(root);
+    fs.mkdirSync(parent, { recursive: true });
+    const temporary = `${root}.skillshop-init-${process.pid}`;
+    fs.rmSync(temporary, { recursive: true, force: true });
+    copyLibraryTemplate(templateRoot, temporary, { includeExample });
+    try {
+      fs.renameSync(temporary, root);
+    } catch (error) {
+      fs.rmSync(temporary, { recursive: true, force: true });
+      throw error;
+    }
+    skillsDirectory = path.join(root, parseConfig(root).config.skillsDirectory);
+    sourceSkills(root, skillsDirectory);
+  }
+
+  const validatedRoot = checkLibraryRoot(root);
+  parseConfig(validatedRoot);
+  writeSelection(stateHome, validatedRoot);
+  const skills = sourceSkills(validatedRoot, skillsDirectory ?? parseConfig(validatedRoot).skillsDirectory);
+  return { root: validatedRoot, skillsDirectory: skillsDirectory ?? parseConfig(validatedRoot).skillsDirectory, skills };
+}
+
+export function listPersonalSkills(stateHome) {
+  const root = selectedLibraryRoot(stateHome);
+  if (!root) throw cliError('no personal skill library selected; run "skillshop library init"');
+  const { skillsDirectory } = parseConfig(root);
+  return { root, skills: sourceSkills(root, skillsDirectory) };
+}
+
+export function resolvePersonalSkill(name, stateHome, explicitRoot = null) {
+  if (!safeName(name)) throw cliError(`invalid skill name: ${name}`);
+  const root = explicitRoot ? checkLibraryRoot(explicitRoot) : selectedLibraryRoot(stateHome);
+  if (!root) return null;
+  const config = parseConfig(root);
+  if (!config) throw cliError(`personal library is missing ${libraryConfigFileName}: ${root}`);
+  const { skillsDirectory } = config;
+  const sourceDir = path.join(skillsDirectory, name);
+  ensureNoSymlink(root, sourceDir, `personal skill ${name}`);
+  let stat;
+  try {
+    stat = fs.lstatSync(sourceDir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw cliError(`personal skill source is not a regular directory: ${sourceDir}`);
+  validateTree(root, sourceDir);
+  const metadata = skillManifest(sourceDir, name);
+  const origin = readPersonalLibraryOrigins(root).skills[name];
+  return {
+    ...metadata,
+    kind: 'personal',
+    source: {
+      kind: 'personal-library',
+      root,
+      skill: name,
+      skillDirectory: path.relative(root, sourceDir).split(path.sep).join('/'),
+      ...(origin ? { origin } : {})
+    }
+  };
+}
+
+export function resolveRecordedPersonalSkill(source) {
+  if (source?.kind !== 'personal-library' || typeof source.root !== 'string' || !path.isAbsolute(source.root) || !safeName(source.skill)) {
+    throw cliError('recorded personal skill source is invalid');
+  }
+  if (source.skillDirectory !== undefined && (typeof source.skillDirectory !== 'string' || !source.skillDirectory || source.skillDirectory.includes('\\') || path.posix.isAbsolute(source.skillDirectory))) {
+    throw cliError('recorded personal skill path is invalid');
+  }
+  if (!source.skillDirectory) return resolvePersonalSkill(source.skill, path.dirname(source.root), source.root);
+  const root = checkLibraryRoot(source.root);
+  const relative = path.posix.normalize(source.skillDirectory);
+  if (relative === '..' || relative.startsWith('../') || relative.startsWith('/')) throw cliError('recorded personal skill path escapes its library root');
+  const sourceDir = path.resolve(root, ...relative.split('/'));
+  ensureNoSymlink(root, sourceDir, `recorded personal skill ${source.skill}`);
+  validatePersonalSkillDirectory(root, sourceDir, source.skill);
+  const metadata = skillManifest(sourceDir, source.skill);
+  const origin = readPersonalLibraryOrigins(root).skills[source.skill];
+  return {
+    ...metadata,
+    kind: 'personal',
+    source: {
+      kind: 'personal-library',
+      root,
+      skill: source.skill,
+      skillDirectory: path.relative(root, sourceDir).split(path.sep).join('/'),
+      ...(origin ? { origin } : {})
+    }
+  };
+}

package/templates/skillshop-library/README.md

@@ -0,0 +1,38 @@
+# Skillshop personal library template
+
+This is a forkable, plain-folder library for user-authored skills. No `package.json`, build step, or npm metadata is required. Create a GitHub repository named `skillshop-library` under your account to share skills with `skillshop download @owner/skill`.
+
+The repository uses `skillshop-library.json` to name its source directory. The default is `skills/`:
+
+```json
+{
+  "schemaVersion": 1,
+  "skillsDirectory": "skills"
+}
+```
+
+Add one directory under `skills/` per skill. Each needs a `SKILL.md` with front matter containing `name` and `description`. Author/version metadata is optional. References, scripts, hidden files, binary assets, nested files, and executable modes stay beside the manifest and are copied as part of the complete directory.
+
+## Use the library
+
+```bash
+skillshop library init [directory]     # select or adopt a local source folder (no migration)
+skillshop library list
+skillshop download @alice/review       # add source only
+skillshop install @alice/review        # download if absent, then install locally
+skillshop install @alice/review --global
+skillshop install review               # install an existing selected source
+skillshop sync                         # update recorded local and global copies
+```
+
+`library init` defaults to the visible `~/skillshop-library` directory. It can also create or select an existing folder with this layout. Existing skill sources and valid config are retained. Add skills by copying their directories into the configured source folder.
+
+`download @owner/skill` reads `https://github.com/owner/skillshop-library.git` and adds the selected skill to the personal library without installing it. The `@` is CLI syntax and is stripped from the GitHub owner. Unprefixed `owner/skill` inputs are rejected. A same-name authored or different-origin source fails safely. Use `download @owner/skill --force` only when you intend to replace that library source.
+
+`install @owner/skill` downloads when the source is absent and then installs from the personal library. If a same-origin source already exists, local edits are reused without fetching. `install name` uses the selected local source. `--global` selects configured user skill directories.
+
+`sync` propagates full-tree changes from the library roots recorded with installed copies. It includes file additions, edits, deletions, binary/reference assets, and mode changes. It replaces content inside those Skillshop-owned directories, repairs divergent installed edits, and removes stale extras. An unchanged copy is left in place. It does not fetch GitHub. Switching the active library does not redirect older installs.
+
+`sync` is also the explicit migration step for tracked copies made by older bundled Skillshop installs; `library init` never migrates. A source already in the selected library wins and updates the tracked copies. If the source is missing, Skillshop imports it only when every surviving tracked project and global copy agrees in paths, file bytes, and modes. Conflicts, unknown source kinds, malformed ownership state, unmanaged directories, and package-import snapshots are preserved and reported. Missing recorded destinations are pruned, never recreated.
+
+The `skillsDirectory` field can name another safe relative directory inside this library. Set it to `.` to use skill folders directly in the library root.

package/templates/skillshop-library/skills/example/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: example
+description: A starting point for a personal Skillshop library skill.
+---
+
+# Example skill
+
+Describe what the skill does and how to use it.

package/templates/skillshop-library/skills/example/references/example.md

@@ -0,0 +1,3 @@
+# Example reference
+
+Keep source material and other assets inside the skill directory.

package/templates/skillshop-library/skills/example/scripts/run.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+printf '%s\n' 'Example skill script'

package/templates/skillshop-library/skillshop-library.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "skillsDirectory": "skills"
+}