@akshar5/skillsync 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akshar Patel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,7 +15,7 @@ npm install -g @akshar5/skillsync
 Connect this device to an existing private skills vault:
 
 ```bash
-skillsync setup --repo AksharP5/skills
+skillsync setup --repo OWNER/skills
 ```
 
 Add a local skill folder to the vault:
@@ -43,6 +43,8 @@ Open the interactive UI:
 skillsync
 ```
 
+In the interactive UI, use arrow keys to move, Space to toggle checklist items, Enter to apply, and Esc to go back.
+
 ## Requirements
 
 - Node.js 20 or newer
@@ -86,7 +88,7 @@ npm install -g @akshar5/skillsync
 Connect to an existing vault:
 
 ```bash
-skillsync setup --repo AksharP5/skills
+skillsync setup --repo OWNER/skills
 ```
 
 Or create/select a vault repo interactively:
@@ -97,7 +99,7 @@ skillsync setup
 
 If you run plain `skillsync setup` in an interactive terminal, it first asks which vault type to use:
 
-- Choose `Use an existing GitHub repo`, then enter a repo like `AksharP5/skills`.
+- Choose `Use an existing GitHub repo`, then enter a repo like `OWNER/skills`.
 - Choose `Create or use OWNER/<name>`, then enter a repo name like `skills`.
 
 `setup --name skills` is the non-interactive form of the second option. It creates `OWNER/skills` as a private GitHub repo if it does not exist. If it exists, SkillSync verifies it is private before using it.
@@ -105,7 +107,7 @@ If you run plain `skillsync setup` in an interactive terminal, it first asks whi
 You can also run commands without a global install:
 
 ```bash
