docshark 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.1.13](https://github.com/Michael-Obele/docshark/compare/v0.1.12...v0.1.13) (2026-03-12)
+
+
+### ✨ Features
+
+* add workflow to cleanup release-please branches on pull request closure ([b250d35](https://github.com/Michael-Obele/docshark/commit/b250d352df810998ed4eb9a1876bf5149c2e9d7d))
+* enhance update command with check and quiet options in CLI ([9f91aba](https://github.com/Michael-Obele/docshark/commit/9f91abafccaa21c9fb43dba5a5548b473a4dc266))
+* implement Bun-first update command and version notification in CLI ([ce31a13](https://github.com/Michael-Obele/docshark/commit/ce31a132d91e3302699afe51f6295a9b0b815e20))
+
 ## [0.1.12](https://github.com/Michael-Obele/docshark/compare/v0.1.11...v0.1.12) (2026-03-12)
 
 

package/README.md

@@ -64,11 +64,10 @@ bunx docshark search "schema validation"
 
 To install DocShark globally as a CLI tool:
 
-```bash
-# Using npm
-npm install -g docshark
+DocShark is intended to be installed and run with Bun.
 
-# Using Bun
+```bash
+# Global Bun installation
 bun add -g docshark
 ```
 
@@ -76,8 +75,18 @@ After installation, you can use the `docshark` command:
 
 ```bash
 docshark list
+
+# Update the global Bun installation when a new release is published
+docshark update
+
+# Script-friendly update check
+docshark update --check --quiet
 ```
 
+Interactive CLI runs will also let you know when a newer version is available. Update notices are intentionally skipped for MCP `stdio` mode so they never interfere with protocol output.
+
+For scripts, `docshark update --check` exits `0` when current, `10` when a newer version is available, and `1` when the version check could not be completed.
+
 ## 🔌 MCP Integration
 
 ### VS Code (GitHub Copilot / MCP Extension)

package/dist/cli-update.d.ts

@@ -0,0 +1,10 @@
+type RunUpdateOptions = {
+    checkOnly?: boolean;
+    quiet?: boolean;
+};
+export declare function maybeNotifyAboutUpdate(options: {
+    commandName: string;
+    stdioMode: boolean;
+}): Promise<void>;
+export declare function runUpdateCommand(options?: RunUpdateOptions): Promise<void>;
+export {};

package/dist/cli-update.js

@@ -0,0 +1,186 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { VERSION } from "./version.js";
+const PACKAGE_NAME = "docshark";
+const REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 2500;
+export async function maybeNotifyAboutUpdate(options) {
+    if (shouldSkipUpdateNotice(options)) {
+        return;
+    }
+    const latestVersion = await getLatestVersion();
+    if (!latestVersion || compareVersions(latestVersion, VERSION) <= 0) {
+        return;
+    }
+    console.error(`\nA newer DocShark version is available: ${VERSION} -> ${latestVersion}.`);
+    console.error(`Run \"docshark update\" or \"bun add -g ${PACKAGE_NAME}@latest\".\n`);
+}
+export async function runUpdateCommand(options = {}) {
+    const latestVersion = await getLatestVersion({ forceRefresh: true });
+    if (!latestVersion) {
+        printFallbackUpdateCommand("Could not check the npm registry for the latest DocShark release.", options.quiet);
+        process.exit(1);
+        return;
+    }
+    const hasUpdate = compareVersions(latestVersion, VERSION) > 0;
+    if (options.checkOnly) {
+        if (!options.quiet) {
+            if (hasUpdate) {
+                console.log(`\nUpdate available: ${VERSION} -> ${latestVersion}.\n`);
+            }
+            else {
+                console.log(`\nDocShark is already up to date (${VERSION}).\n`);
+            }
+        }
+        process.exit(hasUpdate ? 10 : 0);
+        return;
+    }
+    if (!hasUpdate) {
+        if (!options.quiet) {
+            console.log(`\nDocShark is already up to date (${VERSION}).\n`);
+        }
+        return;
+    }
+    const bunPath = resolveBunExecutable();
+    if (!bunPath) {
+        printFallbackUpdateCommand(`A newer version is available (${VERSION} -> ${latestVersion}), but Bun was not detected on PATH.`, options.quiet);
+        process.exit(1);
+        return;
+    }
+    if (!options.quiet) {
+        console.log(`\nUpdating DocShark ${VERSION} -> ${latestVersion} with Bun...\n`);
+    }
+    const exitCode = await spawnProcess(bunPath, [
+        "add",
+        "-g",
+        `${PACKAGE_NAME}@latest`,
+    ]);
+    if (exitCode !== 0) {
+        printFallbackUpdateCommand(`The Bun update command exited with code ${exitCode}.`, options.quiet);
+        process.exit(exitCode ?? 1);
+    }
+    if (!options.quiet) {
+        console.log(`\nDocShark was updated to ${latestVersion}.\n`);
+    }
+}
+function shouldSkipUpdateNotice(options) {
+    if (options.stdioMode || options.commandName === "update") {
+        return true;
+    }
+    if (!process.stdout.isTTY || !process.stderr.isTTY || process.env.CI) {
+        return true;
+    }
+    const rawFlag = process.env.DOCSHARK_DISABLE_UPDATE_CHECK?.trim().toLowerCase();
+    return rawFlag === "1" || rawFlag === "true" || rawFlag === "yes";
+}
+async function getLatestVersion(options) {
+    if (!options?.forceRefresh) {
+        const cached = await readCachedUpdateCheck();
+        if (cached && Date.now() - cached.checkedAt < UPDATE_CHECK_TTL_MS) {
+            return cached.latestVersion;
+        }
+    }
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) {
+        const cached = await readCachedUpdateCheck();
+        return cached?.latestVersion ?? null;
+    }
+    await writeCachedUpdateCheck({
+        latestVersion,
+        checkedAt: Date.now(),
+    });
+    return latestVersion;
+}
+async function fetchLatestVersion() {
+    try {
+        const response = await fetch(REGISTRY_LATEST_URL, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const payload = (await response.json());
+        return typeof payload.version === "string" ? payload.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readCachedUpdateCheck() {
+    try {
+        const contents = await readFile(getUpdateCachePath(), "utf8");
+        const parsed = JSON.parse(contents);
+        if (typeof parsed.latestVersion !== "string" ||
+            typeof parsed.checkedAt !== "number") {
+            return null;
+        }
+        return {
+            latestVersion: parsed.latestVersion,
+            checkedAt: parsed.checkedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCachedUpdateCheck(cache) {
+    try {
+        const cachePath = getUpdateCachePath();
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, JSON.stringify(cache), "utf8");
+    }
+    catch {
+        // Best-effort cache only.
+    }
+}
+function getUpdateCachePath() {
+    const baseCacheDir = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+    return join(baseCacheDir, PACKAGE_NAME, "update-check.json");
+}
+function resolveBunExecutable() {
+    if (typeof Bun !== "undefined") {
+        const bunOnPath = Bun.which("bun");
+        if (bunOnPath) {
+            return bunOnPath;
+        }
+    }
+    return basename(process.execPath).startsWith("bun") ? process.execPath : null;
+}
+function compareVersions(left, right) {
+    const leftParts = left.split(".");
+    const rightParts = right.split(".");
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftValue = parseNumericVersionPart(leftParts[index]);
+        const rightValue = parseNumericVersionPart(rightParts[index]);
+        if (leftValue !== rightValue) {
+            return leftValue - rightValue;
+        }
+    }
+    return 0;
+}
+function parseNumericVersionPart(part) {
+    if (!part) {
+        return 0;
+    }
+    const match = part.match(/^(\d+)/);
+    return match ? Number.parseInt(match[1], 10) : 0;
+}
+function spawnProcess(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: "inherit" });
+        child.on("error", reject);
+        child.on("exit", (code) => resolve(code));
+    });
+}
+function printFallbackUpdateCommand(reason, quiet = false) {
+    if (quiet) {
+        return;
+    }
+    console.error(`\n${reason}`);
+    console.error(`Run \"bun add -g ${PACKAGE_NAME}@latest\" to update DocShark.\n`);
+}

package/dist/cli.js

@@ -4,6 +4,7 @@ import { Command } from "commander";
 import { startHttpServer } from "./http.js";
 import { StdioTransport } from "@tmcp/transport-stdio";
 import { server, db, searchEngine, libraryService } from "./server.js";
+import { maybeNotifyAboutUpdate, runUpdateCommand } from "./cli-update.js";
 import { VERSION } from "./version.js";
 const program = new Command()
     .name("docshark")
@@ -162,6 +163,18 @@ program
     console.log(page.content_markdown);
     console.log("\n");
 });
+program
+    .command("update")
+    .alias("u")
+    .description("Update the global Bun installation of DocShark (aliases: u, -u)")
+    .option("-c, --check", "Only check whether a newer DocShark version is available")
+    .option("-q, --quiet", "Suppress DocShark status output and rely on exit codes")
+    .action(async (opts) => {
+    await runUpdateCommand({
+        checkOnly: opts.check,
+        quiet: opts.quiet,
+    });
+});
 // Intercept manual short flags (e.g., -l instead of l) so they act as command aliases
 const args = process.argv;
 const cmdAliases = {
@@ -173,6 +186,7 @@ const cmdAliases = {
     "-rm": "remove",
     "-g": "get",
     "-i": "info",
+    "-u": "update",
 };
 if (args[2] && cmdAliases[args[2]]) {
     args[2] = cmdAliases[args[2]];
@@ -207,7 +221,17 @@ program
         console.log(`\nNo pages found for this library.\n`);
     }
 });
-program.parse(args);
+program.hook("preAction", async (_thisCommand, actionCommand) => {
+    const commandName = actionCommand.name();
+    const options = typeof actionCommand.opts === "function"
+        ? actionCommand.opts()
+        : {};
+    await maybeNotifyAboutUpdate({
+        commandName,
+        stdioMode: commandName === "start" && options.stdio === true,
+    });
+});
+await program.parseAsync(args);
 /** Helper to wait for a crawl job to finish (CLI blocking mode) */
 async function waitForCrawl(jobId) {
     const { jobManager } = await import("./server.js");

package/dist/tools/list-libraries.d.ts

@@ -5,7 +5,7 @@ export declare function createListLibrariesTool(db: Database): {
         name: "list_libraries";
         description: string;
         schema: v.ObjectSchema<{
-            readonly status: v.OptionalSchema<v.SchemaWithPipe<readonly [v.PicklistSchema<["indexed", "crawling", "error", "all"], undefined>, v.DescriptionAction<"crawling" | "indexed" | "error" | "all", "Filter by indexing status. Default: \"all\".">]>, "all">;
+            readonly status: v.OptionalSchema<v.SchemaWithPipe<readonly [v.PicklistSchema<["indexed", "crawling", "error", "all"], undefined>, v.DescriptionAction<"error" | "crawling" | "indexed" | "all", "Filter by indexing status. Default: \"all\".">]>, "all">;
         }, undefined>;
     };
     handler: ({ status }: {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.12";
+export declare const VERSION = "0.1.13";

package/dist/version.js

@@ -1,2 +1,2 @@
 // This file is automatically updated by release-please
-export const VERSION = '0.1.12'; // x-release-please-version
+export const VERSION = '0.1.13'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docshark",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "🦈 Documentation MCP Server — scrape, index, and search any doc website",
   "type": "module",
   "main": "./dist/index.js",