@yonpark/skillhub-cli 0.2.0 → 0.3.1

package/README.md

@@ -24,55 +24,51 @@ npx @yw9142/skillhub-cli <command>
 
 ## Commands
 
-### Login
+### Auth
 
 ```bash
-skillhub login
+skillhub auth login
+skillhub auth status
+skillhub auth status --json
+skillhub auth logout
+skillhub auth logout --yes
+skillhub auth logout --json
 ```
 
-- Prompts for a GitHub PAT (classic, `gist` scope)
-- Verifies token + Gist API access
-- Stores token locally via `conf`
+- `auth login`: prompts for a GitHub PAT (classic, `gist` scope), verifies access, and stores it via `conf`
+- `auth status`: shows login state, gist id, last successful sync timestamp, local skill count, and Gist API accessibility
+- `auth logout`: clears stored session keys (`githubToken`, `gistId`, `lastSyncAt`)
 
 ### Sync
 
+`skillhub sync` requires a subcommand.
+
 ```bash
-skillhub sync
-skillhub sync --strategy union
-skillhub sync --strategy latest
-skillhub sync --dry-run
-skillhub sync --json
+skillhub sync pull
+skillhub sync push
+skillhub sync merge
+skillhub sync auto
 ```
 
-- `union`: merge local and remote skills, install missing local skills, upload only when changed
-- `latest`: compare `remote.updatedAt` and local `lastSyncAt`
-- `--dry-run`: compute plan only (no install, no Gist update, no config write)
-- `--json`: single JSON output object
-
-### Status
+Common options:
 
 ```bash
-skillhub status
-skillhub status --json
+--dry-run   # compute plan only (no install/remove/upload/config write)
+--json      # single JSON output object
 ```
 
-Shows:
-
-- login state
-- stored gist id
-- last successful sync timestamp
-- local skill count (if available)
-- remote Gist API accessibility
-
-### Logout
+`pull` only:
 
 ```bash
-skillhub logout
-skillhub logout --yes
-skillhub logout --json
+--yes       # skip deletion confirmation prompt
 ```
 
-Clears stored session keys: `githubToken`, `gistId`, `lastSyncAt`.
+Mode behavior:
+
+- `pull`: mirror remote to local (remote -> local). Installs missing local skills and removes extra local skills.
+- `push`: mirror local to remote (local -> remote). Updates/creates remote Gist payload from local skills.
+- `merge`: union local + remote, installs missing local skills, uploads when remote differs.
+- `auto`: compare `remote.updatedAt` and local `lastSyncAt`; install from remote when remote is newer, otherwise upload local when needed.
 
 ## Payload Format
 
@@ -87,7 +83,7 @@ Clears stored session keys: `githubToken`, `gistId`, `lastSyncAt`.
 }
 ```
 
-Backward compatibility for legacy `skills: string[]` is preserved.
+Backward compatibility for legacy `skills: string[]` payloads is preserved.
 
 ## Local npm Credentials
 
@@ -113,9 +109,11 @@ Publish:
 npm run release
 ```
 
-CI release workflow requires:
+CI release workflow publishes to GitHub Packages only:
 
-- `NPM_TOKEN` repository secret for npmjs publish of `@yonpark/skillhub-cli`.
 - GitHub Packages publish uses `GITHUB_TOKEN` by default.
 - If needed, add `GH_PACKAGES_TOKEN` (PAT with `write:packages`) for GitHub Packages.
 - GitHub Packages target package is `@yw9142/skillhub-cli`.
+
+npmjs publish is manual.
+

package/dist/commands/sync.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runSync = runSync;
+exports.runSyncMerge = runSyncMerge;
+exports.runSyncAuto = runSyncAuto;
+exports.runSyncPush = runSyncPush;
+exports.runSyncPull = runSyncPull;
 const syncCore_1 = require("../core/syncCore");
 const config_1 = require("../service/config");
 const gistService_1 = require("../service/gistService");