-npx @akshar5/skillsync setup --repo AksharP5/skills
+npx @akshar5/skillsync setup --repo OWNER/skills
 npx @akshar5/skillsync add https://github.com/example-org/example-skill --skill example-skill
 ```
 
@@ -113,7 +115,7 @@ If an older SkillSync version failed with `git@github.com: Permission denied (pu
 
 ```bash
 npm install -g @akshar5/skillsync@latest
-skillsync setup --repo AksharP5/skills
+skillsync setup --repo OWNER/skills
 ```
 
 ## Common workflows
@@ -124,6 +126,22 @@ List available skills:
 skillsync list
 ```
 
+Browse and install multiple vault skills at once:
+
+```bash
+skillsync
+```
+
+Choose `Browse/install skills`, press Space to select every skill you want installed on this device, then press Enter to apply the changes.
+
+View skills installed on this device:
+
+```bash
+skillsync installed
+```
+
+In the interactive UI, choose `Installed on this device` to select installed skills, update them from the vault, or uninstall them from the current device.
+
 Check current vault/device state:
 
 ```bash
@@ -170,6 +188,8 @@ Sync the vault and reapply local links:
 skillsync sync
 ```
 
+If an installed skill changes in the vault, `skillsync sync` pulls the vault and reapplies local projections. Symlink targets point at the current vault copy automatically; copy targets are refreshed when links are reapplied.
+
 Scan configured target folders for already-installed local skills:
 
 ```bash
@@ -185,6 +205,7 @@ skillsync setup --name skills
 skillsync
 skillsync status
 skillsync list
+skillsync installed
 skillsync add <skill-folder-or-git-url> --skill <name>
 skillsync add https://github.com/example-org/example-skill --skill example-skill
 skillsync import hermes
@@ -204,6 +225,10 @@ skillsync daemon
 - `skillsync uninstall <skill>` removes the skill from the current device only.
 - `skillsync delete <skill>` removes the skill from the vault and all device manifests.
 
+## Skill names
+
+Skill names are vault-wide identifiers. Installing `my-skill` on two devices means both devices refer to the same vault skill. You can install the same skill on many devices, but you should not use the same name for two different skills in one vault; adding a skill with an existing name updates/replaces that vault entry.
+
 ## Detected versus managed skills
 
 `installed` skills are SkillSync-managed projections into a target folder. `detected` skills are already present in a local agent's skill tree, such as bundled Hermes skills under `~/.hermes/skills`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshar5/skillsync",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Local-first GitHub-backed skill vault sync client for AI agent skills.",
   "type": "module",
   "repository": {
@@ -15,6 +15,7 @@
     "skillsync": "src/cli.js"
   },
   "files": [
+    "LICENSE",
     "src",
     "README.md"
   ],

package/src/cli.js

@@ -34,6 +34,8 @@ async function main() {
       return status();
     case 'list':
       return listSkills();
+    case 'installed':
+      return installedCommand();
     case 'add':
       return addSkill(rest);
     case 'import':
@@ -84,6 +86,30 @@ function hasFlag(rest, flag) {
   return rest.includes(flag);
 }
 
+async function promptWithEscape(promptPromise, escapeValue = null) {
+  if (!process.stdin.isTTY) return promptPromise;
+  const onKeypress = (_value, key) => {
+    if (key?.name === 'escape' && typeof promptPromise.cancel === 'function') {
+      promptPromise.cancel();
+    }
+  };
+  process.stdin.on('keypress', onKeypress);
+  try {
+    return await promptPromise;
+  } catch (error) {
+    if (error?.name === 'CancelPromptError') return escapeValue;
+    throw error;
+  } finally {
+    process.stdin.off('keypress', onKeypress);
+  }
+}
+
+function promptPageSize(itemCount, { min = 8, max = 28, reservedRows = 6 } = {}) {
+  const rows = Number(process.stdout.rows) || 30;
+  const availableRows = Math.max(min, rows - reservedRows);
+  return Math.max(1, Math.min(itemCount, max, availableRows));
+}
+
 async function configured() {
   const config = await loadConfig();
   if (!config.repoPath || !await exists(config.repoPath)) {
@@ -142,13 +168,16 @@ async function setup(rest) {
     if (nameArg || yes || !process.stdin.isTTY) {
       repo = await ensureOwnedVaultRepo(owner, nameArg || 'skills');
     } else {
-      const setupMode = await select({
+      const setupMode = await promptWithEscape(select({
         message: 'Which skills vault do you want to use?',
+        loop: false,
+        pageSize: 2,
         choices: [
           { name: 'Use an existing GitHub repo', value: 'existing' },
           { name: `Create or use ${owner}/<name>`, value: 'owned' },
         ],
-      });
+      }));
+      if (!setupMode) return;
       if (setupMode === 'existing') {
         const existingRepo = await input({ message: 'Existing vault repo (owner/repo or URL):', default: `${owner}/skills` });
         repo = await resolveRepoCloneUrl(existingRepo);
@@ -274,6 +303,37 @@ async function listSkills() {
   }
 }
 
+function installedSkillEntries(device, registry) {
+  return Object.entries(device.installed || {})
+    .map(([name, targets]) => ({
+      name,
+      targets: Array.isArray(targets) ? targets : [],
+      inVault: Boolean(registry.skills[name]),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function installedSkillLabel(skill) {
+  const targetLabel = skill.targets.length ? skill.targets.join(', ') : 'no targets';
+  return `${skill.name}  [${targetLabel}]${skill.inVault ? '' : '  missing from vault'}`;
+}
+
+async function installedCommand() {
+  const config = await configured();
+  await refreshChangedRegistryEntries(config.repoPath);
+  const registry = await loadRegistry(config.repoPath);
+  const device = await loadDevice(config.repoPath, config.deviceId);
+  const installed = installedSkillEntries(device, registry);
+  if (!installed.length) {
+    console.log('No SkillSync-managed skills installed on this device.');
+    return;
+  }
+  console.log(`Installed on ${device.display_name}:`);
+  for (const skill of installed) {
+    console.log(`- ${installedSkillLabel(skill)}`);
+  }
+}
+
 async function addSkill(rest) {
   const source = rest[0];
   if (!source) throw new Error('Usage: skillsync add <skill-folder-or-git-url> [--skill name] [--target target]');
@@ -434,10 +494,13 @@ async function chooseInstallTargets(config, rest) {
   if (hasFlag(rest, '--no-install') || hasFlag(rest, '--yes') || hasFlag(rest, '-y') || !process.stdin.isTTY || !available.length) return [];
   const shouldInstall = await confirm({ message: 'Install on this device now?', default: true });
   if (!shouldInstall) return [];
-  return checkbox({
+  return promptWithEscape(checkbox({
     message: 'Choose local targets',
+    loop: false,
+    pageSize: promptPageSize(available.length, { min: 6, max: 18 }),
     choices: available.map((target) => ({ name: target, value: target, checked: true })),
-  });
+    instructions: 'Space toggles targets. Enter confirms. Esc cancels.',
+  }), []);
 }
 
 async function target(rest) {
@@ -561,21 +624,26 @@ async function runUi() {
 
   while (true) {
     await refreshChangedRegistryEntries(config.repoPath);
-    const choice = await select({
+    const menuChoices = [
+      { name: 'Browse/install skills', value: 'skills', description: 'Select multiple vault skills to install or remove here.' },
+      { name: 'Installed on this device', value: 'installed', description: 'View, update, or uninstall SkillSync-managed local skills.' },
+      { name: 'Devices', value: 'devices', description: 'Show devices known to the vault.' },
+      { name: 'Targets', value: 'targets', description: 'Manage local agent skill folders.' },
+      { name: 'Add skill from folder', value: 'add', description: 'Copy a local SKILL.md folder into the vault.' },
+      { name: 'Import Hermes skills', value: 'import-hermes', description: 'Import detected Hermes skills into the vault.' },
+      { name: 'Scan local targets', value: 'scan', description: 'Refresh detected local skills.' },
+      { name: 'Sync now', value: 'sync', description: 'Pull, link, scan, commit, and push vault changes.' },
+      { name: 'Quit', value: 'quit' },
+    ];
+    const choice = await promptWithEscape(select({
       message: 'SkillSync',
-      choices: [
-        { name: 'Browse/install skills', value: 'skills' },
-        { name: 'Devices', value: 'devices' },
-        { name: 'Targets', value: 'targets' },
-        { name: 'Add skill from folder', value: 'add' },
-        { name: 'Import Hermes skills', value: 'import-hermes' },
-        { name: 'Scan local targets', value: 'scan' },
-        { name: 'Sync now', value: 'sync' },
-        { name: 'Quit', value: 'quit' },
-      ],
-    });
-    if (choice === 'quit') return;
+      loop: false,
+      pageSize: promptPageSize(menuChoices.length, { min: 8, max: 12 }),
+      choices: menuChoices,
+    }));
+    if (!choice || choice === 'quit') return;
     if (choice === 'skills') await skillsScreen(config);
+    if (choice === 'installed') await installedScreen(config);
     if (choice === 'devices') await devicesScreen(config);
     if (choice === 'targets') await targetsScreen(config);
     if (choice === 'add') await addSkill([await input({ message: 'Skill folder path:' })]);
@@ -593,41 +661,121 @@ async function skillsScreen(config) {
     console.log('\nNo skills in vault yet. Use Add/import first.\n');
     return;
   }
-  const skill = await select({
-    message: `Available skills on ${device.display_name}`,
-    choices: names.map((name) => ({
-      name: `${device.installed[name] ? '✓' : '○'} ${name}${device.installed[name] ? ` [${device.installed[name].join(', ')}]` : ''}`,
-      value: name,
-    })).concat([{ name: 'Back', value: null }]),
-  });
-  if (!skill) return;
-  const action = await select({
-    message: skill,
+  const installedNames = new Set(Object.keys(device.installed || {}));
+  const selected = await promptWithEscape(checkbox({
+    message: `Install skills on ${device.display_name}`,
+    loop: false,
+    pageSize: promptPageSize(names.length, { min: 10, max: 32, reservedRows: 5 }),
+    instructions: 'Space toggles skills. Enter applies changes. Esc goes back.',
+    choices: names.map((name) => {
+      const targets = device.installed[name] || [];
+      const targetLabel = targets.length ? `  [${targets.join(', ')}]` : '';
+      return {
+        name: `${name}${targetLabel}`,
+        short: name,
+        value: name,
+        checked: installedNames.has(name),
+      };
+    }),
+  }));
+  if (!selected) return;
+
+  const selectedNames = new Set(selected);
+  const toInstall = names.filter((name) => selectedNames.has(name) && !installedNames.has(name));
+  const toUninstall = names.filter((name) => !selectedNames.has(name) && installedNames.has(name));
+  if (!toInstall.length && !toUninstall.length) {
+    console.log('\nNo install changes.\n');
+    return;
+  }
+
+  let targets = [];
+  if (toInstall.length) {
+    targets = await chooseTargets(config);
+    if (!targets.length) return;
+  }
+
+  for (const skillName of toInstall) {
+    await installSkill({ vaultPath: config.repoPath, deviceId: config.deviceId, skillName, targets });
+  }
+  for (const skillName of toUninstall) {
+    await uninstallSkill({ vaultPath: config.repoPath, deviceId: config.deviceId, skillName });
+  }
+  await applyLinks({ vaultPath: config.repoPath, deviceId: config.deviceId });
+  await syncVault({ vaultPath: config.repoPath, deviceId: config.deviceId, pull: false });
+
+  const installedText = toInstall.length ? `Installed ${toInstall.join(', ')} to ${targets.join(', ')}.` : '';
+  const removedText = toUninstall.length ? `Removed ${toUninstall.join(', ')} from this device.` : '';
+  console.log(`\n${[installedText, removedText].filter(Boolean).join(' ')}\n`);
+}
+
+async function installedScreen(config) {
+  await refreshChangedRegistryEntries(config.repoPath);
+  const registry = await loadRegistry(config.repoPath);
+  const device = await loadDevice(config.repoPath, config.deviceId);
+  const installed = installedSkillEntries(device, registry);
+  if (!installed.length) {
+    console.log('\nNo SkillSync-managed skills installed on this device.\n');
+    return;
+  }
+
+  const selected = await promptWithEscape(checkbox({
+    message: `Installed skills on ${device.display_name}`,
+    loop: false,
+    pageSize: promptPageSize(installed.length, { min: 8, max: 28, reservedRows: 5 }),
+    instructions: 'Space selects skills. Enter chooses an action. Esc goes back.',
+    choices: installed.map((skill) => ({
+      name: installedSkillLabel(skill),
+      short: skill.name,
+      value: skill.name,
+      checked: false,
+    })),
+  }), []);
+  if (!selected.length) return;
+
+  const action = await promptWithEscape(select({
+    message: `Manage ${selected.length} selected skill${selected.length === 1 ? '' : 's'}`,
+    loop: false,
+    pageSize: 3,
     choices: [
-      { name: device.installed[skill] ? 'Remove from this device' : 'Install on this device', value: 'toggle' },
-      { name: 'Delete from vault', value: 'delete' },
+      { name: 'Update from vault', value: 'update', description: 'Pull the vault and reapply local installed links.' },
+      { name: 'Uninstall from this device', value: 'uninstall', description: 'Remove selected skills from this device only.' },
       { name: 'Back', value: 'back' },
     ],
+  }));
+  if (!action || action === 'back') return;
+
+  if (action === 'update') {
+    await syncVault({ vaultPath: config.repoPath, deviceId: config.deviceId, pull: true });
+    console.log(`\nUpdated installed skills from the vault. Requested: ${selected.join(', ')}.\n`);
+    return;
+  }
+
+  const confirmed = await confirm({
+    message: `Uninstall ${selected.join(', ')} from this device?`,
+    default: false,
   });
-  if (action === 'toggle') {
-    if (device.installed[skill]) await uninstall([skill]);
-    else {
-      const targets = await chooseTargets(config);
-      await install([skill, '--target', targets.join(',')]);
-    }
+  if (!confirmed) return;
+
+  for (const skillName of selected) {
+    await uninstallSkill({ vaultPath: config.repoPath, deviceId: config.deviceId, skillName });
   }
-  if (action === 'delete') await deleteSkill([skill]);
+  await applyLinks({ vaultPath: config.repoPath, deviceId: config.deviceId });
+  await syncVault({ vaultPath: config.repoPath, deviceId: config.deviceId, pull: false });
+  console.log(`\nRemoved ${selected.join(', ')} from this device.\n`);
 }
 
 async function chooseTargets(config) {
   const device = await loadDevice(config.repoPath, config.deviceId);
   const targetNames = Object.keys(device.targets);
   if (!targetNames.length) throw new Error('No targets configured. Add one from the Targets screen.');
-  return checkbox({
+  return promptWithEscape(checkbox({
     message: 'Install into which targets?',
+    loop: false,
+    pageSize: promptPageSize(targetNames.length, { min: 6, max: 18 }),
     choices: targetNames.map((name) => ({ name, value: name, checked: true })),
     required: true,
-  });
+    instructions: 'Space toggles targets. Enter confirms. Esc cancels.',
+  }), []);
 }
 
 async function devicesScreen(config) {
@@ -651,8 +799,13 @@ async function targetsScreen(config) {
     { name: 'Add target', value: 'add' },
     { name: 'Back', value: 'back' },
   ]);
-  const choice = await select({ message: 'Targets on this device', choices });
-  if (choice === 'back') return;
+  const choice = await promptWithEscape(select({
+    message: 'Targets on this device',
+    choices,
+    loop: false,
+    pageSize: promptPageSize(choices.length, { min: 6, max: 18 }),
+  }));
+  if (!choice || choice === 'back') return;
   if (choice === 'add') {
     const name = await input({ message: 'Target name (codex, claude, hermes, custom):' });
     const targetPath = await input({ message: 'Target skill directory path:' });
@@ -665,5 +818,5 @@ async function targetsScreen(config) {
 }
 
 function help() {
-  console.log(`SkillSync\n\nUsage:\n  skillsync setup [--name skills] [--repo owner/repo|url]\n  skillsync                 Open TUI\n  skillsync list\n  skillsync add <skill-folder-or-git-url> [--skill name] [--target target]\n  skillsync import hermes\n  skillsync install <skill> [--target codex,claude]\n  skillsync uninstall <skill>\n  skillsync delete <skill>\n  skillsync target add <name> <path> [--mode symlink|copy] [--scan-path path]\n  skillsync scan\n  skillsync sync\n  skillsync service install\n  skillsync daemon\n`);
+  console.log(`SkillSync\n\nUsage:\n  skillsync setup [--name skills] [--repo owner/repo|url]\n  skillsync                 Open TUI\n  skillsync list\n  skillsync installed\n  skillsync add <skill-folder-or-git-url> [--skill name] [--target target]\n  skillsync import hermes\n  skillsync install <skill> [--target codex,claude]\n  skillsync uninstall <skill>\n  skillsync delete <skill>\n  skillsync target add <name> <path> [--mode symlink|copy] [--scan-path path]\n  skillsync scan\n  skillsync sync\n  skillsync service install\n  skillsync daemon\n`);
 }