@yonpark/skillhub-cli 0.1.3 → 0.3.0

package/README.md

@@ -1,185 +1,136 @@
-# SkillHub CLI (Gist Edition)
-
-SkillHub is a small CLI that syncs your local AI agent skills (managed by `npx skills`)
-with a single GitHub Gist. The Gist acts as a free, serverless backup so you can
-recreate your skill setup on any machine.
-
-## Features
-
-- **Login** with a GitHub Personal Access Token (classic) that has `gist` scope
-- **Sync** local skills with a remote Gist:
-  - Push new local skills up to Gist
-  - Pull missing skills down from Gist and install them globally
-  - Simple merge strategies (`union` and `latest`)
-
-## Installation
-
-From the project root:
-
-```bash
-npm install
-npm run build
-npm link        # optional, to get a global `skillhub` command
-```
-
-Alternatively, you can run it without linking:
-
-```bash
-npm run build
-node bin/skillhub.js <command>
-```
-
-If you published this package to npm, you can run it with `npx`:
-
-```bash
-npx @yw9142/skillhub-cli <command>
-```
-
-## Commands
-
-### `skillhub login`
-
-Registers a GitHub token locally so the CLI can talk to the Gist API.
-
-The command will:
-
-1. Prompt for a token:
-   - Create a **Personal Access Token (classic)** in GitHub
-   - Grant at least the **`gist`** scope
-2. Verify that the token is valid and can access Gists
-3. Store the token locally using [`conf`](https://www.npmjs.com/package/conf)
-
-If login fails, the CLI explains that the token is invalid or missing gist
-permissions, and you can paste a new one.
-
-### `skillhub sync`
-
-Synchronizes your local skills with the remote Gist.
-
-```bash
-skillhub sync
-skillhub sync --strategy union
-skillhub sync --strategy latest
-```
-
-#### What “sync” actually does
-
-1. **Read local skills**
-   - Runs `npx skills list -g` and parses the global skills:
-     - For example:
-
-       ```text
-       Global Skills
-
-       vercel-composition-patterns ~\.agents\skills\vercel-composition-patterns
-       vercel-react-best-practices ~\.agents\skills\vercel-react-best-practices
-       ```
-
-   - Falls back to `npx skills generate-lock` + searching for a
-     `skills-lock.json` file when necessary.
-
-2. **Read remote skills (from Gist)**
-   - Looks for a private Gist that contains `skillhub.json`
-   - If not found, creates a new Gist
-
-3. **Merge local vs remote**
-   - **`union` (default)**:
-     - Takes the set union of local and remote skill names
-     - Any skills only on Gist are installed locally
-     - Any skills only on local are written to Gist
-   - **`latest`**:
-     - Compares `updatedAt` timestamps in the payloads
-     - If remote is newer:
-       - Installs skills that are missing locally
-       - Gist is treated as the source of truth
-     - If local is newer (or timestamps are invalid):
-       - Overwrites the Gist with local data
-
-4. **Apply changes**
-   - For skills that exist remotely but not locally, SkillHub runs:
-
-     ```bash
-     npx skills add "<owner>/<repo>" --skill "<skill-name>" -g -y
-     ```
-
-   - For skills that exist locally but not in the Gist, the CLI updates
-     `skillhub.json` in the Gist to reflect the union
-
-5. **Summary output**
-
-After a run you’ll see a short summary like:
-
-```text
-Uploaded 1 change, installed 0 skills
-Uploaded 0 changes, installed 4 skills (1 install failed – check logs)
-```
-
-## Gist Payload
-
-The Gist file `skillhub.json` stores both the skill name and its source repo
-(so you can install skills from repos other than `vercel-labs/agent-skills`):
-
-```json
-{
-  "skills": [
-    { "name": "vercel-composition-patterns", "source": "vercel-labs/agent-skills" },
-    { "name": "my-custom-skill", "source": "yw9142/my-agent-tools" }
-  ],
-  "updatedAt": "2026-01-29T07:27:53.844Z"
-}
-```
-
-- `skills`: list of installed skills + where they came from (`owner/repo`)
-- `updatedAt`: ISO timestamp when the payload was last written
-
-This keeps the format easy to inspect and edit directly in GitHub if needed.
-
-## Typical Workflows
-
-### First machine (create backup)
-
-```bash
-# 1) Install skills using the official CLI
-npx skills add vercel-labs/agent-skills --all -g -y
-
-# 2) Login once
-skillhub login
-
-# 3) Push your current skills to Gist
-skillhub sync
-```
-
-### New machine (restore from backup)
-
-```bash
-# 1) Install and build SkillHub CLI
-npm install
-npm run build
-npm link
-
-# 2) Login with the same GitHub account/token
-skillhub login
-
-# 3) Pull skills from Gist and install missing ones
-skillhub sync
-```
-
-## Notes and Limitations
-
-- Local discovery uses `npx skills list -g` as the primary source. That output
-  usually does **not** include `owner/repo`, so SkillHub may fall back to a
-  default source (`vercel-labs/agent-skills`) unless it can infer a source from
-  `skills-lock.json`.
-- For installs, SkillHub uses the stored `source` per skill:
-
-  ```bash
-  npx skills add "<owner>/<repo>" --skill "<skill-name>" -g -y
-  ```
-
-  If a skill name doesn’t exist in that repo, the install will fail but the
-  overall sync will continue.
-- The CLI currently focuses on **global** skills (`skills list -g`),
-  not project-scoped skills.
-- Error messages try to surface both:
-  - Which step failed (local list / lock file / install / Gist)
-  - The underlying CLI output for easier debugging
+# SkillHub CLI
+
+Sync local AI agent skills (`npx skills`) with a private GitHub Gist.
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Run without linking:
+
+```bash
+node bin/skillhub.js <command>
+```
+
+Published package:
+
+```bash
+npx @yw9142/skillhub-cli <command>
+```
+
+## Commands
+
+### Auth
+
+```bash
+skillhub auth login
+skillhub auth status
+skillhub auth status --json
+skillhub auth logout
+skillhub auth logout --yes
+skillhub auth logout --json
+```
+
+- `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 pull
+skillhub sync push
+skillhub sync merge
+skillhub sync auto
+```
+
+Common options:
+
+```bash
+--dry-run   # compute plan only (no install/remove/upload/config write)
+--json      # single JSON output object
+```
+
+`pull` only:
+
+```bash
+--yes       # skip deletion confirmation prompt
+```
+
+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.
+
+## Migration (Breaking Changes in 0.3.0)
+
+Removed commands:
+
+- `skillhub login`
+- `skillhub status`
+- `skillhub logout`
+- `skillhub sync --strategy ...`
+- `skillhub sync` (without a subcommand)
+
+New mapping:
+
+- `skillhub login` -> `skillhub auth login`
+- `skillhub status` -> `skillhub auth status`
+- `skillhub logout` -> `skillhub auth logout`
+- `skillhub sync --strategy union` -> `skillhub sync merge`
+- `skillhub sync --strategy latest` -> `skillhub sync auto`
+
+## Payload Format
+
+`skillhub.json` in Gist:
+
+```json
+{
+  "skills": [
+    { "name": "vercel-composition-patterns", "source": "vercel-labs/agent-skills" }
+  ],
+  "updatedAt": "2026-01-29T07:27:53.844Z"
+}
+```
+
+Backward compatibility for legacy `skills: string[]` payloads is preserved.
+
+## Local npm Credentials
+
+If you need npm auth, copy `.npmrc.example` to `.npmrc` and keep it local only.
+
+## Release (Changesets)
+
+Create release note:
+
+```bash
+npm run changeset
+```
+
+Version packages:
+
+```bash
+npm run version-packages
+```
+
+Publish:
+
+```bash
+npm run release
+```
+
+CI release workflow publishes to GitHub Packages only:
+
+- 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/logout.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearStoredSession = clearStoredSession;
+exports.runLogout = runLogout;
+const config_1 = require("../service/config");
+const output_1 = require("../utils/output");
+const REMOVED_KEYS = ["githubToken", "gistId", "lastSyncAt"];
+function formatLogoutSummary(summary) {
+    if (!summary.cleared) {
+        return "Logout cancelled.";
+    }
+    return `Logout completed. Removed keys: ${summary.removedKeys.join(", ")}`;
+}
+async function clearStoredSession(store = config_1.configStore) {
+    await store.clearSession();
+    return [...REMOVED_KEYS];
+}
+async function runLogout(options = {}) {
+    const asJson = options.json === true;
+    const force = options.yes === true;
+    if (!force) {
+        const { default: inquirer } = await import("inquirer");
+        const { confirm } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "confirm",
+                default: false,
+                message: "Delete stored GitHub session data (token, gistId, lastSyncAt)?",
+            },
+        ]);
+        if (!confirm) {
+            const cancelled = { cleared: false, removedKeys: [] };
+            (0, output_1.emitOutput)(cancelled, asJson, formatLogoutSummary);
+            return cancelled;
+        }
+    }
+    const removedKeys = await clearStoredSession();
+    const summary = {
+        cleared: true,
+        removedKeys,
+    };
+    (0, output_1.emitOutput)(summary, asJson, formatLogoutSummary);
+    return summary;
+}

