@khanhcan148/mk 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -21,7 +21,8 @@
   "dependencies": {
     "chalk": "^5.0.0",
     "commander": "^12.0.0",
-    "fs-extra": "^11.0.0"
+    "fs-extra": "^11.0.0",
+    "semver": "^7.0.0"
   },
   "keywords": [
     "claude",

package/src/commands/update.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
+import { createInterface } from 'node:readline';
 import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync } from 'node:fs';
-import { join, dirname, resolve, sep } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
@@ -9,6 +10,28 @@ import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePat
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';
 import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
+import { fetchLatestRelease, compareVersions } from '../lib/releases.js';
+
+// ---------------------------------------------------------------------------
+// Prompt helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Prompt the user with a yes/no question and return true for yes, false for no.
+ * Reads from stdin; defaults to "no" on empty/non-y input.
+ *
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+async function defaultPromptUser(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
 
 /**
  * Run the update command.
@@ -151,7 +174,9 @@ export async function runUpdate(params = {}) {
 
 /**
  * CLI action handler for 'mk update'.
- * Downloads fresh kit from GitHub and applies three-way diff.
+ * Checks GitHub Releases for a newer version, prompts the user, then downloads
+ * and applies a three-way diff. Falls back to the main-branch tarball if no
+ * release information is available.
  *
  * @param {{ force: boolean, global: boolean }} options
  * @param {object} [deps] - Injected dependencies (for testing)
@@ -162,9 +187,17 @@ export async function updateAction(options = {}, deps = {}) {
     downloadAndExtractKit: download = downloadAndExtractKit,
     cleanupTempDir: cleanup = cleanupTempDir,
     writeToken: storeToken = writeToken,
-    readStoredToken: readToken = readStoredToken
+    readStoredToken: readToken = readStoredToken,
+    fetchLatestRelease: fetchRelease = fetchLatestRelease,
+    compareVersions: cmpVersions = compareVersions,
+    promptUser = defaultPromptUser
   } = deps;
 
+  // Read local package version for comparison
+  const pkg = JSON.parse(
+    readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')
+  );
+
   const targetDir = resolveTargetDir(options);
   const manifestPath = resolveManifestPath(options);
 
@@ -183,8 +216,51 @@ export async function updateAction(options = {}, deps = {}) {
       }
     });
 
+    // --- Version check via GitHub Releases API ---
+    process.stdout.write('Checking for updates...\n');
+    const release = await fetchRelease(token);
+
+    let downloadUrl; // undefined = use default (main branch)
+
+    if (!release.available) {
+      // No release found or API error — warn and fall back to main branch
+      process.stdout.write(
+        chalk.yellow(`Warning: Could not check latest release (${release.reason}). Falling back to main branch.\n`)
+      );
+    } else {
+      const { needsUpdate, local, remote } = cmpVersions(pkg.version, release.version);
+
+      if (!needsUpdate) {
+        process.stdout.write(chalk.green(`Already up to date (v${local}).\n`));
+        return;
+      }
+
+      // Show version diff
+      process.stdout.write(
+        chalk.cyan(`Update available: v${local} -> v${remote}\n`)
+      );
+
+      // Show release notes (if any), truncated to 500 chars
+      const body = release.body;
+      if (body && body.trim().length > 0) {
+        const notes = body.length > 500 ? body.slice(0, 500) + '...' : body;
+        process.stdout.write('\nRelease notes:\n');
+        process.stdout.write(notes + '\n\n');
+      }
+
+      // Prompt user
+      const confirmed = await promptUser(`Update to v${remote}? [y/N] `);
+      if (!confirmed) {
+        process.stdout.write('Update cancelled.\n');
+        return;
+      }
+
+      downloadUrl = release.tarballUrl;
+    }
+
+    // --- Download and apply ---
     process.stdout.write('Downloading latest kit from GitHub...\n');
-    tempDir = await download(token);
+    tempDir = await download(token, downloadUrl !== undefined ? { url: downloadUrl } : {});
     const sourceDir = join(tempDir, '.claude');
 
     const result = await runUpdate({ sourceDir, targetDir, manifestPath, force: options.force });

package/src/lib/download.js

@@ -228,15 +228,16 @@ class TarExtractor extends Writable {
  * Download the kit repository as a tarball and extract .claude/ to targetDir.
  *
  * @param {string} token - GitHub Bearer token
- * @param {{ targetDir?: string }} [opts]
+ * @param {{ targetDir?: string, url?: string }} [opts]
+ *   - url: override the download URL (e.g. a release tarball URL). Defaults to main-branch TARBALL_URL.
  * @returns {Promise<string>} The targetDir path
  */
 export async function downloadAndExtractKit(token, opts = {}) {
-  const { targetDir = mkdtempSync(join(tmpdir(), 'mk-kit-')) } = opts;
+  const { targetDir = mkdtempSync(join(tmpdir(), 'mk-kit-')), url = TARBALL_URL } = opts;
 
   let res;
   try {
-    res = await fetch(TARBALL_URL, {
+    res = await fetch(url, {
       headers: {
         Authorization: `Bearer ${token}`,
         Accept: 'application/vnd.github.v3+json'

package/src/lib/releases.js

@@ -0,0 +1,94 @@
+import semver from 'semver';
+import { GITHUB_API, KIT_REPO } from './constants.js';
+
+// ---------------------------------------------------------------------------
+// GitHub Releases API helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the latest non-draft, non-prerelease release from the kit repository.
+ *
+ * Returns a discriminated union:
+ *   - On success:  { available: true, tag, version, body, tarballUrl }
+ *   - On failure:  { available: false, reason }
+ *
+ * Failure cases:
+ *   - Network error (GitHub unreachable)
+ *   - HTTP 404 (no releases, or private repo + bad token)
+ *   - Any other non-2xx response
+ *   - tag_name is not parseable as semver even with coerce()
+ *
+ * @param {string} token - GitHub Bearer token
+ * @returns {Promise<{ available: true, tag: string, version: string, body: string|null, tarballUrl: string }
+ *                  | { available: false, reason: string }>}
+ */
+export async function fetchLatestRelease(token) {
+  const url = `${GITHUB_API}/repos/${KIT_REPO}/releases/latest`;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3+json'
+      }
+    });
+  } catch (err) {
+    return { available: false, reason: `Network error: ${err.message}` };
+  }
+
+  if (!res.ok) {
+    return {
+      available: false,
+      reason: `HTTP ${res.status}: ${res.statusText}`
+    };
+  }
+
+  let data;
+  try {
+    data = await res.json();
+  } catch (err) {
+    return { available: false, reason: `Failed to parse release JSON: ${err.message}` };
+  }
+
+  const { tag_name: tag, body = null, tarball_url: tarballUrl } = data;
+
+  // Parse version: try clean() first (handles v-prefix), then coerce() as fallback.
+  // coerce('release-0.2.0') => '0.2.0', coerce('totally-not-semver') => null
+  const version = semver.clean(tag) ?? (semver.coerce(tag) ? semver.coerce(tag).version : null);
+
+  if (!version) {
+    return {
+      available: false,
+      reason: `Release tag "${tag}" is not a valid semver version`
+    };
+  }
+
+  return {
+    available: true,
+    tag,
+    version,
+    body: body ?? null,
+    tarballUrl
+  };
+}
+
+/**
+ * Compare a local version string against a remote version string.
+ *
+ * Both versions may include a `v` prefix — they are normalized before comparison.
+ *
+ * @param {string} localVersion - e.g. "0.1.3" or "v0.1.3"
+ * @param {string} remoteVersion - e.g. "0.1.5" or "v0.1.5"
+ * @returns {{ needsUpdate: boolean, local: string, remote: string }}
+ */
+export function compareVersions(localVersion, remoteVersion) {
+  // semver.clean strips 'v' prefix and whitespace; returns null for truly invalid strings.
+  // Fall back to coerce for any edge-case format.
+  const local = semver.clean(localVersion) ?? semver.coerce(localVersion)?.version ?? localVersion;
+  const remote = semver.clean(remoteVersion) ?? semver.coerce(remoteVersion)?.version ?? remoteVersion;
+
+  const needsUpdate = !!semver.gt(remote, local);
+
+  return { needsUpdate, local, remote };
+}