@akshar5/skillsync 0.1.0

package/src/core/device.js

@@ -0,0 +1,285 @@
+import { cp, lstat, mkdir, readlink, readdir, realpath, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import path from 'node:path';
+
+import { ensureDir, exists, expandHome, readJson, removePath, slugifySkillName, writeJson } from './fs.js';
+import { ensureVault, loadRegistry } from './registry.js';
+
+export function defaultDeviceId() {
+  return slugifySkillName(hostname()) || 'device';
+}
+
+export function newDevice(deviceId = defaultDeviceId()) {
+  return {
+    version: 1,
+    device_id: deviceId,
+    display_name: deviceId,
+    last_seen: new Date().toISOString(),
+    targets: {},
+    installed: {},
+    detected: {},
+  };
+}
+
+export function devicePath(vaultPath, deviceId) {
+  return path.join(vaultPath, 'devices', `${deviceId}.json`);
+}
+
+export async function loadDevice(vaultPath, deviceId = defaultDeviceId()) {
+  await ensureVault(vaultPath);
+  const device = await readJson(devicePath(vaultPath, deviceId), newDevice(deviceId));
+  return normalizeDevice(device, deviceId);
+}
+
+export async function saveDevice(vaultPath, device) {
+  await ensureVault(vaultPath);
+  const normalized = normalizeDevice(device, device.device_id);
+  await writeJson(devicePath(vaultPath, normalized.device_id), normalized);
+}
+
+function normalizeDevice(device, deviceId) {
+  return {
+    version: 1,
+    device_id: device?.device_id || deviceId || defaultDeviceId(),
+    display_name: device?.display_name || device?.device_id || deviceId || defaultDeviceId(),
+    last_seen: device?.last_seen || new Date().toISOString(),
+    targets: normalizeTargets(device?.targets),
+    installed: device?.installed && typeof device.installed === 'object' ? device.installed : {},
+    detected: device?.detected && typeof device.detected === 'object' ? device.detected : {},
+  };
+}
+
+function normalizeTargets(targets) {
+  if (!targets || typeof targets !== 'object') return {};
+  return Object.fromEntries(Object.entries(targets).map(([name, target]) => [
+    name,
+    {
+      path: target.path,
+      mode: target.mode || 'symlink',
+      ...(target.scan_path ? { scan_path: target.scan_path } : {}),
+    },
+  ]));
+}
+
+export async function touchDevice({ vaultPath, deviceId = defaultDeviceId() }) {
+  const device = await loadDevice(vaultPath, deviceId);
+  device.last_seen = new Date().toISOString();
+  await saveDevice(vaultPath, device);
+  return device;
+}
+
+export async function addTarget({ vaultPath, deviceId = defaultDeviceId(), name, targetPath, mode = 'symlink', scanPath }) {
+  if (!name) throw new Error('Target name is required');
+  if (!targetPath) throw new Error('Target path is required');
+  if (!['symlink', 'copy'].includes(mode)) throw new Error(`Unsupported target mode: ${mode}`);
+  const device = await loadDevice(vaultPath, deviceId);
+  device.targets[name] = { path: targetPath, mode, ...(scanPath ? { scan_path: scanPath } : {}) };
+  device.last_seen = new Date().toISOString();
+  await saveDevice(vaultPath, device);
+  return device;
+}
+
+export async function removeTarget({ vaultPath, deviceId = defaultDeviceId(), name }) {
+  const device = await loadDevice(vaultPath, deviceId);
+  delete device.targets[name];
+  delete device.detected[name];
+  for (const targets of Object.values(device.installed)) {
+    const index = targets.indexOf(name);
+    if (index >= 0) targets.splice(index, 1);
+  }
+  await saveDevice(vaultPath, device);
+  return device;
+}
+
+export async function installSkill({ vaultPath, deviceId = defaultDeviceId(), skillName, targets }) {
+  const registry = await loadRegistry(vaultPath);
+  if (!registry.skills[skillName]) throw new Error(`Skill not found in vault: ${skillName}`);
+  const device = await loadDevice(vaultPath, deviceId);
+  const selectedTargets = targets?.length ? targets : Object.keys(device.targets);
+  if (!selectedTargets.length) throw new Error('No targets configured. Add one with: skillsync target add <name> <path>');
+  for (const target of selectedTargets) {
+    if (!device.targets[target]) throw new Error(`Unknown target on this device: ${target}`);
+  }
+  device.installed[skillName] = [...new Set(selectedTargets)].sort();
+  device.last_seen = new Date().toISOString();
+  await saveDevice(vaultPath, device);
+  return device;
+}
+
+export async function uninstallSkill({ vaultPath, deviceId = defaultDeviceId(), skillName, targets }) {
+  const device = await loadDevice(vaultPath, deviceId);
+  if (!device.installed[skillName]) return device;
+  if (!targets?.length) {
+    delete device.installed[skillName];
+  } else {
+    device.installed[skillName] = device.installed[skillName].filter((target) => !targets.includes(target));
+    if (!device.installed[skillName].length) delete device.installed[skillName];
+  }
+  device.last_seen = new Date().toISOString();
+  await saveDevice(vaultPath, device);
+  return device;
+}
+
+export async function applyLinks({ vaultPath, deviceId = defaultDeviceId() }) {
+  const device = await loadDevice(vaultPath, deviceId);
+  const registry = await loadRegistry(vaultPath);
+  const desiredByTarget = new Map();
+  for (const [skillName, targets] of Object.entries(device.installed)) {
+    if (!registry.skills[skillName]) continue;
+    for (const targetName of targets) {
+      if (!device.targets[targetName]) continue;
+      if (!desiredByTarget.has(targetName)) desiredByTarget.set(targetName, new Set());
+      desiredByTarget.get(targetName).add(skillName);
+    }
+  }
+
+  for (const [targetName, targetConfig] of Object.entries(device.targets)) {
+    const targetPath = expandHome(targetConfig.path);
+    await ensureDir(targetPath);
+    const desired = desiredByTarget.get(targetName) || new Set();
+    await removeStaleOwnedProjections({ vaultPath, targetPath, desired });
+    for (const skillName of desired) {
+      const source = path.join(vaultPath, registry.skills[skillName].path);
+      const destination = path.join(targetPath, skillName);
+      if (targetConfig.mode === 'copy') {
+        await createCopyProjection(source, destination, skillName, vaultPath);
+      } else {
+        await createSymlinkProjection(source, destination);
+      }
+    }
+  }
+}
+
+export async function scanTargets({ vaultPath, deviceId = defaultDeviceId() }) {
+  const device = await loadDevice(vaultPath, deviceId);
+  const registry = await loadRegistry(vaultPath);
+  const detected = {};
+  for (const [targetName, targetConfig] of Object.entries(device.targets)) {
+    const scanPath = expandHome(targetConfig.scan_path || targetConfig.path);
+    const skills = await findLocalSkills(scanPath);
+    detected[targetName] = skills.map((skill) => ({
+      ...skill,
+      in_vault: Boolean(registry.skills[skill.name]),
+    }));
+  }
+  device.detected = detected;
+  await saveDevice(vaultPath, device);
+  return device;
+}
+
+async function findLocalSkills(scanPath) {
+  const root = path.resolve(scanPath);
+  if (!await exists(root)) return [];
+  const seen = new Set();
+  const skills = [];
+
+  async function walk(current) {
+    let canonical;
+    try {
+      canonical = await realpath(current);
+    } catch {
+      canonical = path.resolve(current);
+    }
+    if (seen.has(canonical)) return;
+    seen.add(canonical);
+
+    if (await exists(path.join(current, 'SKILL.md'))) {
+      skills.push({
+        name: slugifySkillName(path.basename(current)),
+        path: path.relative(root, current).split(path.sep).join(path.posix.sep) || '.',
+      });
+      return;
+    }
+
+    const entries = await readdir(current, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const child = path.join(current, entry.name);
+      if (entry.isDirectory() || await symlinkedDirectory(child, entry)) {
+        await walk(child);
+      }
+    }
+  }
+
+  await walk(root);
+  const sorted = skills.sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+  return sorted.filter((skill, index) => sorted.findIndex((candidate) => candidate.name === skill.name) === index);
+}
+
+async function symlinkedDirectory(child, entry) {
+  if (!entry.isSymbolicLink()) return false;
+  try {
+    return (await stat(child)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function removeStaleOwnedProjections({ vaultPath, targetPath, desired }) {
+  const entries = await readdir(targetPath, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (desired.has(entry.name)) continue;
+    const fullPath = path.join(targetPath, entry.name);
+    if (await isOwnedSymlink(fullPath, vaultPath) || await isOwnedCopy(fullPath)) {
+      await removePath(fullPath);
+    }
+  }
+}
+
+async function createSymlinkProjection(source, destination) {
+  if (await exists(destination)) {
+    if (await isOwnedSymlink(destination, path.dirname(path.dirname(source))) || await isOwnedCopy(destination)) {
+      await removePath(destination);
+    } else {
+      throw new Error(`Refusing to overwrite unmanaged target path: ${destination}`);
+    }
+  }
+  const relativeSource = path.relative(path.dirname(destination), source);
+  await symlink(relativeSource, destination, 'dir');
+}
+
+async function createCopyProjection(source, destination, skillName, vaultPath) {
+  if (await exists(destination)) {
+    if (await isOwnedCopy(destination) || await isOwnedSymlink(destination, vaultPath)) {
+      await removePath(destination);
+    } else {
+      throw new Error(`Refusing to overwrite unmanaged target path: ${destination}`);
+    }
+  }
+  await cp(source, destination, { recursive: true, force: true, dereference: false });
+  await writeFile(path.join(destination, '.skillsync-owned.json'), JSON.stringify({ skill: skillName, vault: vaultPath }, null, 2));
+}
+
+async function isOwnedSymlink(targetPath, vaultPath) {
+  try {
+    const info = await lstat(targetPath);
+    if (!info.isSymbolicLink()) return false;
+    const linked = await readlink(targetPath);
+    const resolved = path.resolve(path.dirname(targetPath), linked);
+    return resolved.startsWith(path.join(vaultPath, 'skills') + path.sep);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function isOwnedCopy(targetPath) {
+  try {
+    const info = await lstat(path.join(targetPath, '.skillsync-owned.json'));
+    return info.isFile();
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+export async function listDevices(vaultPath) {
+  await mkdir(path.join(vaultPath, 'devices'), { recursive: true });
+  const files = await readdir(path.join(vaultPath, 'devices')).catch(() => []);
+  const devices = [];
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    devices.push(await readJson(path.join(vaultPath, 'devices', file)));
+  }
+  return devices.sort((a, b) => String(a.display_name).localeCompare(String(b.display_name)));
+}

package/src/core/fs.js

@@ -0,0 +1,98 @@
+import { cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export function expandHome(value) {
+  if (!value) return value;
+  if (value === '~') return homedir();
+  if (value.startsWith('~/')) return path.join(homedir(), value.slice(2));
+  return value;
+}
+
+export async function exists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function ensureDir(dirPath) {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function readJson(filePath, fallback = undefined) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' && fallback !== undefined) return fallback;
+    throw error;
+  }
+}
+
+export async function writeJson(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function copyDir(source, destination) {
+  await rm(destination, { recursive: true, force: true });
+  await ensureDir(path.dirname(destination));
+  await cp(source, destination, { recursive: true, force: true, dereference: false });
+}
+
+export async function removePath(targetPath) {
+  await rm(targetPath, { recursive: true, force: true });
+}
+
+export function slugifySkillName(name) {
+  return String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export async function readSkillName(skillDir) {
+  const raw = await readFile(path.join(skillDir, 'SKILL.md'), 'utf8');
+  const frontmatter = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (frontmatter) {
+    const nameLine = frontmatter[1].split(/\r?\n/).find((line) => /^name\s*:/i.test(line));
+    if (nameLine) {
+      const [, value] = nameLine.split(/:(.*)/s);
+      const cleaned = value?.trim().replace(/^['"]|['"]$/g, '');
+      if (cleaned) return slugifySkillName(cleaned);
+    }
+  }
+  return slugifySkillName(path.basename(skillDir));
+}
+
+async function walk(dirPath, root = dirPath) {
+  const entries = await import('node:fs/promises').then(({ readdir }) => readdir(dirPath, { withFileTypes: true }));
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === '.DS_Store') continue;
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walk(fullPath, root));
+    } else if (entry.isFile() || entry.isSymbolicLink()) {
+      files.push(path.relative(root, fullPath));
+    }
+  }
+  return files.sort();
+}
+
+export async function hashDirectory(dirPath) {
+  const hash = createHash('sha256');
+  const files = await walk(dirPath);
+  for (const relativePath of files) {
+    hash.update(relativePath);
+    hash.update('\0');
+    hash.update(await readFile(path.join(dirPath, relativePath)));
+    hash.update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}

package/src/core/git.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+import { exists } from './fs.js';
+import path from 'node:path';
+
+export function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: { ...process.env, ...(options.env || {}) },
+      stdio: options.inherit ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    if (!options.inherit) {
+      child.stdout?.on('data', (chunk) => { stdout += chunk; });
+      child.stderr?.on('data', (chunk) => { stderr += chunk; });
+    }
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve({ stdout, stderr, code });
+      else reject(new Error(`${command} ${args.join(' ')} failed (${code})\n${stderr || stdout}`));
+    });
+  });
+}
+
+export async function commandExists(command) {
+  try {
+    await run('sh', ['-lc', `command -v ${command}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function git(args, cwd, options = {}) {
+  return run('git', args, { cwd, ...options });
+}
+
+export async function gh(args, cwd, options = {}) {
+  return run('gh', args, { cwd, ...options });
+}
+
+export async function isGitRepo(repoPath) {
+  return exists(path.join(repoPath, '.git'));
+}
+
+export async function cloneRepo(repo, repoPath) {
+  if (await isGitRepo(repoPath)) return;
+  await run('git', ['clone', repo, repoPath], { inherit: true });
+}
+
+export async function pullRebase(repoPath) {
+  if (!await isGitRepo(repoPath)) return;
+  await git(['pull', '--rebase', '--autostash'], repoPath);
+}
+
+export async function push(repoPath) {
+  if (!await isGitRepo(repoPath)) return;
+  await git(['push'], repoPath);
+}
+
+export async function statusPorcelain(repoPath) {
+  if (!await isGitRepo(repoPath)) return '';
+  const { stdout } = await git(['status', '--porcelain'], repoPath);
+  return stdout.trim();
+}
+
+export async function commitAllIfChanged(repoPath, message) {
+  if (!await isGitRepo(repoPath)) return false;
+  if (!await statusPorcelain(repoPath)) return false;
+  await git(['add', 'skills', 'devices', 'registry.json', 'README.md'], repoPath);
+  if (!await statusPorcelain(repoPath)) return false;
+  await git(['commit', '-m', message], repoPath);
+  return true;
+}

package/src/core/registry.js

@@ -0,0 +1,132 @@
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { copyDir, ensureDir, exists, hashDirectory, readJson, readSkillName, removePath, writeJson } from './fs.js';
+
+export const REGISTRY_FILE = 'registry.json';
+
+export function emptyRegistry() {
+  return { version: 1, skills: {} };
+}
+
+export async function ensureVault(vaultPath) {
+  await ensureDir(path.join(vaultPath, 'skills'));
+  await ensureDir(path.join(vaultPath, 'devices'));
+  const registryPath = path.join(vaultPath, REGISTRY_FILE);
+  if (!await exists(registryPath)) {
+    await writeJson(registryPath, emptyRegistry());
+  }
+}
+
+export async function loadRegistry(vaultPath) {
+  await ensureVault(vaultPath);
+  const registry = await readJson(path.join(vaultPath, REGISTRY_FILE), emptyRegistry());
+  return normalizeRegistry(registry);
+}
+
+function normalizeRegistry(registry) {
+  return {
+    version: 1,
+    skills: registry?.skills && typeof registry.skills === 'object' ? registry.skills : {},
+  };
+}
+
+export async function saveRegistry(vaultPath, registry) {
+  await ensureVault(vaultPath);
+  await writeJson(path.join(vaultPath, REGISTRY_FILE), normalizeRegistry(registry));
+}
+
+export async function validateSkillFolder(sourcePath) {
+  const skillFile = path.join(sourcePath, 'SKILL.md');
+  try {
+    const info = await stat(skillFile);
+    if (!info.isFile()) throw new Error(`SKILL.md is not a file: ${skillFile}`);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Skill folder must contain SKILL.md: ${sourcePath}`);
+    }
+    throw error;
+  }
+}
+
+export async function addSkillToVault({ vaultPath, sourcePath, name }) {
+  await ensureVault(vaultPath);
+  await validateSkillFolder(sourcePath);
+  const skillName = name || await readSkillName(sourcePath);
+  if (!skillName) throw new Error(`Could not derive a skill name from ${sourcePath}`);
+  const destination = path.join(vaultPath, 'skills', skillName);
+  await copyDir(sourcePath, destination);
+  const registry = await loadRegistry(vaultPath);
+  registry.skills[skillName] = await registryEntryForSkill(vaultPath, skillName);
+  await saveRegistry(vaultPath, registry);
+  return { name: skillName, path: destination };
+}
+
+export async function registryEntryForSkill(vaultPath, skillName) {
+  const skillPath = path.join(vaultPath, 'skills', skillName);
+  await validateSkillFolder(skillPath);
+  return {
+    path: path.posix.join('skills', skillName),
+    hash: await hashDirectory(skillPath),
+    updated_at: new Date().toISOString(),
+  };
+}
+
+export async function rebuildRegistry(vaultPath) {
+  await ensureVault(vaultPath);
+  const skillsDir = path.join(vaultPath, 'skills');
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const registry = emptyRegistry();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillName = entry.name;
+    if (!await exists(path.join(skillsDir, skillName, 'SKILL.md'))) continue;
+    registry.skills[skillName] = await registryEntryForSkill(vaultPath, skillName);
+  }
+  await saveRegistry(vaultPath, registry);
+  return registry;
+}
+
+export async function refreshChangedRegistryEntries(vaultPath) {
+  const before = await loadRegistry(vaultPath);
+  const after = await rebuildRegistry(vaultPath);
+  for (const [name, entry] of Object.entries(after.skills)) {
+    if (before.skills[name]?.hash === entry.hash && before.skills[name]?.updated_at) {
+      after.skills[name].updated_at = before.skills[name].updated_at;
+    }
+  }
+  await saveRegistry(vaultPath, after);
+  return after;
+}
+
+export async function deleteSkillFromVault({ vaultPath, skillName }) {
+  await ensureVault(vaultPath);
+  await removePath(path.join(vaultPath, 'skills', skillName));
+  const registry = await loadRegistry(vaultPath);
+  delete registry.skills[skillName];
+  await saveRegistry(vaultPath, registry);
+
+  const devicesDir = path.join(vaultPath, 'devices');
+  await mkdir(devicesDir, { recursive: true });
+  const devices = await readdir(devicesDir).catch(() => []);
+  for (const file of devices) {
+    if (!file.endsWith('.json')) continue;
+    const filePath = path.join(devicesDir, file);
+    const device = await readJson(filePath, null);
+    if (!device?.installed?.[skillName]) continue;
+    delete device.installed[skillName];
+    await writeJson(filePath, device);
+  }
+}
+
+export async function listSkillFolders(vaultPath) {
+  await ensureVault(vaultPath);
+  const skillsDir = path.join(vaultPath, 'skills');
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+
+export async function resetVault(vaultPath) {
+  await rm(vaultPath, { recursive: true, force: true });
+  await ensureVault(vaultPath);
+}

package/src/core/source.js

@@ -0,0 +1,80 @@
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { exists, readSkillName } from './fs.js';
+import { git } from './git.js';
+
+const OWNER_REPO = /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*(?:#.+)?$/;
+
+export function isRemoteSkillSource(source) {
+  if (!source) return false;
+  return /^(https?:\/\/|git@|ssh:\/\/)/.test(source) || OWNER_REPO.test(source);
+}
+
+export function splitSourceRef(rawSource) {
+  const hashIndex = rawSource.lastIndexOf('#');
+  if (hashIndex === -1) return { source: rawSource, ref: undefined };
+  return {
+    source: rawSource.slice(0, hashIndex),
+    ref: rawSource.slice(hashIndex + 1) || undefined,
+  };
+}
+
+export function cloneUrlForSource(rawSource) {
+  const { source, ref } = splitSourceRef(rawSource);
+  let cloneUrl = source;
+  if (OWNER_REPO.test(source)) cloneUrl = `https://github.com/${source}.git`;
+  return { cloneUrl, ref };
+}
+
+export async function cloneSkillSource(rawSource) {
+  const { cloneUrl, ref } = cloneUrlForSource(rawSource);
+  const dir = await mkdtemp(path.join(tmpdir(), 'skillsync-source-'));
+  const args = ['clone', '--depth', '1'];
+  if (ref) args.push('--branch', ref);
+  args.push(cloneUrl, dir);
+  try {
+    await git(args);
+    return {
+      path: dir,
+      cleanup: () => rm(dir, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+export async function discoverSkillFolders(root, { fullDepth = false } = {}) {
+  const results = [];
+
+  async function walk(dir, relative = '.') {
+    if (await exists(path.join(dir, 'SKILL.md'))) {
+      const name = await readSkillName(dir) || path.basename(dir);
+      results.push({ name, path: dir, relative });
+      if (!fullDepth) return;
+    }
+
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      await walk(path.join(dir, entry.name), relative === '.' ? entry.name : path.posix.join(relative, entry.name));
+    }
+  }
+
+  await walk(root);
+  return results.sort((a, b) => a.name.localeCompare(b.name) || a.relative.localeCompare(b.relative));
+}
+
+export function selectDiscoveredSkills(skills, wantedNames = []) {
+  if (!wantedNames.length) return skills;
+  const wanted = new Set(wantedNames);
+  const selected = skills.filter((skill) => wanted.has(skill.name) || wanted.has(path.basename(skill.path)));
+  const selectedNames = new Set(selected.map((skill) => skill.name));
+  const missing = wantedNames.filter((name) => !selectedNames.has(name) && !selected.some((skill) => path.basename(skill.path) === name));
+  if (missing.length) {
+    throw new Error(`Skill not found in source: ${missing.join(', ')}`);
+  }
+  return selected;
+}

package/src/core/sync.js

@@ -0,0 +1,19 @@
+import { applyLinks, scanTargets, touchDevice } from './device.js';
+import { commitAllIfChanged, isGitRepo, pullRebase, push } from './git.js';
+import { refreshChangedRegistryEntries } from './registry.js';
+
+export async function syncVault({ vaultPath, deviceId, pushChanges = true, pull = true, heartbeat = false } = {}) {
+  if (pull && await isGitRepo(vaultPath)) {
+    await pullRebase(vaultPath);
+  }
+  await refreshChangedRegistryEntries(vaultPath);
+  if (deviceId && heartbeat) await touchDevice({ vaultPath, deviceId });
+  if (deviceId) await applyLinks({ vaultPath, deviceId });
+  if (deviceId) await scanTargets({ vaultPath, deviceId });
+  let committed = false;
+  if (pushChanges && await isGitRepo(vaultPath)) {
+    committed = await commitAllIfChanged(vaultPath, `sync: update skills from ${deviceId || 'device'}`);
+    if (committed) await push(vaultPath);
+  }
+  return { committed };
+}