package/dist/commands/status.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStatus = runStatus;
+const config_1 = require("../service/config");
+const gistService_1 = require("../service/gistService");
+const skillsService_1 = require("../service/skillsService");
+const output_1 = require("../utils/output");
+function formatStatusSummary(summary) {
+    const lines = [
+        `loggedIn=${summary.loggedIn}`,
+        `gistId=${summary.gistId ?? "none"}`,
+        `lastSyncAt=${summary.lastSyncAt ?? "none"}`,
+        `localSkillCount=${summary.localSkillCount === null ? "unavailable" : String(summary.localSkillCount)}`,
+        `remoteAccessible=${summary.remoteAccessible === null
+            ? "unknown"
+            : String(summary.remoteAccessible)}`,
+    ];
+    if (summary.errors.length > 0) {
+        lines.push(`errors=${summary.errors.length}`);
+        for (const error of summary.errors) {
+            lines.push(`- ${error}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function runStatus(options = {}) {
+    const asJson = options.json === true;
+    const token = await config_1.configStore.getToken();
+    const gistId = await config_1.configStore.getGistId();
+    const lastSyncAt = await config_1.configStore.getLastSyncAt();
+    const summary = {
+        loggedIn: Boolean(token),
+        gistId: gistId ?? null,
+        lastSyncAt: lastSyncAt ?? null,
+        localSkillCount: null,
+        remoteAccessible: token ? null : false,
+        errors: [],
+    };
+    try {
+        const localSkills = await (0, skillsService_1.getLocalSkills)();
+        summary.localSkillCount = localSkills.length;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        summary.errors.push(`Failed to read local skills: ${message}`);
+    }
+    if (token) {
+        try {
+            const octokit = (0, gistService_1.createOctokit)(token);
+            await (0, gistService_1.checkGistAccess)(octokit);
+            summary.remoteAccessible = true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            summary.remoteAccessible = false;
+            summary.errors.push(`Failed to access GitHub Gist API: ${message}`);
+        }
+    }
+    (0, output_1.emitOutput)(summary, asJson, formatStatusSummary);
+    return summary;
+}