@@ -12,11 +15,11 @@ function formatSyncSummary(summary) {
         ? ` (${summary.failed.length} failed - check logs or JSON output)`
         : "";
     const actionLine = summary.dryRun
-        ? `${prefix}: would upload ${summary.uploaded} change(s), would install ${summary.installPlanned} skill(s)`
-        : `${prefix}: uploaded ${summary.uploaded} change(s), installed ${summary.installed} skill(s)`;
+        ? `${prefix} ${summary.mode}: would upload ${summary.uploaded} change(s), would install ${summary.installPlanned} skill(s), would remove ${summary.removePlanned} skill(s)`
+        : `${prefix} ${summary.mode}: uploaded ${summary.uploaded} change(s), installed ${summary.installed} skill(s), removed ${summary.removed} skill(s)`;
     const details = [
         actionLine + failurePart,
-        `strategy=${summary.strategy}`,
+        `mode=${summary.mode}`,
         `gistFound=${summary.gistFound}`,
         `gistCreated=${summary.gistCreated}`,
         `remoteNewer=${summary.remoteNewer === null ? "n/a" : String(summary.remoteNewer)}`,
@@ -24,7 +27,49 @@ function formatSyncSummary(summary) {
     ];
     return details.join("\n");
 }
-async function resolveRemotePayload(token) {
+function createSummary(params) {
+    return {
+        ok: params.failed.length === 0,
+        mode: params.mode,
+        dryRun: params.dryRun,
+        gistFound: params.gistFound,
+        gistCreated: params.gistCreated,
+        remoteNewer: params.remoteNewer,
+        uploaded: params.uploaded,
+        installPlanned: params.installPlanned,
+        installed: params.installed,
+        removePlanned: params.removePlanned,
+        removed: params.removed,
+        failed: params.failed,
+        lastSyncAtUpdated: params.lastSyncAtUpdated,
+    };
+}
+function finalizeWithFailures(summary, asJson) {
+    if (summary.failed.length === 0) {
+        return summary;
+    }
+    if (asJson) {
+        process.exitCode = 1;
+        return summary;
+    }
+    throw new Error(`Sync ${summary.mode} completed with ${summary.failed.length} failed operation(s). Check logs above.`);
+}
+async function ensureToken() {
+    const token = await config_1.configStore.getToken();
+    if (!token) {
+        throw new Error("You must login first. Run `skillhub auth login` and try again.");
+    }
+    return token;
+}
+async function safeGetPayload(octokit, gistId) {
+    try {
+        return await (0, gistService_1.getSkillhubPayload)(octokit, gistId);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveRemoteState(token) {
     const octokit = (0, gistService_1.createOctokit)(token);
     let gistId = await config_1.configStore.getGistId();
     let remotePayload = null;
@@ -45,52 +90,166 @@ async function resolveRemotePayload(token) {
     return {
         octokit,
         gistId,
-        remotePayload: remotePayload ?? { skills: [], updatedAt: "" },
+        gistFound: Boolean(gistId),
+        remotePayload,
     };
 }
-async function safeGetPayload(octokit, gistId) {
-    try {
-        return await (0, gistService_1.getSkillhubPayload)(octokit, gistId);
-    }
-    catch {
-        return null;
-    }
+function asPlanPayload(payload) {
+    return payload ?? { skills: [], updatedAt: "" };
 }
-function createSummaryFromPlan(params) {
+function splitInstallCandidates(candidates) {
+    const invalidInstallCandidates = candidates
+        .filter((skill) => !(0, skillsService_1.isValidSource)(skill.source))
+        .map((skill) => ({
+        skill,
+        reason: `Invalid source "${skill.source}". Expected owner/repo format.`,
+    }));
+    const validInstallCandidates = candidates.filter((skill) => (0, skillsService_1.isValidSource)(skill.source));
     return {
-        ok: params.failed.length === 0,
-        strategy: params.strategy,
-        dryRun: params.dryRun,
-        gistFound: params.gistFound,
-        gistCreated: params.gistCreated,
-        remoteNewer: params.remoteNewer,
-        uploaded: params.uploaded,
-        installPlanned: params.installPlanned,
-        installed: params.installed,
-        failed: params.failed,
-        lastSyncAtUpdated: params.lastSyncAtUpdated,
+        invalidInstallCandidates,
+        validInstallCandidates,
     };
 }
-async function runSync(options = {}) {
-    const strategy = (0, syncCore_1.parseStrategy)(options.strategyInput);
+async function confirmPullRemovalsIfNeeded(removeCandidates, options) {
+    if (removeCandidates.length === 0 || options.yes === true) {
+        return;
+    }
+    const { default: inquirer } = await import("inquirer");
+    const { confirm } = await inquirer.prompt([
+        {
+            type: "confirm",
+            name: "confirm",
+            default: false,
+            message: `Pull sync will remove ${removeCandidates.length} local skill(s). Continue?`,
+        },
+    ]);
+    if (!confirm) {
+        throw new Error("Sync pull cancelled.");
+    }
+}
+async function runSyncMerge(options = {}) {
     const dryRun = options.dryRun === true;
     const asJson = options.json === true;
-    const token = await config_1.configStore.getToken();
-    if (!token) {
-        throw new Error("You must login first. Run `skillhub login` and try again.");
+    const token = await ensureToken();
+    const nowIso = new Date().toISOString();
+    const localSkills = await (0, skillsService_1.getLocalSkills)();
+    const localPayload = {
+        skills: localSkills,
+        updatedAt: nowIso,
+    };
+    const { octokit, gistId, gistFound, remotePayload } = await resolveRemoteState(token);
+    if (!gistFound) {
+        if (dryRun) {
+            const summary = createSummary({
+                mode: "merge",
+                dryRun: true,
+                gistFound: false,
+                gistCreated: false,
+                remoteNewer: null,
+                uploaded: 1,
+                installPlanned: 0,
+                installed: 0,
+                removePlanned: 0,
+                removed: 0,
+                failed: [],
+                lastSyncAtUpdated: false,
+            });
+            (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+            return summary;
+        }
+        const created = await (0, gistService_1.createSkillhubGist)(octokit, localPayload);
+        if (!created.id) {
+            throw new Error("Gist was created, but the ID could not be determined.");
+        }
+        await config_1.configStore.setGistId(created.id);
+        await config_1.configStore.setLastSyncAt(nowIso);
+        const summary = createSummary({
+            mode: "merge",
+            dryRun: false,
+            gistFound: false,
+            gistCreated: true,
+            remoteNewer: null,
+            uploaded: 1,
+            installPlanned: 0,
+            installed: 0,
+            removePlanned: 0,
+            removed: 0,
+            failed: [],
+            lastSyncAtUpdated: true,
+        });
+        (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+        return summary;
     }
+    const plan = (0, syncCore_1.buildMergePlan)({
+        localPayload,
+        remotePayload: asPlanPayload(remotePayload),
+        nowIso,
+    });
+    const { invalidInstallCandidates, validInstallCandidates } = splitInstallCandidates(plan.installCandidates);
+    if (dryRun) {
+        const summary = createSummary({
+            mode: "merge",
+            dryRun: true,
+            gistFound: true,
+            gistCreated: false,
+            remoteNewer: null,
+            uploaded: plan.uploadPayload ? 1 : 0,
+            installPlanned: plan.installCandidates.length,
+            installed: 0,
+            removePlanned: 0,
+            removed: 0,
+            failed: invalidInstallCandidates,
+            lastSyncAtUpdated: false,
+        });
+        (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+        return summary;
+    }
+    const installResult = await (0, skillsService_1.installSkills)(validInstallCandidates, {
+        verbose: !asJson,
+    });
+    const failed = [
+        ...invalidInstallCandidates,
+        ...installResult.failed,
+    ];
+    if (plan.uploadPayload) {
+        await (0, gistService_1.updateSkillhubGist)(octokit, gistId, plan.uploadPayload);
+    }
+    const summary = createSummary({
+        mode: "merge",
+        dryRun: false,
+        gistFound: true,
+        gistCreated: false,
+        remoteNewer: null,
+        uploaded: plan.uploadPayload ? 1 : 0,
+        installPlanned: plan.installCandidates.length,
+        installed: installResult.succeeded.length,
+        removePlanned: 0,
+        removed: 0,
+        failed,
+        lastSyncAtUpdated: false,
+    });
+    if (failed.length === 0) {
+        await config_1.configStore.setLastSyncAt(nowIso);
+        summary.lastSyncAtUpdated = true;
+    }
+    (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+    return finalizeWithFailures(summary, asJson);
+}
+async function runSyncAuto(options = {}) {
+    const dryRun = options.dryRun === true;
+    const asJson = options.json === true;
+    const token = await ensureToken();
     const nowIso = new Date().toISOString();
     const localSkills = await (0, skillsService_1.getLocalSkills)();
     const localPayload = {
         skills: localSkills,
         updatedAt: nowIso,
     };
-    const { octokit, gistId, remotePayload } = await resolveRemotePayload(token);
-    const hasRemoteGist = Boolean(gistId);
-    if (!hasRemoteGist) {
+    const { octokit, gistId, gistFound, remotePayload } = await resolveRemoteState(token);
+    if (!gistFound) {
         if (dryRun) {
-            const summary = createSummaryFromPlan({
-                strategy,
+            const summary = createSummary({
+                mode: "auto",
                 dryRun: true,
                 gistFound: false,
                 gistCreated: false,
@@ -98,6 +257,8 @@ async function runSync(options = {}) {
                 uploaded: 1,
                 installPlanned: 0,
                 installed: 0,
+                removePlanned: 0,
+                removed: 0,
                 failed: [],
                 lastSyncAtUpdated: false,
             });
@@ -110,8 +271,8 @@ async function runSync(options = {}) {
         }
         await config_1.configStore.setGistId(created.id);
         await config_1.configStore.setLastSyncAt(nowIso);
-        const summary = createSummaryFromPlan({
-            strategy,
+        const summary = createSummary({
+            mode: "auto",
             dryRun: false,
             gistFound: false,
             gistCreated: true,
@@ -119,6 +280,8 @@ async function runSync(options = {}) {
             uploaded: 1,
             installPlanned: 0,
             installed: 0,
+            removePlanned: 0,
+            removed: 0,
             failed: [],
             lastSyncAtUpdated: true,
         });
@@ -126,30 +289,25 @@ async function runSync(options = {}) {
         return summary;
     }
     const lastSyncAt = await config_1.configStore.getLastSyncAt();
-    const plan = (0, syncCore_1.buildSyncPlan)({
-        strategy,
+    const plan = (0, syncCore_1.buildAutoPlan)({
         localPayload,
-        remotePayload,
+        remotePayload: asPlanPayload(remotePayload),
         lastSyncAt,
         nowIso,
     });
-    const invalidInstallCandidates = plan.installCandidates
-        .filter((skill) => !(0, skillsService_1.isValidSource)(skill.source))
-        .map((skill) => ({
-        skill,
-        reason: `Invalid source "${skill.source}". Expected owner/repo format.`,
-    }));
-    const validInstallCandidates = plan.installCandidates.filter((skill) => (0, skillsService_1.isValidSource)(skill.source));
+    const { invalidInstallCandidates, validInstallCandidates } = splitInstallCandidates(plan.installCandidates);
     if (dryRun) {
-        const summary = createSummaryFromPlan({
-            strategy,
+        const summary = createSummary({
+            mode: "auto",
             dryRun: true,
             gistFound: true,
             gistCreated: false,
-            remoteNewer: strategy === "latest" ? plan.isRemoteNewer : null,
+            remoteNewer: plan.isRemoteNewer,
             uploaded: plan.uploadPayload ? 1 : 0,
             installPlanned: plan.installCandidates.length,
             installed: 0,
+            removePlanned: 0,
+            removed: 0,
             failed: invalidInstallCandidates,
             lastSyncAtUpdated: false,
         });
@@ -159,19 +317,24 @@ async function runSync(options = {}) {
     const installResult = await (0, skillsService_1.installSkills)(validInstallCandidates, {
         verbose: !asJson,
     });
-    const failed = [...invalidInstallCandidates, ...installResult.failed];
+    const failed = [
+        ...invalidInstallCandidates,
+        ...installResult.failed,
+    ];
     if (plan.uploadPayload) {
         await (0, gistService_1.updateSkillhubGist)(octokit, gistId, plan.uploadPayload);
     }
-    const summary = createSummaryFromPlan({
-        strategy,
+    const summary = createSummary({
+        mode: "auto",
         dryRun: false,
         gistFound: true,
         gistCreated: false,
-        remoteNewer: strategy === "latest" ? plan.isRemoteNewer : null,
+        remoteNewer: plan.isRemoteNewer,
         uploaded: plan.uploadPayload ? 1 : 0,
         installPlanned: plan.installCandidates.length,
         installed: installResult.succeeded.length,
+        removePlanned: 0,
+        removed: 0,
         failed,
         lastSyncAtUpdated: false,
     });
@@ -180,12 +343,175 @@ async function runSync(options = {}) {
         summary.lastSyncAtUpdated = true;
     }
     (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
-    if (failed.length > 0) {
-        if (asJson) {
-            process.exitCode = 1;
+    return finalizeWithFailures(summary, asJson);
+}
+async function runSyncPush(options = {}) {
+    const dryRun = options.dryRun === true;
+    const asJson = options.json === true;
+    const token = await ensureToken();
+    const nowIso = new Date().toISOString();
+    const localSkills = await (0, skillsService_1.getLocalSkills)();
+    const localPayload = {
+        skills: localSkills,
+        updatedAt: nowIso,
+    };
+    const { octokit, gistId, gistFound, remotePayload } = await resolveRemoteState(token);
+    if (!gistFound) {
+        if (dryRun) {
+            const summary = createSummary({
+                mode: "push",
+                dryRun: true,
+                gistFound: false,
+                gistCreated: false,
+                remoteNewer: null,
+                uploaded: 1,
+                installPlanned: 0,
+                installed: 0,
+                removePlanned: 0,
+                removed: 0,
+                failed: [],
+                lastSyncAtUpdated: false,
+            });
+            (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
             return summary;
         }
-        throw new Error(`Sync completed with ${failed.length} failed install(s). Check logs above.`);
+        const created = await (0, gistService_1.createSkillhubGist)(octokit, localPayload);
+        if (!created.id) {
+            throw new Error("Gist was created, but the ID could not be determined.");
+        }
+        await config_1.configStore.setGistId(created.id);
+        await config_1.configStore.setLastSyncAt(nowIso);
+        const summary = createSummary({
+            mode: "push",
+            dryRun: false,
+            gistFound: false,
+            gistCreated: true,
+            remoteNewer: null,
+            uploaded: 1,
+            installPlanned: 0,
+            installed: 0,
+            removePlanned: 0,
+            removed: 0,
+            failed: [],
+            lastSyncAtUpdated: true,
+        });
+        (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+        return summary;
     }
+    const plan = (0, syncCore_1.buildPushPlan)({
+        localPayload,
+        remotePayload: asPlanPayload(remotePayload),
+        nowIso,
+    });
+    if (dryRun) {
+        const summary = createSummary({
+            mode: "push",
+            dryRun: true,
+            gistFound: true,
+            gistCreated: false,
+            remoteNewer: null,
+            uploaded: plan.uploadPayload ? 1 : 0,
+            installPlanned: 0,
+            installed: 0,
+            removePlanned: 0,
+            removed: 0,
+            failed: [],
+            lastSyncAtUpdated: false,
+        });
+        (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+        return summary;
+    }
+    if (plan.uploadPayload) {
+        await (0, gistService_1.updateSkillhubGist)(octokit, gistId, plan.uploadPayload);
+    }
+    await config_1.configStore.setLastSyncAt(nowIso);
+    const summary = createSummary({
+        mode: "push",
+        dryRun: false,
+        gistFound: true,
+        gistCreated: false,
+        remoteNewer: null,
+        uploaded: plan.uploadPayload ? 1 : 0,
+        installPlanned: 0,
+        installed: 0,
+        removePlanned: 0,
+        removed: 0,
+        failed: [],
+        lastSyncAtUpdated: true,
+    });
+    (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
     return summary;
 }
+async function runSyncPull(options = {}) {
+    const dryRun = options.dryRun === true;
+    const asJson = options.json === true;
+    const token = await ensureToken();
+    const nowIso = new Date().toISOString();
+    const localSkills = await (0, skillsService_1.getLocalSkills)();
+    const localPayload = {
+        skills: localSkills,
+        updatedAt: nowIso,
+    };
+    const { gistFound, remotePayload } = await resolveRemoteState(token);
+    if (!gistFound) {
+        throw new Error("Remote SkillHub Gist not found. Run `skillhub sync push` to create it first.");
+    }
+    if (!remotePayload) {
+        throw new Error("Remote SkillHub payload is missing or invalid. Fix the remote `skillhub.json` and retry.");
+    }
+    const plan = (0, syncCore_1.buildPullPlan)({
+        localPayload,
+        remotePayload,
+    });
+    const { invalidInstallCandidates, validInstallCandidates } = splitInstallCandidates(plan.installCandidates);
+    if (dryRun) {
+        const summary = createSummary({
+            mode: "pull",
+            dryRun: true,
+            gistFound: true,
+            gistCreated: false,
+            remoteNewer: null,
+            uploaded: 0,
+            installPlanned: plan.installCandidates.length,
+            installed: 0,
+            removePlanned: plan.removeCandidates.length,
+            removed: 0,
+            failed: invalidInstallCandidates,
+            lastSyncAtUpdated: false,
+        });
+        (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+        return summary;
+    }
+    await confirmPullRemovalsIfNeeded(plan.removeCandidates, options);
+    const installResult = await (0, skillsService_1.installSkills)(validInstallCandidates, {
+        verbose: !asJson,
+    });
+    const removeResult = await (0, skillsService_1.removeSkills)(plan.removeCandidates, {
+        verbose: !asJson,
+    });
+    const failed = [
+        ...invalidInstallCandidates,
+        ...installResult.failed,
+        ...removeResult.failed,
+    ];
+    const summary = createSummary({
+        mode: "pull",
+        dryRun: false,
+        gistFound: true,
+        gistCreated: false,
+        remoteNewer: null,
+        uploaded: 0,
+        installPlanned: plan.installCandidates.length,
+        installed: installResult.succeeded.length,
+        removePlanned: plan.removeCandidates.length,
+        removed: removeResult.succeeded.length,
+        failed,
+        lastSyncAtUpdated: false,
+    });
+    if (failed.length === 0) {
+        await config_1.configStore.setLastSyncAt(nowIso);
+        summary.lastSyncAtUpdated = true;
+    }
+    (0, output_1.emitOutput)(summary, asJson, formatSyncSummary);
+    return finalizeWithFailures(summary, asJson);
+}

package/dist/core/syncCore.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseStrategy = parseStrategy;
 exports.parseTimestamp = parseTimestamp;
 exports.normalizeSkills = normalizeSkills;
 exports.uniqueSortedSkills = uniqueSortedSkills;
 exports.areSameSkills = areSameSkills;
-exports.buildSyncPlan = buildSyncPlan;
+exports.buildMergePlan = buildMergePlan;
+exports.buildAutoPlan = buildAutoPlan;
+exports.buildPullPlan = buildPullPlan;
+exports.buildPushPlan = buildPushPlan;
 const DEFAULT_SKILL_SOURCE_REPO = "vercel-labs/agent-skills";
 const BANNED_SKILL_NAME_SUBSTRINGS = [
     "No global skills found",
@@ -13,15 +15,6 @@ const BANNED_SKILL_NAME_SUBSTRINGS = [
     "No project skills found",
     "Try listing global skills",
 ];
-function parseStrategy(input) {
-    if (!input) {
-        return "union";
-    }
-    if (input === "union" || input === "latest") {
-        return input;
-    }
-    throw new Error(`Invalid strategy "${input}". Use one of: union, latest.`);
-}
 function parseTimestamp(value) {
     if (!value) {
         return null;
@@ -70,34 +63,35 @@ function areSameSkills(left, right) {
     return leftSorted.every((skill, index) => skill.name === rightSorted[index].name &&
         skill.source === rightSorted[index].source);
 }
-function buildSyncPlan(params) {
+function buildMergePlan(params) {
     const localSkills = normalizeSkills(params.localPayload.skills);
     const remoteSkills = normalizeSkills(params.remotePayload.skills);
-    if (params.strategy === "union") {
-        const unionSkills = uniqueSortedSkills([...localSkills, ...remoteSkills]);
-        const installCandidates = unionSkills.filter((skill) => !localSkills.some((local) => local.name === skill.name && local.source === skill.source));
-        const uploadPayload = areSameSkills(remoteSkills, unionSkills)
-            ? null
-            : {
-                skills: unionSkills,
-                updatedAt: params.nowIso,
-            };
-        return {
-            strategy: "union",
-            localSkills,
-            remoteSkills,
-            installCandidates,
-            uploadPayload,
-            isRemoteNewer: false,
+    const unionSkills = uniqueSortedSkills([...localSkills, ...remoteSkills]);
+    const installCandidates = unionSkills.filter((skill) => !localSkills.some((local) => local.name === skill.name && local.source === skill.source));
+    const uploadPayload = areSameSkills(remoteSkills, unionSkills)
+        ? null
+        : {
+            skills: unionSkills,
+            updatedAt: params.nowIso,
         };
-    }
+    return {
+        mode: "merge",
+        localSkills,
+        remoteSkills,
+        installCandidates,
+        uploadPayload,
+    };
+}
+function buildAutoPlan(params) {
+    const localSkills = normalizeSkills(params.localPayload.skills);
+    const remoteSkills = normalizeSkills(params.remotePayload.skills);
     const lastSyncTime = parseTimestamp(params.lastSyncAt) ?? 0;
     const remoteTime = parseTimestamp(params.remotePayload.updatedAt);
     const isRemoteNewer = remoteTime !== null && remoteTime > lastSyncTime;
     if (isRemoteNewer) {
         const installCandidates = remoteSkills.filter((skill) => !localSkills.some((local) => local.name === skill.name && local.source === skill.source));
         return {
-            strategy: "latest",
+            mode: "auto",
             localSkills,
             remoteSkills,
             installCandidates,
@@ -112,7 +106,7 @@ function buildSyncPlan(params) {
             updatedAt: params.nowIso,
         };
     return {
-        strategy: "latest",
+        mode: "auto",
         localSkills,
         remoteSkills,
         installCandidates: [],
@@ -120,3 +114,32 @@ function buildSyncPlan(params) {
         isRemoteNewer,
     };
 }
+function buildPullPlan(params) {
+    const localSkills = normalizeSkills(params.localPayload.skills);
+    const remoteSkills = normalizeSkills(params.remotePayload.skills);
+    const installCandidates = remoteSkills.filter((remote) => !localSkills.some((local) => local.name === remote.name && local.source === remote.source));
+    const removeCandidates = localSkills.filter((local) => !remoteSkills.some((remote) => remote.name === local.name && remote.source === local.source));
+    return {
+        mode: "pull",
+        localSkills,
+        remoteSkills,
+        installCandidates,
+        removeCandidates,
+    };
+}
+function buildPushPlan(params) {
+    const localSkills = normalizeSkills(params.localPayload.skills);
+    const remoteSkills = normalizeSkills(params.remotePayload.skills);
+    const uploadPayload = areSameSkills(localSkills, remoteSkills)
+        ? null
+        : {
+            skills: localSkills,
+            updatedAt: params.nowIso,
+        };
+    return {
+        mode: "push",
+        localSkills,
+        remoteSkills,
+        uploadPayload,
+    };
+}

package/dist/index.js

@@ -17,80 +17,100 @@ function getPackageVersion() {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function withJsonErrorHandling(action) {
+    return async (options) => {
+        try {
+            await action(options);
+        }
+        catch (error) {
+            if (options.json) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    error: errorMessage(error),
+                }, null, 2));
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+    };
+}
 const program = new commander_1.Command();
 program.name("skillhub").description("SkillHub CLI").version(getPackageVersion());
-program
+const authCommand = program.command("auth").description("Authentication commands");
+authCommand
     .command("login")
-    .description("Login: register your GitHub PAT with gist access")
+    .description("Register your GitHub PAT with gist access")
     .action(async () => {
     await (0, login_1.runLogin)();
 });
-program
-    .command("sync")
-    .description("Sync: reconcile local skills with remote Gist backup")
-    .option("-s, --strategy <strategy>", "merge strategy (union|latest)", "union")
-    .option("--dry-run", "show planned changes without applying them", false)
-    .option("--json", "print output as JSON", false)
-    .action(async (options) => {
-    try {
-        await (0, sync_1.runSync)({
-            strategyInput: options.strategy,
-            dryRun: options.dryRun,
-            json: options.json,
-        });
-    }
-    catch (error) {
-        if (options.json) {
-            console.log(JSON.stringify({
-                ok: false,
-                error: errorMessage(error),
-            }, null, 2));
-            process.exitCode = 1;
-            return;
-        }
-        throw error;
-    }
-});
-program
+authCommand
     .command("status")
     .description("Show local auth/sync status")
     .option("--json", "print output as JSON", false)
-    .action(async (options) => {
-    try {
-        await (0, status_1.runStatus)({ json: options.json });
-    }
-    catch (error) {
-        if (options.json) {
-            console.log(JSON.stringify({
-                ok: false,
-                error: errorMessage(error),
-            }, null, 2));
-            process.exitCode = 1;
-            return;
-        }
-        throw error;
-    }
-});
-program
+    .action(withJsonErrorHandling(async (options) => {
+    await (0, status_1.runStatus)({ json: options.json });
+}));
+authCommand
     .command("logout")
     .description("Clear stored session data (token, gist id, last sync)")
     .option("--yes", "skip confirmation prompt", false)
     .option("--json", "print output as JSON", false)
-    .action(async (options) => {
-    try {
-        await (0, logout_1.runLogout)({ yes: options.yes, json: options.json });
-    }
-    catch (error) {
-        if (options.json) {
-            console.log(JSON.stringify({
-                ok: false,
-                error: errorMessage(error),
-            }, null, 2));
-            process.exitCode = 1;
-            return;
-        }
-        throw error;
-    }
+    .action(withJsonErrorHandling(async (options) => {
+    await (0, logout_1.runLogout)({ yes: options.yes, json: options.json });
+}));
+const syncCommand = program
+    .command("sync")
+    .description("Sync local skills and remote Gist backup");
+syncCommand
+    .command("pull")
+    .description("Mirror remote skills into local skills (remote -> local)")
+    .option("--dry-run", "show planned changes without applying them", false)
+    .option("--yes", "skip deletion confirmation prompt", false)
+    .option("--json", "print output as JSON", false)
+    .action(withJsonErrorHandling(async (options) => {
+    await (0, sync_1.runSyncPull)({
+        dryRun: options.dryRun,
+        yes: options.yes,
+        json: options.json,
+    });
+}));
+syncCommand
+    .command("push")
+    .description("Mirror local skills into remote backup (local -> remote)")
+    .option("--dry-run", "show planned changes without applying them", false)
+    .option("--json", "print output as JSON", false)
+    .action(withJsonErrorHandling(async (options) => {
+    await (0, sync_1.runSyncPush)({
+        dryRun: options.dryRun,
+        json: options.json,
+    });
+}));
+syncCommand
+    .command("merge")
+    .description("Merge local and remote skills (union behavior)")
+    .option("--dry-run", "show planned changes without applying them", false)
+    .option("--json", "print output as JSON", false)
+    .action(withJsonErrorHandling(async (options) => {
+    await (0, sync_1.runSyncMerge)({
+        dryRun: options.dryRun,
+        json: options.json,
+    });
+}));
+syncCommand
+    .command("auto")
+    .description("Sync using remote.updatedAt and lastSyncAt comparison")
+    .option("--dry-run", "show planned changes without applying them", false)
+    .option("--json", "print output as JSON", false)
+    .action(withJsonErrorHandling(async (options) => {
+    await (0, sync_1.runSyncAuto)({
+        dryRun: options.dryRun,
+        json: options.json,
+    });
+}));
+syncCommand.action(() => {
+    syncCommand.outputHelp();
+    throw new Error("Missing sync mode. Use one of: pull, push, merge, auto.");
 });
 program.parseAsync(process.argv).catch((error) => {
     console.error(`Error: ${errorMessage(error)}`);

package/dist/service/skillsService.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValidSource = isValidSource;
 exports.getLocalSkills = getLocalSkills;
 exports.installSkills = installSkills;
+exports.removeSkills = removeSkills;
 const node_child_process_1 = require("node:child_process");
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -14,7 +15,7 @@ const node_util_1 = require("node:util");
 const syncCore_1 = require("../core/syncCore");
 const retry_1 = require("../utils/retry");
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
-const SKILLS_LOCK_FILENAME = "skills-lock.json";
+const SKILLS_LOCK_FILENAMES = ["skills-lock.json", ".skill-lock.json"];
 const DEFAULT_SKILL_SOURCE_REPO = "vercel-labs/agent-skills";
 const NPX_COMMAND = process.platform === "win32" ? "npx.cmd" : "npx";
 const SOURCE_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
@@ -35,26 +36,31 @@ async function runSkillsCommand(args, label) {
 function isValidSource(source) {
     return SOURCE_PATTERN.test(source);
 }
-function getCandidateSkillsLockPaths() {
-    const cwdPath = node_path_1.default.resolve(process.cwd(), SKILLS_LOCK_FILENAME);
-    const homePath = node_path_1.default.resolve(node_os_1.default.homedir(), SKILLS_LOCK_FILENAME);
+function getCandidateSkillsLockPaths(filename) {
+    const cwdPath = node_path_1.default.resolve(process.cwd(), filename);
+    const homePath = node_path_1.default.resolve(node_os_1.default.homedir(), filename);
     const homeConfigPaths = [
-        node_path_1.default.resolve(node_os_1.default.homedir(), ".config", "skills", SKILLS_LOCK_FILENAME),
-        node_path_1.default.resolve(node_os_1.default.homedir(), ".config", "skillhub", SKILLS_LOCK_FILENAME),
-        node_path_1.default.resolve(node_os_1.default.homedir(), ".skills", SKILLS_LOCK_FILENAME),
+        node_path_1.default.resolve(node_os_1.default.homedir(), ".config", "skills", filename),
+        node_path_1.default.resolve(node_os_1.default.homedir(), ".config", "skillhub", filename),
+        node_path_1.default.resolve(node_os_1.default.homedir(), ".skills", filename),
+        node_path_1.default.resolve(node_os_1.default.homedir(), ".agents", filename),
     ];
     const winAppData = process.env.APPDATA;
     const winLocalAppData = process.env.LOCALAPPDATA;
     const windowsConfigPaths = [
         ...(winAppData
-            ? [node_path_1.default.resolve(winAppData, "skills", SKILLS_LOCK_FILENAME)]
+            ? [node_path_1.default.resolve(winAppData, "skills", filename)]
             : []),
         ...(winLocalAppData
-            ? [node_path_1.default.resolve(winLocalAppData, "skills", SKILLS_LOCK_FILENAME)]
+            ? [node_path_1.default.resolve(winLocalAppData, "skills", filename)]
             : []),
     ];
     return [cwdPath, homePath, ...homeConfigPaths, ...windowsConfigPaths];
 }
+function getAllCandidateSkillsLockPaths() {
+    const paths = SKILLS_LOCK_FILENAMES.flatMap((filename) => getCandidateSkillsLockPaths(filename));
+    return [...new Set(paths)];
+}
 function parseSkillsLock(raw) {
     const parsed = JSON.parse(raw);
     const extractSkills = (items) => {
@@ -82,6 +88,21 @@ function parseSkillsLock(raw) {
     if (Array.isArray(parsed?.skills)) {
         return extractSkills(parsed.skills);
     }
+    if (parsed?.skills && typeof parsed.skills === "object") {
+        const objectSkills = parsed.skills;
+        return Object.entries(objectSkills).map(([name, metadata]) => {
+            if (typeof metadata === "object" && metadata !== null) {
+                const objectItem = metadata;
+                const source = typeof objectItem.source === "string"
+                    ? objectItem.source
+                    : typeof objectItem.repo === "string"
+                        ? objectItem.repo
+                        : DEFAULT_SKILL_SOURCE_REPO;
+                return { name, source };
+            }
+            return { name, source: DEFAULT_SKILL_SOURCE_REPO };
+        });
+    }
     if (Array.isArray(parsed)) {
         return extractSkills(parsed);
     }
@@ -127,6 +148,45 @@ async function tryReadSkillsLock(lockPath) {
         return null;
     }
 }
+async function readFirstAvailableSkillsLock() {
+    const candidatePaths = getAllCandidateSkillsLockPaths();
+    for (const lockPath of candidatePaths) {
+        const parsed = await tryReadSkillsLock(lockPath);
+        if (parsed && parsed.length > 0) {
+            return {
+                skills: (0, syncCore_1.normalizeSkills)(parsed),
+                candidatePaths,
+            };
+        }
+    }
+    return {
+        skills: [],
+        candidatePaths,
+    };
+}
+function hydrateSourcesFromLock(listSkills, lockSkills) {
+    const lockByName = new Map();
+    for (const skill of lockSkills) {
+        const existing = lockByName.get(skill.name);
+        if (existing) {
+            existing.push(skill);
+            continue;
+        }
+        lockByName.set(skill.name, [skill]);
+    }
+    const hydrated = listSkills.map((skill) => {
+        const matches = lockByName.get(skill.name);
+        if (!matches || matches.length === 0) {
+            return skill;
+        }
+        const preferred = matches.find((item) => isValidSource(item.source)) ?? matches[0];
+        return {
+            name: skill.name,
+            source: preferred.source,
+        };
+    });
+    return (0, syncCore_1.normalizeSkills)(hydrated);
+}
 async function getLocalSkills() {
     const listResult = await runSkillsCommand(["list", "-g"], "skills list -g");
     const listOutput = stringifyCommandResult(listResult);
@@ -135,32 +195,23 @@ async function getLocalSkills() {
         return [];
     }
     const fromList = parseSkillsListOutput(listOutput);
+    const fromLock = await readFirstAvailableSkillsLock();
     if (fromList.length > 0) {
-        return fromList;
-    }
-    const lockResult = await runSkillsCommand(["generate-lock"], "skills generate-lock");
-    const lockOutput = stringifyCommandResult(lockResult);
-    const candidatePaths = getCandidateSkillsLockPaths();
-    for (const lockPath of candidatePaths) {
-        const parsed = await tryReadSkillsLock(lockPath);
-        if (parsed) {
-            return (0, syncCore_1.normalizeSkills)(parsed);
+        if (fromLock.skills.length > 0) {
+            return hydrateSourcesFromLock(fromList, fromLock.skills);
         }
+        return fromList;
     }
-    if (lockOutput.includes("No installed skills found") ||
-        listOutput.includes("No project skills found")) {
-        return [];
+    if (fromLock.skills.length > 0) {
+        return fromLock.skills;
     }
     throw new Error([
         "Unable to construct local skills list.",
         "- skills list -g output:",
         listOutput,
         "",
-        `- Searched ${SKILLS_LOCK_FILENAME} paths:`,
-        ...candidatePaths.map((p) => `  - ${p}`),
-        "",
-        "- npx skills generate-lock output:",
-        lockOutput,
+        "- Searched lock paths:",
+        ...fromLock.candidatePaths.map((p) => `  - ${p}`),
     ].join("\n"));
 }
 async function installSkills(skills, options = {}) {
@@ -195,3 +246,32 @@ async function installSkills(skills, options = {}) {
     }
     return { succeeded, failed };
 }
+async function removeSkills(skills, options = {}) {
+    const succeeded = [];
+    const failed = [];
+    const seen = new Set();
+    for (const skill of skills) {
+        const key = `${skill.source}:${skill.name}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        try {
+            const result = await runSkillsCommand(["remove", "--skill", skill.name, "--global", "--yes"], `skills remove --skill ${skill.name}`);
+            const output = stringifyCommandResult(result);
+            if (options.verbose && output) {
+                console.log(output);
+            }
+            succeeded.push(skill);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            failed.push({ skill, reason });
+            if (options.verbose) {
+                console.warn(`Skill remove failed: ${skill.name} (from ${skill.source})`);
+                console.warn(`  - ${reason}`);
+            }
+        }
+    }
+    return { succeeded, failed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yonpark/skillhub-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "SkillHub CLI - sync skills with GitHub Gist",
   "bin": {
     "skillhub": "bin/skillhub.js"