skillshop 0.0.0-stage → 2.1.0

package/src/library.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { normalizeSkillSpecifier, parseSkillSpecifier } from './specifier.js';
+
+export const SKILLSHOP_LIBRARY_FILE = 'skillshop.library.json';
+export const SKILLSHOP_MANIFEST_FILE = 'skillshop.manifest.mjs';
+export const SKILLSHOP_SCHEMA_VERSION = 1;
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new Error(`Cannot read ${file}: ${error.message}`); }
+}
+
+function packageFile(root) { return path.join(path.resolve(root), 'package.json'); }
+function libraryFile(root) { return path.join(path.resolve(root), SKILLSHOP_LIBRARY_FILE); }
+
+function normalizeLocalSource(source) {
+  if (typeof source !== 'string' || !source.trim()) throw new Error('skill source must be a nonempty relative path');
+  const raw = source.trim().replaceAll('\\', '/');
+  if (path.posix.isAbsolute(raw)) throw new Error('skill source must be relative to the library package');
+  const normalized = path.posix.normalize(raw.replace(/^\.\//, ''));
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) throw new Error('skill source must stay inside the library package');
+  if (/[*?\[\]{}()!]/.test(normalized)) {
+    throw new Error('skill source must not contain npm glob metacharacters');
+  }
+  const segments = normalized.split('/');
+  const npmExcludedDirectories = new Set(['node_modules', '.git', '.svn', 'CVS']);
+  if (segments.some((segment) => npmExcludedDirectories.has(segment))) {
+    throw new Error('skill source must not live under an npm-excluded directory');
+  }
+  return `./${normalized}`;
+}
+
+function normalizeTarget(target, exportedSpecifier) {
+  if (typeof target === 'string') return normalizeLocalSource(target);
+  if (!target || typeof target !== 'object' || Array.isArray(target)) throw new Error(`Invalid export target for ${exportedSpecifier}`);
+  if (typeof target.from !== 'string' || !target.from.trim()) throw new Error(`Imported export ${exportedSpecifier} needs a package in "from"`);
+  const importedSkill = normalizeSkillSpecifier(target.skill || exportedSpecifier);
+  return { from: target.from.trim(), skill: importedSkill };
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function assertNoSymlinks(directory, specifier) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name === '.npmignore' || entry.name === '.gitignore') {
+      throw new Error(`Skill ${specifier} must not contain nested npm/git ignore files that can exclude packaged assets`);
+    }
+    const entryPath = path.join(directory, entry.name);
+    const stat = fs.lstatSync(entryPath);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Skill ${specifier} must not contain symlinks because npm packages omit symbolic links`);
+    }
+    if (stat.isDirectory()) assertNoSymlinks(entryPath, specifier);
+  }
+}
+
+function assertNoParentIgnores(root, source, specifier) {
+  // Root ignore rules are overridden by package.json#files, but nested ignore
+  // rules can still omit SKILL.md even when its directory is explicitly packed.
+  for (let directory = path.dirname(source); directory !== root; directory = path.dirname(directory)) {
+    for (const name of ['.npmignore', '.gitignore']) {
+      if (fs.existsSync(path.join(directory, name))) {
+        throw new Error(`Skill ${specifier} has nested ignore rules in ${directory} that can exclude packaged assets`);
+      }
+    }
+  }
+}
+
+function legacyRootExport(packageRoot) {
+  const realRoot = fs.realpathSync(packageRoot);
+  const requireFromPackage = createRequire(path.join(realRoot, '__skillshop_resolve__.cjs'));
+  let resolved;
+  try {
+    resolved = requireFromPackage.resolve(realRoot);
+  } catch {
+    return null;
+  }
+  const realResolved = fs.realpathSync(resolved);
+  if (!inside(realRoot, realResolved)) {
+    throw new Error('package root entry resolves outside the package');
+  }
+  const relative = path.relative(realRoot, realResolved).split(path.sep).join('/');
+  return relative ? `./${relative}` : null;
+}
+
+export function resolveLocalSkill(root, specifier, library = readSkillLibrary(root, { required: true })) {
+  const packageRoot = fs.realpathSync(path.resolve(root));
+  const normalized = normalizeSkillSpecifier(specifier);
+  const target = library.exports[normalized];
+  if (!target) throw new Error(`Skill ${normalized} is not exported by this library`);
+  if (typeof target !== 'string') throw new Error(`Skill ${normalized} is re-exported from ${target.from}, not stored locally`);
+  const source = normalizeLocalSource(target);
+  const sourceDir = path.resolve(packageRoot, source);
+  if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) throw new Error(`Skill ${normalized} source directory does not exist: ${source}`);
+  const realSource = fs.realpathSync(sourceDir);
+  if (!inside(packageRoot, realSource)) throw new Error(`Skill ${normalized} source escapes the library package`);
+  if (path.normalize(realSource) !== path.normalize(sourceDir)) {
+    throw new Error(`Skill ${normalized} source must not use symlinks because npm packages omit symbolic links`);
+  }
+  assertNoParentIgnores(packageRoot, realSource, normalized);
+  assertNoSymlinks(realSource, normalized);
+  const manifestPath = path.join(realSource, 'SKILL.md');
+  if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
+    throw new Error(`Skill ${normalized} is missing a regular SKILL.md file`);
+  }
+  return Object.freeze({ ...parseSkillSpecifier(normalized), kind: 'local', source, sourceDir: realSource, manifestPath });
+}
+
+export function readSkillLibrary(root = process.cwd(), { required = false } = {}) {
+  const file = libraryFile(root);
+  if (!fs.existsSync(file)) {
+    if (required) throw new Error(`No ${SKILLSHOP_LIBRARY_FILE} found at ${path.resolve(root)}`);
+    return { schemaVersion: SKILLSHOP_SCHEMA_VERSION, exports: {} };
+  }
+  const raw = readJson(file);
+  if (raw?.schemaVersion !== SKILLSHOP_SCHEMA_VERSION || !raw.exports || Array.isArray(raw.exports) || typeof raw.exports !== 'object') throw new Error(`${file} is not a supported Skillshop library`);
+  const exports = {};
+  for (const [specifier, target] of Object.entries(raw.exports)) {
+    const normalized = normalizeSkillSpecifier(specifier);
+    if (normalized !== specifier) throw new Error(`Skill export must use canonical specifier ${normalized}`);
+    exports[normalized] = normalizeTarget(target, normalized);
+  }
+  return { schemaVersion: SKILLSHOP_SCHEMA_VERSION, exports };
+}
+
+export function writeSkillLibrary(root, library) {
+  const file = libraryFile(root);
+  const stable = {
+    schemaVersion: SKILLSHOP_SCHEMA_VERSION,
+    exports: Object.fromEntries(Object.entries(library.exports || {}).sort(([a], [b]) => a.localeCompare(b))),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(stable, null, 2)}\n`);
+  return file;
+}
+
+export function initSkillLibrary(root = process.cwd()) {
+  const packageRoot = path.resolve(root);
+  if (!fs.existsSync(packageFile(packageRoot))) throw new Error('Skillshop libraries require a package.json');
+  const file = libraryFile(packageRoot);
+  if (!fs.existsSync(file)) writeSkillLibrary(packageRoot, { exports: {} });
+  return readSkillLibrary(packageRoot, { required: true });
+}
+
+function dependencyNames(pkg) {
+  const names = new Set(Object.keys(pkg.dependencies || {}));
+  for (const name of Object.keys(pkg.peerDependencies || {})) {
+    if (pkg.peerDependenciesMeta?.[name]?.optional === true) continue;
+    names.add(name);
+  }
+  return names;
+}
+
+function validateExports(packageRoot, pkg, library) {
+  const dependencies = dependencyNames(pkg);
+  return Object.entries(library.exports).map(([specifier, target]) => {
+    if (typeof target === 'string') return resolveLocalSkill(packageRoot, specifier, library);
+    if (!dependencies.has(target.from)) throw new Error(`Re-export ${specifier} requires ${target.from} in dependencies or peerDependencies`);
+    return Object.freeze({ ...parseSkillSpecifier(specifier), kind: 'import', from: target.from, importedSpecifier: target.skill });
+  });
+}
+
+function relativeUrlPath(source) {
+  return source.split('/').map((segment) => encodeURIComponent(segment)).join('/');
+}
+
+function manifestSource(packageName, library) {
+  const importedPackages = [...new Set(
+    Object.values(library.exports)
+      .filter((target) => typeof target === 'object')
+      .map((target) => target.from),
+  )].sort();
+  const aliases = new Map(importedPackages.map((name, index) => [name, `library${index}`]));
+  const imports = importedPackages.map((name) => `import ${aliases.get(name)} from ${JSON.stringify(`${name}/skillshop`)};`).join('\n');
+  const skills = Object.entries(library.exports).sort(([a], [b]) => a.localeCompare(b)).map(([specifier, target]) => {
+    if (typeof target === 'string') {
+      const directory = target.endsWith('/') ? target : `${target}/`;
+      return `  ${JSON.stringify(specifier)}: new URL(${JSON.stringify(relativeUrlPath(directory))}, import.meta.url).href,`;
+    }
+    return `  ${JSON.stringify(specifier)}: ${aliases.get(target.from)}.skills[${JSON.stringify(target.skill)}],`;
+  }).join('\n');
+  return `// Generated by Skillshop. Do not edit by hand.\n${imports}${imports ? '\n\n' : ''}const skills = Object.freeze({\n${skills}\n});\n\nexport default Object.freeze({\n  schemaVersion: ${SKILLSHOP_SCHEMA_VERSION},\n  packageName: ${JSON.stringify(packageName)},\n  skills,\n});\n`;
+}
+
+function mergePackageExports(pkg, packageRoot) {
+  const skillshopExport = `./${SKILLSHOP_MANIFEST_FILE}`;
+  if (pkg.exports == null) {
+    const rootExport = legacyRootExport(packageRoot);
+    return rootExport
+      ? { '.': rootExport, './skillshop': skillshopExport }
+      : { './skillshop': skillshopExport };
+  }
+  if (typeof pkg.exports !== 'object' || Array.isArray(pkg.exports)) {
+    return { '.': pkg.exports, './skillshop': skillshopExport };
+  }
+  const keys = Object.keys(pkg.exports);
+  const subpaths = keys.filter((key) => key.startsWith('.'));
+  if (subpaths.length && subpaths.length !== keys.length) {
+    throw new Error('package.json exports mixes subpaths and conditions and cannot be extended safely');
+  }
+  if (!subpaths.length) return { '.': pkg.exports, './skillshop': skillshopExport };
+  return { ...pkg.exports, './skillshop': skillshopExport };
+}
+
+function nextPackageManifest(packageRoot, pkg, skills) {
+  const next = structuredClone(pkg);
+  next.exports = mergePackageExports(next, packageRoot);
+  if (Array.isArray(next.files)) {
+    const previousManaged = new Set(Array.isArray(next.skillshop?.managedFiles) ? next.skillshop.managedFiles : []);
+    const userFiles = next.files.filter((file) => !previousManaged.has(file));
+    const desired = [
+      SKILLSHOP_MANIFEST_FILE,
+      ...skills.filter((skill) => skill.kind === 'local').map((skill) => skill.source.replace(/^\.\//, '').replace(/\/$/, '')),
+    ];
+    const managedFiles = desired.filter((file) => !userFiles.includes(file));
+    next.files = [...new Set([...userFiles, ...desired])];
+    next.skillshop = { ...(next.skillshop || {}), schemaVersion: SKILLSHOP_SCHEMA_VERSION, managedFiles };
+  }
+  return next;
+}
+
+export function validateSkillLibrary(root = process.cwd()) {
+  const packageRoot = path.resolve(root);
+  const pkgPath = packageFile(packageRoot);
+  if (!fs.existsSync(pkgPath)) throw new Error('Skillshop libraries require a package.json');
+  const pkg = readJson(pkgPath);
+  if (typeof pkg.name !== 'string' || !pkg.name.trim()) throw new Error('package.json must have a package name');
+  const library = readSkillLibrary(packageRoot, { required: true });
+  const skills = validateExports(packageRoot, pkg, library);
+  const userInstall = pkg.skillshop?.userInstall ?? [];
+  if (!Array.isArray(userInstall) || new Set(userInstall).size !== userInstall.length ||
+      userInstall.some((specifier) => {
+        try {
+          return normalizeSkillSpecifier(specifier) !== specifier || !Object.hasOwn(library.exports, specifier);
+        } catch { return true; }
+      })) {
+    throw new Error('package.json#skillshop.userInstall must list unique exported skill specifiers');
+  }
+  return { packageName: pkg.name, library, skills };
+}
+
+export function buildSkillLibrary(root = process.cwd()) {
+  const packageRoot = path.resolve(root);
+  const { packageName, library, skills } = validateSkillLibrary(packageRoot);
+  const manifestPath = path.join(packageRoot, SKILLSHOP_MANIFEST_FILE);
+  const pkgPath = packageFile(packageRoot);
+  const pkg = readJson(pkgPath);
+
+  const nextPkg = nextPackageManifest(packageRoot, pkg, skills);
+  const nextManifest = manifestSource(packageName, library);
+
+  fs.writeFileSync(manifestPath, nextManifest);
+  fs.writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`);
+  return { packageName, manifestPath, skills };
+}

package/src/specifier.js

@@ -0,0 +1,27 @@
+const SKILL_SPECIFIER = /^skill:([a-z0-9][a-z0-9._-]*)$/;
+
+export function parseSkillSpecifier(value) {
+  if (typeof value !== 'string') throw new TypeError('skill specifier must be a string');
+  const match = value.trim().match(SKILL_SPECIFIER);
+  if (!match) throw new Error(`Invalid skill specifier: ${value}. Expected skill:<name>`);
+  return Object.freeze({ specifier: `skill:${match[1]}`, name: match[1] });
+}
+
+export function normalizeSkillSpecifier(value) {
+  return parseSkillSpecifier(value).specifier;
+}
+
+export function skillName(value) {
+  return parseSkillSpecifier(value).name;
+}
+
+export function parseLibrarySkillReference(value) {
+  if (typeof value !== 'string') throw new TypeError('library skill reference must be a string');
+  const separator = value.lastIndexOf(':');
+  if (separator <= 0 || separator === value.length - 1) {
+    throw new Error(`Invalid library skill reference: ${value}. Expected <library>:<skill>`);
+  }
+  const library = value.slice(0, separator);
+  const skill = parseSkillSpecifier(`skill:${value.slice(separator + 1)}`);
+  return Object.freeze({ library, specifier: skill.specifier, name: skill.name });
+}

package/src/user-install.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { importSkill } from './import.js';
+import { normalizeSkillSpecifier, skillName } from './specifier.js';
+
+function declaredUserSkills(packageRoot) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  const declared = pkg.skillshop?.userInstall ?? [];
+  if (!Array.isArray(declared) || new Set(declared).size !== declared.length ||
+      declared.some((specifier) => {
+        try { return normalizeSkillSpecifier(specifier) !== specifier; }
+        catch { return true; }
+      })) {
+    throw new Error('package.json#skillshop.userInstall must list unique skill specifiers');
+  }
+  return declared;
+}
+
+export async function installUserSkill({
+  library,
+  specifier,
+  cwd = process.cwd(),
+  userSkillsDir = path.join(os.homedir(), '.agents', 'skills'),
+}) {
+  const normalized = normalizeSkillSpecifier(specifier);
+  return importSkill({
+    library,
+    specifier: normalized,
+    targetDir: path.resolve(userSkillsDir, skillName(normalized)),
+    cwd,
+    overwrite: true,
+  });
+}
+
+export async function installDeclaredUserSkills({
+  library = process.cwd(),
+  userSkillsDir,
+  cwd = process.cwd(),
+} = {}) {
+  const packageRoot = path.resolve(cwd, library);
+  const declared = declaredUserSkills(packageRoot);
+  const results = [];
+  for (const specifier of declared) {
+    results.push(await installUserSkill({ library: packageRoot, specifier, cwd, userSkillsDir }));
+  }
+  return results;
+}