skillshop 2.2.0 → 4.0.0

package/src/cli.js

@@ -11,22 +11,18 @@ import { parseLibrarySkillReference, skillName } from './specifier.js';
 
 function help() {
   console.log(`
-Library commands:
+Personal folder library commands:
 
-  skillshop library init
+  skillshop library init [directory]
   skillshop library list
-  skillshop export skill:<name> <directory>
-  skillshop export skill:<name> --from <package> [--skill skill:<source-name>]
-  skillshop unexport skill:<name>
-  skillshop validate
-  skillshop build
-  skillshop resolve <library>:<skill>
-  skillshop import <library>:<skill> [--global] [--to <directory>] [--force]
-  skillshop install-user [package-dir] [--if-global] [--to <skills-dir>]
+  skillshop download @<owner>/<skill> [--force]
+  skillshop install @<owner>/<skill> [--global]
+  skillshop install <name> [--global]
+  skillshop sync
 
-A library publishes skills by portable specifier, for example skill:review.
-Import uses the short <library>:<skill> form and copies to .agents/skills/<skill> by default.
---global copies to ~/.agents/skills/<skill> and replaces an existing directory.`);
+Create or select a source folder with skillshop library init. Download @owner/skill adds a GitHub skill to that folder without installing it.
+Install @owner/skill downloads when needed, then installs the complete source tree. Bare install names use the selected personal library. Sync updates recorded project and global copies from their saved source roots.
+No npm package manifest or author metadata is required. Existing npm package export/import APIs remain available for compatibility.`);
 }
 
 function flag(args, name) {
@@ -47,7 +43,7 @@ const libraryCommands = new Set(['export', 'unexport', 'validate', 'build', 'res
 async function main(argv, { libraryNamespace = false } = {}) {
   const [command, ...args] = argv;
   if (!libraryNamespace && command === 'library') {
-    if (args[0] === 'init' || args[0] === 'list') return main(args, { libraryNamespace: true });
+    if (args[0] === 'init' || args[0] === 'list') return runLegacyCli(argv);
     if (!args.length || args[0] === '--help' || args[0] === '-h') return help();
     throw new Error('Usage: skillshop library init | list');
   }
@@ -146,13 +142,14 @@ async function main(argv, { libraryNamespace = false } = {}) {
 
 const argv = process.argv.slice(2);
 const usingLibraryCommands = argv[0] === 'library' || libraryCommands.has(argv[0]);
+const personalLibraryCommand = argv[0] === 'library' && ['init', 'list'].includes(argv[1]);
 
 try {
-  if (usingLibraryCommands) reconcileLegacyState();
+  if (usingLibraryCommands && !personalLibraryCommand) reconcileLegacyState();
   try {
     await main(argv);
   } finally {
-    if (usingLibraryCommands) reconcileLegacyState();
+    if (usingLibraryCommands && !personalLibraryCommand) reconcileLegacyState();
   }
 } catch (error) {
   console.error(`skillshop: ${error.message}`);

package/src/github-library.js

@@ -0,0 +1,310 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  commitDownloadedPersonalSkill,
+  initPersonalLibrary,
+  inspectPersonalLibrary,
+  libraryConfigFileName,
+  libraryOriginsFileName,
+  librarySelectionFileName,
+  readPersonalLibraryOrigins,
+  selectedLibraryRoot,
+  validatePersonalSkillDirectory
+} from './personal-library.js';
+
+const githubOwnerPattern = /^[A-Za-z0-9-]+$/;
+const skillNamePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const reservedRootNames = new Set([libraryConfigFileName, 'README.md', libraryOriginsFileName]);
+
+export class GitHubLibraryError extends Error {}
+
+function fail(message) {
+  return new GitHubLibraryError(message);
+}
+
+export function parseGitHubSkillReference(reference) {
+  if (typeof reference !== 'string') throw fail('expected GitHub skill reference @<owner>/<skill>');
+  if (!reference.startsWith('@')) {
+    throw fail(`invalid GitHub skill reference ${reference}; prefix remote references with @ as @<owner>/<skill>`);
+  }
+  const parts = reference.slice(1).split('/');
+  if (parts.length !== 2 || !githubOwnerPattern.test(parts[0]) || !skillNamePattern.test(parts[1])) {
+    throw fail(`invalid GitHub skill reference ${reference}; expected @<owner>/<skill>`);
+  }
+  return { owner: parts[0], name: parts[1], repository: `https://github.com/${parts[0]}/skillshop-library.git` };
+}
+
+function gitEnvironment() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_ALLOW_PROTOCOL: 'https:file'
+  };
+}
+
+function git(args, { cwd, encoding = 'utf8', maxBuffer = 64 * 1024 * 1024 } = {}) {
+  const result = spawnSync('git', args, { cwd, encoding, env: gitEnvironment(), maxBuffer });
+  if (result.error) throw fail(`could not run Git: ${result.error.message}`);
+  if (result.status !== 0) {
+    const message = encoding === null ? result.stderr?.toString('utf8') : result.stderr;
+    throw fail(`Git ${args[0]} failed${message?.trim() ? `: ${message.trim()}` : ''}`);
+  }
+  return result.stdout;
+}
+
+function parseTreeEntries(buffer) {
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const entries = [];
+  for (const chunk of buffer.toString('binary').split('\0').filter(Boolean)) {
+    const separator = chunk.indexOf('\t');
+    if (separator < 0) throw fail('Git returned a malformed tree entry');
+    const [mode, type, object] = chunk.slice(0, separator).split(' ');
+    const rawPath = Buffer.from(chunk.slice(separator + 1), 'binary');
+    let entryPath;
+    try {
+      entryPath = decoder.decode(rawPath);
+    } catch {
+      throw fail('repository contains a non-UTF-8 path');
+    }
+    entries.push({ mode, type, object, path: entryPath });
+  }
+  return entries;
+}
+
+function literalPath(value) {
+  return `:(literal)${value}`;
+}
+
+function treeEntry(repositoryDir, commit, filePath) {
+  const result = git(['-C', repositoryDir, 'ls-tree', '-z', commit, '--', literalPath(filePath)], { encoding: null });
+  const entries = parseTreeEntries(result);
+  return entries.find((entry) => entry.path === filePath) ?? null;
+}
+
+function normalizeSkillsDirectory(value) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/')) {
+    throw fail('skillshop-library.json skillsDirectory must be a relative repository path');
+  }
+  const normalized = path.posix.normalize(value);
+  if (normalized === '..' || normalized.startsWith('../') || normalized.startsWith('/')) {
+    throw fail('skillshop-library.json skillsDirectory contains an unsafe path');
+  }
+  return normalized;
+}
+
+function readRemoteConfig(repositoryDir, commit) {
+  const entry = treeEntry(repositoryDir, commit, libraryConfigFileName);
+  if (!entry || entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) {
+    throw fail(`repository is missing a regular ${libraryConfigFileName}`);
+  }
+  let config;
+  try {
+    config = JSON.parse(git(['-C', repositoryDir, 'show', `${commit}:${libraryConfigFileName}`], { encoding: null }).toString('utf8'));
+  } catch (error) {
+    if (error instanceof GitHubLibraryError) throw error;
+    throw fail(`cannot parse ${libraryConfigFileName}: ${error.message}`);
+  }
+  if (config?.schemaVersion !== 1) throw fail(`${libraryConfigFileName} has an unsupported schemaVersion`);
+  const skillsDirectory = normalizeSkillsDirectory(config.skillsDirectory);
+  return { skillsDirectory };
+}
+
+function safeRelativeFilePath(skillPath, repoPath) {
+  if (!repoPath.startsWith(`${skillPath}/`)) throw fail(`repository path escapes requested skill: ${repoPath}`);
+  const relative = repoPath.slice(skillPath.length + 1);
+  const parts = relative.split('/');
+  if (!relative || relative.includes('\\') || parts.some((part) => !part || part === '.' || part === '..')) {
+    throw fail(`repository contains an unsafe skill path: ${repoPath}`);
+  }
+  return relative;
+}
+
+function stageSkill(repositoryDir, commit, skillPath, name, stagingRoot) {
+  const rootEntry = treeEntry(repositoryDir, commit, skillPath);
+  if (!rootEntry) throw fail(`repository has no skill named ${name}`);
+  if (rootEntry.mode !== '040000' || rootEntry.type !== 'tree') {
+    throw fail(`repository path for ${name} is not a skill directory`);
+  }
+  const entries = parseTreeEntries(git([
+    '-C', repositoryDir, 'ls-tree', '-r', '-z', '--full-tree', commit, '--', literalPath(skillPath)
+  ], { encoding: null }));
+  if (!entries.length) throw fail(`repository skill ${name} is empty`);
+
+  const skillDirectory = path.join(stagingRoot, 'skill');
+  fs.mkdirSync(skillDirectory, { recursive: true, mode: 0o755 });
+  const seen = new Set();
+  for (const entry of entries) {
+    const relative = safeRelativeFilePath(skillPath, entry.path);
+    if (seen.has(relative)) throw fail(`repository contains a duplicate skill path: ${relative}`);
+    seen.add(relative);
+    if (entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) {
+      throw fail(`repository skill contains a symlink, submodule, or non-regular entry: ${entry.path}`);
+    }
+    const target = path.join(skillDirectory, ...relative.split('/'));
+    const contained = path.relative(skillDirectory, target);
+    if (contained === '..' || contained.startsWith(`..${path.sep}`) || path.isAbsolute(contained)) {
+      throw fail(`repository path escapes requested skill: ${entry.path}`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o755 });
+    const contents = git(['-C', repositoryDir, 'cat-file', 'blob', entry.object], { encoding: null });
+    fs.writeFileSync(target, contents, { flag: 'wx', mode: entry.mode === '100755' ? 0o755 : 0o644 });
+    fs.chmodSync(target, entry.mode === '100755' ? 0o755 : 0o644);
+  }
+  validatePersonalSkillDirectory(skillDirectory, skillDirectory, name);
+  return skillDirectory;
+}
+
+function fetchSkill(reference, temporaryRoot) {
+  const bareRepository = path.join(temporaryRoot, 'repository.git');
+  fs.mkdirSync(bareRepository, { recursive: true });
+  git(['init', '--bare', '--quiet', bareRepository]);
+  const symbolicRefs = git(['ls-remote', '--symref', reference.repository, 'HEAD']);
+  const headReference = symbolicRefs.split(/\r?\n/).find((line) => line.startsWith('ref: ') && line.endsWith('\tHEAD'));
+  const headObject = symbolicRefs.split(/\r?\n/).find((line) => /^[a-f0-9]{40,64}\tHEAD$/.test(line));
+  if (!headReference || !headObject) throw fail(`could not discover the default branch for ${reference.repository}`);
+  const branchRef = headReference.slice('ref: '.length, -'\tHEAD'.length);
+  if (!branchRef.startsWith('refs/heads/')) throw fail('GitHub repository default is not a branch');
+  git(['-C', bareRepository, 'check-ref-format', branchRef]);
+  git(['-C', bareRepository, 'fetch', '--no-tags', '--no-recurse-submodules', '--depth=1', reference.repository, branchRef]);
+  const commit = git(['-C', bareRepository, 'rev-parse', '--verify', 'FETCH_HEAD^{commit}']).trim();
+  if (!/^[a-f0-9]{40,64}$/.test(commit)) throw fail('Git returned an invalid commit identifier');
+  const config = readRemoteConfig(bareRepository, commit);
+  const skillPath = config.skillsDirectory === '.' ? reference.name : `${config.skillsDirectory}/${reference.name}`;
+  if (config.skillsDirectory === '.' && reservedRootNames.has(reference.name)) {
+    throw fail(`skill name collides with repository metadata: ${reference.name}`);
+  }
+  const skillDirectory = stageSkill(bareRepository, commit, skillPath, reference.name, temporaryRoot);
+  return { skillDirectory, origin: { repository: reference.repository, commit } };
+}
+
+function snapshotFile(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw fail(`${filePath} must be a regular file`);
+    return { contents: fs.readFileSync(filePath), mode: stat.mode & 0o777 };
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function restoreFile(filePath, snapshot) {
+  if (!snapshot) {
+    fs.rmSync(filePath, { force: true });
+    return;
+  }
+  fs.writeFileSync(filePath, snapshot.contents, { mode: snapshot.mode });
+  fs.chmodSync(filePath, snapshot.mode);
+}
+
+function captureInitialization(root, stateHome) {
+  let rootExisted = true;
+  let rootEmpty = false;
+  try {
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw fail(`library root is not a regular directory: ${root}`);
+    rootEmpty = fs.readdirSync(root).length === 0;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    rootExisted = false;
+  }
+  const skillsBefore = path.join(root, 'skills');
+  let skillsExisted = false;
+  try {
+    fs.lstatSync(skillsBefore);
+    skillsExisted = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return {
+    rootExisted,
+    rootEmpty,
+    skillsExisted,
+    stateHomeExisted: fs.existsSync(stateHome),
+    config: snapshotFile(path.join(root, libraryConfigFileName)),
+    readme: snapshotFile(path.join(root, 'README.md')),
+    selection: snapshotFile(path.join(stateHome, librarySelectionFileName))
+  };
+}
+
+function rollbackInitialization(root, stateHome, snapshot) {
+  if (!snapshot.rootExisted) {
+    fs.rmSync(root, { recursive: true, force: true });
+  } else if (snapshot.rootEmpty) {
+    for (const entry of fs.readdirSync(root)) fs.rmSync(path.join(root, entry), { recursive: true, force: true });
+  } else {
+    restoreFile(path.join(root, libraryConfigFileName), snapshot.config);
+    restoreFile(path.join(root, 'README.md'), snapshot.readme);
+    if (!snapshot.skillsExisted) fs.rmSync(path.join(root, 'skills'), { recursive: true, force: true });
+  }
+  restoreFile(path.join(stateHome, librarySelectionFileName), snapshot.selection);
+  if (!snapshot.stateHomeExisted && fs.existsSync(stateHome) && fs.readdirSync(stateHome).length === 0) {
+    fs.rmdirSync(stateHome);
+  }
+}
+
+function targetInfo(layout, name) {
+  if (path.resolve(layout.skillsDirectory) === path.resolve(layout.root) && reservedRootNames.has(name)) {
+    throw fail(`skill name collides with library metadata: ${name}`);
+  }
+  const target = path.join(layout.skillsDirectory, name);
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw fail(`personal library target is not a regular skill directory: ${target}`);
+    validatePersonalSkillDirectory(layout.root, target, name);
+    return { target, exists: true };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { target, exists: false };
+    throw error;
+  }
+}
+
+export function downloadPersonalSkill(referenceValue, { stateHome, templateRoot, force = false } = {}) {
+  const reference = parseGitHubSkillReference(referenceValue);
+  const selected = selectedLibraryRoot(stateHome);
+  const root = selected ?? path.resolve(os.homedir(), 'skillshop-library');
+  const layout = inspectPersonalLibrary(root);
+  const origins = layout.exists ? readPersonalLibraryOrigins(root) : { schemaVersion: 1, skills: {} };
+  const existingOrigin = origins.skills[reference.name];
+  const target = targetInfo(layout, reference.name);
+  if (target.exists && !force) {
+    if (existingOrigin?.repository === reference.repository) {
+      if (!selected) initPersonalLibrary(root, stateHome, templateRoot);
+      return { root, name: reference.name, origin: existingOrigin, alreadyPresent: true };
+    }
+    if (existingOrigin) throw fail(`${reference.name} already has a different GitHub source; use --force to replace it`);
+    throw fail(`${reference.name} already exists as a personal skill; use --force to replace it`);
+  }
+  if (existingOrigin && existingOrigin.repository !== reference.repository && !force) {
+    throw fail(`${reference.name} already has a different GitHub source; use --force to replace it`);
+  }
+  const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skillshop-github-download-'));
+  try {
+    const downloaded = fetchSkill(reference, temporaryRoot);
+    let initialized = false;
+    let initializationSnapshot;
+    let skillsDirectory = layout.skillsDirectory;
+    if (!selected) initializationSnapshot = captureInitialization(root, stateHome);
+    try {
+      if (!selected) {
+        initialized = true;
+        const result = initPersonalLibrary(root, stateHome, templateRoot, { includeExample: false });
+        skillsDirectory = result.skillsDirectory;
+        if (path.resolve(skillsDirectory) !== path.resolve(layout.skillsDirectory)) {
+          throw fail('default library layout changed during download');
+        }
+      }
+      const committed = commitDownloadedPersonalSkill(root, skillsDirectory, reference.name, downloaded.skillDirectory, downloaded.origin, { force });
+      return { root, name: reference.name, origin: downloaded.origin, target: committed.target, alreadyPresent: false };
+    } catch (error) {
+      if (initialized) rollbackInitialization(root, stateHome, initializationSnapshot);
+      throw error;
+    }
+  } finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}