skillshop 4.0.0 → 4.1.0

package/src/dependencies.js

@@ -0,0 +1,282 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { fetchGitHubSkill, parseGitHubSkillReference } from './github-library.js';
+import { atomicJson, assertRegularPath, assertInstallationOwner, readInstallationManifest, writeInstallationManifest, sameOwner } from './installation-state.js';
+
+export const dependencyManifestName = 'skillshop.json';
+export const dependencyLockName = 'skillshop-lock.json';
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+const sorted = (value) => Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+
+export function parseDependencyReference(value) {
+  if (typeof value !== 'string') throw new Error('skill dependency must be @owner/skill or @owner/skill@ref');
+  const separator = value.lastIndexOf('@');
+  const reference = separator > 0 ? value.slice(0, separator) : value;
+  const ref = separator > 0 ? value.slice(separator + 1) : null;
+  if (ref !== null && (!ref || ref.startsWith('-') || !/^[A-Za-z0-9_./-]+$/.test(ref) || ref.includes('..') || ref.endsWith('/'))) {
+    throw new Error(`invalid skill dependency ref: ${ref}`);
+  }
+  return { ...parseGitHubSkillReference(reference), reference, ref, requested: value };
+}
+
+export function dependencyProjectRoot(cwd = process.cwd()) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, dependencyManifestName)) || fs.existsSync(path.join(current, '.git'))) return fs.realpathSync(current);
+    const parent = path.dirname(current);
+    if (parent === current) return fs.realpathSync(cwd);
+    current = parent;
+  }
+}
+
+function readJson(file) {
+  assertRegularPath(file);
+  if (!fs.existsSync(file)) return null;
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new Error(`cannot parse ${file}: ${error.message}`); }
+}
+
+function skillsPath(root, relative) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative) || relative.includes('\\')) throw new Error('dependency skillsDirectory must be a relative project directory');
+  const directory = path.resolve(root, relative);
+  const contained = path.relative(root, directory);
+  if (!contained || contained === '..' || contained.startsWith(`..${path.sep}`) || path.isAbsolute(contained)) throw new Error('dependency skillsDirectory escapes the project');
+  assertRegularPath(directory);
+  return directory;
+}
+
+function readManifest(root, { create = false } = {}) {
+  const manifest = readJson(path.join(root, dependencyManifestName));
+  if (!manifest) {
+    if (create) return { schemaVersion: 1, skillsDirectory: '.agents/skills', dependencies: {} };
+    throw new Error(`no ${dependencyManifestName}; add a dependency with skillshop dependency add @owner/skill@ref`);
+  }
+  if (manifest.schemaVersion !== 1 || !object(manifest.dependencies)) throw new Error(`${dependencyManifestName} is not a supported dependency manifest`);
+  skillsPath(root, manifest.skillsDirectory);
+  for (const [name, reference] of Object.entries(manifest.dependencies)) {
+    if (parseDependencyReference(reference).name !== name) throw new Error(`dependency ${name} must match its upstream skill name`);
+  }
+  return manifest;
+}
+
+function readLock(root) {
+  const lock = readJson(path.join(root, dependencyLockName));
+  if (!lock) return null;
+  if (lock.lockfileVersion !== 1 || !object(lock.dependencies)) throw new Error(`${dependencyLockName} is not a supported dependency lockfile`);
+  skillsPath(root, lock.skillsDirectory);
+  for (const [name, entry] of Object.entries(lock.dependencies)) {
+    if (!object(entry)) throw new Error(`invalid locked dependency ${name}`);
+    const parsed = parseDependencyReference(entry.reference);
+    if (parsed.name !== name || entry.repository !== parsed.repository || !/^[a-f0-9]{40,64}$/.test(entry.commit) || !/^sha256-[A-Za-z0-9+/]{43}=$/.test(entry.integrity)) {
+      throw new Error(`invalid locked dependency ${name}`);
+    }
+  }
+  return lock;
+}
+
+export function skillIntegrity(directory) {
+  assertRegularPath(directory);
+  const hash = createHash('sha256');
+  const visit = (relative = '') => {
+    const absolute = path.join(directory, relative);
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink()) throw new Error(`skill contains a symlink: ${absolute}`);
+    if (stat.isDirectory()) {
+      hash.update(JSON.stringify(['directory', relative]));
+      for (const name of fs.readdirSync(absolute).sort()) visit(relative ? `${relative}/${name}` : name);
+    } else if (stat.isFile()) {
+      const contents = fs.readFileSync(absolute);
+      hash.update(JSON.stringify(['file', relative, Boolean(stat.mode & 0o111), contents.length]));
+      hash.update(contents);
+    } else throw new Error(`skill contains a non-regular entry: ${absolute}`);
+  };
+  visit();
+  return `sha256-${hash.digest('base64')}`;
+}
+
+function lockMatches(manifest, lock) {
+  return lock && lock.skillsDirectory === manifest.skillsDirectory &&
+    JSON.stringify(sorted(manifest.dependencies)) === JSON.stringify(sorted(Object.fromEntries(Object.entries(lock.dependencies).map(([name, entry]) => [name, entry.reference]))));
+}
+
+function snapshotFile(file) {
+  assertRegularPath(file);
+  return fs.existsSync(file) ? { bytes: fs.readFileSync(file), mode: fs.statSync(file).mode & 0o777 } : null;
+}
+
+function dependencyExclusion(root, manifest, directories) {
+  let gitRoot;
+  try { gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return null; }
+  const relativeRoot = path.relative(gitRoot, root);
+  if (relativeRoot === '..' || relativeRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeRoot)) throw new Error('dependency project is outside its Git root');
+  const gitPath = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: root, encoding: 'utf8' }).trim();
+  const file = path.resolve(root, gitPath);
+  assertRegularPath(file);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const begin = '# >>> skillshop project dependencies >>>';
+  const end = '# <<< skillshop project dependencies <<<';
+  const lines = existing.replace(/\r\n/g, '\n').split('\n');
+  const starts = lines.flatMap((line, i) => line === begin ? [i] : []);
+  const ends = lines.flatMap((line, i) => line === end ? [i] : []);
+  if (starts.length !== ends.length || starts.length > 1 || (starts.length && starts[0] >= ends[0])) throw new Error('dependency Git exclude markers are malformed');
+  const retained = starts.length ? [...lines.slice(0, starts[0]), ...lines.slice(ends[0] + 1)] : lines;
+  while (retained.at(-1) === '') retained.pop();
+  const pattern = (target) => `/${path.relative(gitRoot, target).split(path.sep).join('/').replaceAll('\\', '\\\\').replace(/([ !#*?\[\]])/g, '\\$1')}`;
+  const directory = skillsPath(root, manifest.skillsDirectory);
+  const paths = [...directories.keys()].map((installedDirectory) => pattern(path.join(installedDirectory, '.skillshop-lock')));
+  paths.push(...Object.keys(manifest.dependencies).map((name) => `${pattern(path.join(directory, name))}/`));
+  return { file, contents: `${[...retained, ...(retained.length ? [''] : []), begin, ...[...new Set(paths)].sort(), end].join('\n')}\n` };
+}
+
+// All downloads and ownership/integrity checks finish before mutating any
+// installation. Backups keep replacement/removal and metadata writes recoverable.
+function commitChanges(root, manifest, lock, changes, directoryStates, { saveManifest }) {
+  const token = randomUUID();
+  const exclusion = dependencyExclusion(root, manifest, directoryStates);
+  const files = [path.join(root, dependencyLockName), ...(saveManifest ? [path.join(root, dependencyManifestName)] : []),
+    ...[...directoryStates.keys()].map((directory) => path.join(directory, '.skillshop-lock')), ...(exclusion ? [exclusion.file] : [])];
+  const before = new Map(files.map((file) => [file, snapshotFile(file)]));
+  const applied = [];
+  try {
+    for (const change of changes) {
+      const target = path.join(change.directory, change.name);
+      const backup = `${target}.skillshop-backup-${token}`;
+      const temporary = `${target}.skillshop-tmp-${token}`;
+      fs.mkdirSync(change.directory, { recursive: true });
+      if (change.source) fs.cpSync(change.source, temporary, { recursive: true });
+      const existed = fs.existsSync(target);
+      if (existed) fs.renameSync(target, backup);
+      const step = { target, backup, temporary, existed };
+      applied.push(step);
+      if (change.source) fs.renameSync(temporary, target);
+    }
+    for (const [directory, state] of directoryStates) writeInstallationManifest(directory, state);
+    atomicJson(path.join(root, dependencyLockName), lock);
+    if (saveManifest) atomicJson(path.join(root, dependencyManifestName), { ...manifest, dependencies: sorted(manifest.dependencies) });
+    if (exclusion && (!before.get(exclusion.file) || before.get(exclusion.file).bytes.toString('utf8') !== exclusion.contents)) {
+      fs.mkdirSync(path.dirname(exclusion.file), { recursive: true });
+      fs.writeFileSync(exclusion.file, exclusion.contents);
+    }
+  } catch (error) {
+    for (const step of applied.reverse()) {
+      fs.rmSync(step.target, { recursive: true, force: true });
+      if (step.existed) fs.renameSync(step.backup, step.target);
+    }
+    for (const [file, previous] of before) {
+      if (previous) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, previous.bytes, { mode: previous.mode });
+        fs.chmodSync(file, previous.mode);
+      } else fs.rmSync(file, { force: true });
+    }
+    throw error;
+  } finally {
+    for (const change of changes) {
+      const target = path.join(change.directory, change.name);
+      fs.rmSync(`${target}.skillshop-tmp-${token}`, { recursive: true, force: true });
+    }
+  }
+  // Cleanup after the commit cannot roll back a successfully published install.
+  for (const step of applied) fs.rmSync(step.backup, { recursive: true, force: true });
+}
+
+function installManifest(root, manifest, previousLock, { frozen = false, saveManifest = false } = {}) {
+  if (frozen && !lockMatches(manifest, previousLock)) throw new Error(`${dependencyLockName} is missing or out of date with ${dependencyManifestName}; frozen install refused`);
+  const directory = skillsPath(root, manifest.skillsDirectory);
+  const owner = { kind: 'dependency', id: 'project' };
+  const directories = new Map([[directory, readInstallationManifest(directory)]]);
+  if (previousLock) {
+    const previousDirectory = skillsPath(root, previousLock.skillsDirectory);
+    if (!directories.has(previousDirectory)) directories.set(previousDirectory, readInstallationManifest(previousDirectory));
+  }
+  // Detect ownership conflicts before network requests, including removals.
+  for (const name of Object.keys(manifest.dependencies)) assertInstallationOwner(directory, name, owner);
+  const removals = [];
+  for (const [installedDirectory, state] of directories) {
+    for (const [name, entry] of Object.entries(state.skills)) {
+      if (sameOwner(entry.owner, owner) && (installedDirectory !== directory || !Object.hasOwn(manifest.dependencies, name))) {
+        assertInstallationOwner(installedDirectory, name, owner, { requireOwned: true });
+        removals.push({ directory: installedDirectory, name });
+        delete state.skills[name];
+      }
+    }
+  }
+  const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skillshop-dependencies-'));
+  try {
+    const dependencies = {};
+    const changes = [...removals];
+    for (const [name, reference] of Object.entries(sorted(manifest.dependencies))) {
+      const parsed = parseDependencyReference(reference);
+      const previous = previousLock?.dependencies[name];
+      const locked = previous?.reference === reference ? previous : null;
+      const target = path.join(directory, name);
+      const existing = directories.get(directory).skills[name];
+      let current = false;
+      if (locked && existing?.source?.commit === locked.commit && existing?.source?.integrity === locked.integrity && fs.existsSync(target)) {
+        current = skillIntegrity(target) === locked.integrity;
+      }
+      let resolved = locked;
+      if (!current) {
+        const staging = path.join(temporaryRoot, name);
+        fs.mkdirSync(staging);
+        const fetched = fetchGitHubSkill(parsed.reference, staging, locked ? { commit: locked.commit } : { ref: parsed.ref });
+        const integrity = skillIntegrity(fetched.skillDirectory);
+        if (locked && integrity !== locked.integrity) throw new Error(`integrity mismatch for locked dependency ${name}; installation unchanged`);
+        resolved = { reference, repository: parsed.repository, commit: fetched.origin.commit, integrity };
+        changes.push({ directory, name, source: fetched.skillDirectory });
+      }
+      dependencies[name] = resolved;
+      directories.get(directory).skills[name] = { owner, source: { kind: 'dependency', ...resolved } };
+    }
+    const lock = { lockfileVersion: 1, skillsDirectory: manifest.skillsDirectory, dependencies };
+    commitChanges(root, manifest, lock, changes, directories, { saveManifest });
+    return { root, lock, changed: changes.length };
+  } finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+export function addDependency(reference, { cwd = process.cwd() } = {}) {
+  const parsed = parseDependencyReference(reference);
+  const root = dependencyProjectRoot(cwd);
+  const manifest = readManifest(root, { create: true });
+  manifest.dependencies[parsed.name] = reference;
+  return installManifest(root, manifest, readLock(root), { saveManifest: true });
+}
+
+export function installDependencies({ cwd = process.cwd(), frozen = false } = {}) {
+  const root = dependencyProjectRoot(cwd);
+  return installManifest(root, readManifest(root), readLock(root), { frozen });
+}
+
+export function updateDependencies(name = null, { cwd = process.cwd() } = {}) {
+  const root = dependencyProjectRoot(cwd);
+  const manifest = readManifest(root);
+  if (name !== null && !Object.hasOwn(manifest.dependencies, name)) throw new Error(`${name} is not a declared project skill dependency`);
+  const lock = readLock(root);
+  if (lock) {
+    for (const key of Object.keys(manifest.dependencies)) {
+      if (name === null || key === name) delete lock.dependencies[key];
+    }
+  }
+  return installManifest(root, manifest, lock);
+}
+
+export function removeDependency(name, { cwd = process.cwd() } = {}) {
+  const root = dependencyProjectRoot(cwd);
+  const manifest = readManifest(root);
+  if (!Object.hasOwn(manifest.dependencies, name)) throw new Error(`${name} is not a declared project skill dependency`);
+  const lock = readLock(root);
+  if (!lockMatches(manifest, lock)) throw new Error(`${dependencyLockName} is missing or out of date; install dependencies before removing one`);
+  const directory = skillsPath(root, manifest.skillsDirectory);
+  const state = assertInstallationOwner(directory, name, { kind: 'dependency', id: 'project' });
+  delete state.skills[name];
+  delete manifest.dependencies[name];
+  delete lock.dependencies[name];
+  commitChanges(root, manifest, lock, [{ directory, name }], new Map([[directory, state]]), { saveManifest: true });
+  return { root, lock, changed: 1 };
+}

package/src/github-library.js

@@ -158,20 +158,28 @@ function stageSkill(repositoryDir, commit, skillPath, name, stagingRoot) {
   return skillDirectory;
 }
 
-function fetchSkill(reference, temporaryRoot) {
+function fetchSkill(reference, temporaryRoot, { ref = null, commit: expectedCommit = null } = {}) {
   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]);
+  let fetchRef = expectedCommit ?? ref;
+  if (expectedCommit && !/^[a-f0-9]{40,64}$/.test(expectedCommit)) throw fail('invalid locked commit identifier');
+  if (fetchRef) {
+    if (typeof fetchRef !== 'string' || fetchRef.startsWith('-')) throw fail('invalid Git skill ref');
+    if (!/^[a-f0-9]{40,64}$/.test(fetchRef)) git(['check-ref-format', '--allow-onelevel', fetchRef]);
+  } else {
+    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}`);
+    fetchRef = headReference.slice('ref: '.length, -'\tHEAD'.length);
+    if (!fetchRef.startsWith('refs/heads/')) throw fail('GitHub repository default is not a branch');
+    git(['-C', bareRepository, 'check-ref-format', fetchRef]);
+  }
+  git(['-C', bareRepository, 'fetch', '--no-tags', '--no-recurse-submodules', '--depth=1', reference.repository, fetchRef]);
   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');
+  if (expectedCommit && commit !== expectedCommit) throw fail(`fetched commit does not match locked commit ${expectedCommit}`);
   const config = readRemoteConfig(bareRepository, commit);
   const skillPath = config.skillsDirectory === '.' ? reference.name : `${config.skillsDirectory}/${reference.name}`;
   if (config.skillsDirectory === '.' && reservedRootNames.has(reference.name)) {
@@ -181,6 +189,10 @@ function fetchSkill(reference, temporaryRoot) {
   return { skillDirectory, origin: { repository: reference.repository, commit } };
 }
 
+export function fetchGitHubSkill(reference, temporaryRoot, options = {}) {
+  return fetchSkill(parseGitHubSkillReference(reference), temporaryRoot, options);
+}
+
 function snapshotFile(filePath) {
   try {
     const stat = fs.lstatSync(filePath);

package/src/import.js

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { normalizeSkillSpecifier, parseSkillSpecifier, parseLibrarySkillReference } from './specifier.js';
 import { SKILLSHOP_MANIFEST_FILE, SKILLSHOP_SCHEMA_VERSION } from './library.js';
+import { assertInstallationOwner, writeInstallationManifest } from './installation-state.js';
 
 async function importManifestFile(file) {
   // Content-based cache keys also invalidate in long-lived consumers when two
@@ -95,11 +96,23 @@ export async function importSkill({
   cwd = process.cwd(),
   overwrite = false,
   merge = false,
+  ownerKind = 'package-import',
 }) {
   if (targetDir !== undefined && (typeof targetDir !== 'string' || !targetDir.trim())) throw new Error('targetDir must be a nonempty path');
   if (merge && overwrite) throw new Error('merge and overwrite cannot both be enabled');
   const skill = await resolveSkill({ reference, library, specifier, cwd });
   const target = path.resolve(cwd, targetDir ?? path.join('.agents', 'skills', skill.name));
+  const source = path.resolve(skill.sourceDir);
+  if ([path.relative(source, target), path.relative(target, source)].some((relative) => relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)))) {
+    throw new Error('skill import destination overlaps its source directory');
+  }
+  listSkillFiles(skill.sourceDir);
+  const owner = { kind: ownerKind, id: skill.packageName || skill.sourceDir };
+  const installation = assertInstallationOwner(path.dirname(target), path.basename(target), owner);
+  const saveOwnership = () => {
+    installation.skills[path.basename(target)] = { owner, source: { kind: 'package', package: skill.packageName, specifier: skill.specifier } };
+    writeInstallationManifest(path.dirname(target), installation);
+  };
   const exists = fs.existsSync(target);
 
   if (exists && merge) {
@@ -121,6 +134,7 @@ export async function importSkill({
         addedFiles += 1;
       }
     }
+    saveOwnership();
     return { ...skill, targetDir: target, installed: addedFiles > 0, updated: updatedFiles > 0, addedFiles, updatedFiles };
   }
 
@@ -132,6 +146,7 @@ export async function importSkill({
     fs.cpSync(skill.sourceDir, temporary, { recursive: true, force: true });
     if (overwrite) fs.rmSync(target, { recursive: true, force: true });
     fs.renameSync(temporary, target);
+    saveOwnership();
   } finally {
     fs.rmSync(temporary, { recursive: true, force: true });
   }

package/src/index.js

@@ -3,3 +3,5 @@ export * from './library.js';
 export * from './export.js';
 export * from './import.js';
 export * from './user-install.js';
+export * from './dependencies.js';
+export * from './installation-state.js';

package/src/installation-state.js

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const installationManifestName = '.skillshop-lock';
+const skillNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export function assertRegularPath(target) {
+  const absolute = path.resolve(target);
+  let current = path.parse(absolute).root;
+  for (const segment of absolute.slice(current.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      // macOS exposes its system temporary directories through these aliases.
+      const systemAlias = process.platform === 'darwin' && ['/var', '/tmp'].includes(current);
+      if (fs.lstatSync(current).isSymbolicLink() && !systemAlias) throw new Error(`installation path contains a symlink: ${current}`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export function atomicJson(file, value) {
+  assertRegularPath(file);
+  const contents = `${JSON.stringify(value, null, 2)}\n`;
+  if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === contents) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${randomUUID()}`;
+  try {
+    fs.writeFileSync(temporary, contents, { flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+export function sameOwner(left, right) {
+  return left?.kind === right?.kind && left?.id === right?.id;
+}
+
+export function readInstallationManifest(directory) {
+  const file = path.join(directory, installationManifestName);
+  assertRegularPath(file);
+  if (!fs.existsSync(file)) return { manifestVersion: 1, skills: {} };
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new Error(`cannot parse ${file}: ${error.message}`); }
+  if (manifest?.manifestVersion !== 1 || !manifest.skills || typeof manifest.skills !== 'object' || Array.isArray(manifest.skills)) {
+    throw new Error(`${file} is not a supported Skillshop installation manifest`);
+  }
+  for (const [name, entry] of Object.entries(manifest.skills)) {
+    if (!skillNamePattern.test(name) || !entry || typeof entry !== 'object' ||
+        typeof entry.owner?.kind !== 'string' || !entry.owner.kind || typeof entry.owner?.id !== 'string' || !entry.owner.id) {
+      throw new Error(`${file} has an invalid ownership entry for ${name}`);
+    }
+  }
+  return manifest;
+}
+
+export function writeInstallationManifest(directory, manifest) {
+  atomicJson(path.join(directory, installationManifestName), {
+    manifestVersion: 1,
+    skills: Object.fromEntries(Object.entries(manifest.skills).sort(([a], [b]) => a.localeCompare(b)))
+  });
+}
+
+export function assertInstallationOwner(directory, name, owner, { requireOwned = false } = {}) {
+  if (!skillNamePattern.test(name)) throw new Error(`invalid skill name: ${name}`);
+  const target = path.join(directory, name);
+  assertRegularPath(target);
+  const manifest = readInstallationManifest(directory);
+  const existing = manifest.skills[name];
+  if (existing && !sameOwner(existing.owner, owner)) {
+    throw new Error(`${target} is owned by ${existing.owner.kind}:${existing.owner.id}; refusing to replace or remove it`);
+  }
+  if (!existing && (requireOwned || fs.existsSync(target))) {
+    throw new Error(`${target} exists or was requested for removal but is not a Skillshop-managed copy owned by ${owner.kind}:${owner.id}`);
+  }
+  return manifest;
+}
+
+export function stateHome() {
+  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;
+}
+
+export function readInstallationIndex(home = stateHome()) {
+  const file = path.join(home, 'installations.json');
+  assertRegularPath(file);
+  if (!fs.existsSync(file)) return [];
+  let index;
+  try { index = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new Error(`cannot parse ${file}: ${error.message}`); }
+  if (index?.indexVersion !== 1 || !Array.isArray(index.installations) || index.installations.some((entry) =>
+    !entry || !path.isAbsolute(entry.directory ?? '') || !['project', 'global'].includes(entry.scope) ||
+    (entry.scope === 'project' && !path.isAbsolute(entry.root ?? '')))) {
+    throw new Error(`${file} is not a supported installation discovery index`);
+  }
+  return index.installations;
+}
+
+export function registerInstallationDirectory(directory, { root = null, home = stateHome() } = {}) {
+  const entry = root ? { directory: path.resolve(directory), scope: 'project', root: path.resolve(root) }
+    : { directory: path.resolve(directory), scope: 'global' };
+  const entries = readInstallationIndex(home).filter((item) => item.directory !== entry.directory);
+  entries.push(entry);
+  entries.sort((a, b) => a.directory.localeCompare(b.directory));
+  atomicJson(path.join(home, 'installations.json'), { indexVersion: 1, installations: entries });
+}