@khanhcan148/mk 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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/init.js

@@ -10,6 +10,7 @@ import { MANIFEST_FILENAME } from '../lib/constants.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';
 import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
+import { fetchLatestRelease } from '../lib/releases.js';
 
 /**
  * Run the init command.
@@ -19,7 +20,8 @@ import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
  *   targetDir?: string,
  *   manifestPath?: string,
  *   scope?: 'project'|'global',
- *   dryRun?: boolean
+ *   dryRun?: boolean,
+ *   version?: string  - Kit version to store in manifest (defaults to pkg.version when omitted)
  * }} params
  * @returns {Promise<{ files: Array, totalSize: number }>}
  */
@@ -29,7 +31,8 @@ export async function runInit(params = {}) {
     targetDir = resolveTargetDir({ global: false }),
     manifestPath = resolveManifestPath({ global: false }),
     scope = 'project',
-    dryRun = false
+    dryRun = false,
+    version: explicitVersion
   } = params;
 
   // Guard: abort if already installed
@@ -61,8 +64,10 @@ export async function runInit(params = {}) {
     }
   }
 
-  // Write manifest
-  writeManifest(manifestPath, files, pkg.version, scope);
+  // Write manifest.
+  // Use explicitVersion when provided (e.g. release.version from initAction);
+  // fall back to pkg.version for direct runInit calls without a known release version.
+  writeManifest(manifestPath, files, explicitVersion ?? pkg.version, scope);
 
   const totalSize = fileList.reduce((s, f) => s + f.size, 0);
   return { files: fileList, totalSize, fileCount: fileList.length };
@@ -81,11 +86,15 @@ export async function initAction(options = {}, deps = {}) {
     downloadAndExtractKit: download = downloadAndExtractKit,
     cleanupTempDir: cleanup = cleanupTempDir,
     writeToken: storeToken = writeToken,
-    readStoredToken: readToken = readStoredToken
+    readStoredToken: readToken = readStoredToken,
+    fetchLatestRelease: fetchRelease = fetchLatestRelease,
+    // Injectable for tests — allows overriding resolved paths without touching CWD
+    targetDir: injectedTargetDir,
+    manifestPath: injectedManifestPath
   } = deps;
 
-  const targetDir = resolveTargetDir(options);
-  const manifestPath = resolveManifestPath(options);
+  const targetDir = injectedTargetDir ?? resolveTargetDir(options);
+  const manifestPath = injectedManifestPath ?? resolveManifestPath(options);
   const scope = options.global ? 'global' : 'project';
 
   // Pre-flight: warn if target exists with files
@@ -115,11 +124,23 @@ export async function initAction(options = {}, deps = {}) {
       }
     });
 
+    // Determine installed version from latest release (more accurate than pkg.version).
+    // Falls back silently to pkg.version if no release is available (new repo, API error, etc.)
+    let installedVersion;
+    if (!options.dryRun) {
+      try {
+        const release = await fetchRelease(token);
+        installedVersion = release.available ? release.version : undefined;
+      } catch {
+        // Ignore errors — version fallback handled by runInit
+      }
+    }
+
     process.stdout.write('Downloading kit from GitHub...\n');
     tempDir = await download(token);
     const sourceDir = join(tempDir, '.claude');
 
-    const result = await runInit({ sourceDir, targetDir, manifestPath, scope, dryRun: options.dryRun });
+    const result = await runInit({ sourceDir, targetDir, manifestPath, scope, dryRun: options.dryRun, version: installedVersion });
 
     if (options.dryRun) {
       process.stdout.write(`Would install ${result.files.length} files:\n`);

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.
@@ -17,7 +40,8 @@ import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
  *   sourceDir?: string,
  *   targetDir?: string,
  *   manifestPath?: string,
- *   force?: boolean
+ *   force?: boolean,
+ *   version?: string  - Kit version to store in manifest (defaults to pkg.version when omitted)
  * }} params
  * @returns {Promise<{ updated: string[], added: string[], removed: string[], conflicts: string[], unchanged: string[], upToDate: boolean }>}
  */
@@ -26,7 +50,8 @@ export async function runUpdate(params = {}) {
     sourceDir = resolveSourceDir(),
     targetDir = resolveTargetDir({ global: false }),
     manifestPath = resolveManifestPath({ global: false }),
-    force = false
+    force = false,
+    version: explicitVersion
   } = params;
 
   // Read existing manifest
@@ -136,8 +161,10 @@ export async function runUpdate(params = {}) {
     delete newFiles[relPath];
   }
 
-  // Update manifest with new file map
-  updateManifest(manifestPath, newFiles, pkg.version);
+  // Update manifest with new file map.
+  // Use explicitVersion when provided (e.g. release.version from updateAction);
+  // fall back to pkg.version for direct runUpdate calls or main-branch fallback downloads.
+  updateManifest(manifestPath, newFiles, explicitVersion ?? pkg.version);
 
   return {
     updated: diff.updated,
@@ -151,7 +178,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,11 +191,21 @@ 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,
+    // Injectable for tests — allows overriding resolved paths without touching CWD
+    manifestPath: injectedManifestPath
   } = deps;
 
+  // Read local package version (used as fallback when manifest has no version)
+  const pkg = JSON.parse(
+    readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')
+  );
+
   const targetDir = resolveTargetDir(options);
-  const manifestPath = resolveManifestPath(options);
+  const manifestPath = injectedManifestPath ?? resolveManifestPath(options);
 
   let tempDir = null;
   try {
@@ -183,11 +222,71 @@ export async function updateAction(options = {}, deps = {}) {
       }
     });
 
+    // --- Version check via GitHub Releases API ---
+    process.stdout.write('Checking for updates...\n');
+    const release = await fetchRelease(token);
+
+    // Read installed version from manifest (more accurate than pkg.version which reflects
+    // the CLI package, not the downloaded kit files). Fall back to pkg.version if no manifest.
+    let installedVersion = pkg.version;
+    if (existsSync(manifestPath)) {
+      try {
+        const existingManifest = readManifest(manifestPath);
+        if (existingManifest?.version) installedVersion = existingManifest.version;
+      } catch {
+        // Manifest unreadable — proceed with pkg.version fallback
+      }
+    }
+
+    let downloadUrl; // undefined = use default (main branch)
+    let releaseVersion; // set when downloading from a specific release tarball
+
+    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(installedVersion, 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;
+      releaseVersion = release.version;
+    }
+
+    // --- 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 });
+    // Pass releaseVersion so runUpdate stores it in the manifest.
+    // When falling back to main branch (no release), releaseVersion is undefined and
+    // runUpdate falls back to pkg.version — which is the correct behaviour for that path.
+    const result = await runUpdate({ sourceDir, targetDir, manifestPath, force: options.force, version: releaseVersion });
 
     if (result.upToDate) {
       process.stdout.write(chalk.green('Already up to date.\n'));

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 };
+}