docshark 0.1.12 → 0.1.16

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/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

@@ -1,22 +1,30 @@
 #!/usr/bin/env bun
 // src/cli.ts — DocShark CLI entry point
-import { Command } from "commander";
+import { cac } from "cac";
 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")
-    .description("🦈 Documentation MCP Server — scrape, index, and search any doc website")
-    .version(VERSION, "-v, --version", "output the current version");
-program
-    .command("start", { isDefault: true })
+const useColor = process.stdout.isTTY;
+const color = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    yellow: "\x1b[33m",
+    gray: "\x1b[90m",
+};
+const cli = cac("docshark");
+cli
+    .command("", "Start the MCP server")
+    .alias("start")
     .alias("s")
-    .description("Start the MCP server (aliases: s, -s)")
-    .option("-p, --port <port>", "HTTP server port", "6380")
+    .option("-p, --port <port>", "HTTP server port", { default: "6380" })
     .option("-S, --stdio", "Run in STDIO mode (for Claude Desktop, Cursor, etc.)")
-    .option("-D, --data-dir <path>", "Data directory", "")
+    .option("-D, --data-dir <path>", "Data directory")
     .action(async (opts) => {
+    await maybeNotifyForCommand("start", opts.stdio === true);
     if (opts.dataDir) {
         process.env.DOCSHARK_DATA_DIR = opts.dataDir;
     }
@@ -30,14 +38,70 @@ program
         await startHttpServer(parseInt(opts.port));
     }
 });
-program
-    .command("add <url>")
+const helpCommands = [
+    {
+        name: "start",
+        aliases: ["s", "-s"],
+        args: "",
+        description: "Start server",
+    },
+    {
+        name: "add",
+        aliases: ["a", "-a"],
+        args: "<url>",
+        description: "Add & crawl library",
+    },
+    {
+        name: "search",
+        aliases: ["f", "-f"],
+        args: "<query>",
+        description: "Search docs",
+    },
+    {
+        name: "list",
+        aliases: ["l", "-l"],
+        args: "",
+        description: "List libraries",
+    },
+    {
+        name: "refresh",
+        aliases: ["r", "-r"],
+        args: "<name>",
+        description: "Refresh library",
+    },
+    {
+        name: "remove",
+        aliases: ["rm", "-rm"],
+        args: "<name>",
+        description: "Remove library",
+    },
+    {
+        name: "get",
+        aliases: ["g", "-g"],
+        args: "[url]",
+        description: "Get page markdown",
+    },
+    {
+        name: "update",
+        aliases: ["u", "-u"],
+        args: "",
+        description: "Update DocShark",
+    },
+    {
+        name: "info",
+        aliases: ["i", "-i"],
+        args: "<name>",
+        description: "Library info + pages",
+    },
+];
+cli
+    .command("add <url>", "Add a documentation library and start crawling")
     .alias("a")
-    .description("Add a documentation library and start crawling (aliases: a, -a)")
     .option("-n, --name <name>", "Library name (auto-generated from URL if omitted)")
-    .option("-d, --depth <n>", "Max crawl depth", "3")
+    .option("-d, --depth <n>", "Max crawl depth", { default: "3" })
     .option("-V, --lib-version <version>", "Library version")
     .action(async (url, opts) => {
+    await maybeNotifyForCommand("add");
     db.init();
     try {
         const lib = await libraryService.add({
@@ -57,13 +121,36 @@ program
         process.exit(1);
     }
 });
-program
-    .command("search <query>")
+cli.command("help [command]", "Show help for a command").action((command) => {
+    if (command) {
+        printCommandHelp(command);
+        return;
+    }
+    printRootHelp();
+});
+cli
+    .command("rename <current-name> <new-name>", "Rename an existing documentation library")
+    .alias("mv")
+    .action(async (currentName, newName) => {
+    await maybeNotifyForCommand("rename");
+    db.init();
+    try {
+        const library = libraryService.rename({ currentName, newName });
+        console.log(`\n✅ Renamed library to "${library.display_name}" (${library.name}).\n`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        console.error(`\n❌ ${message}\n`);
+        process.exit(1);
+    }
+});
+cli
+    .command("search <query>", "Search indexed documentation")
     .alias("f")
-    .description("Search indexed documentation (aliases: f, -f)")
     .option("-l, --library <name>", "Filter by library")
-    .option("-m, --limit <n>", "Max results", "5")
+    .option("-m, --limit <n>", "Max results", { default: "5" })
     .action(async (query, opts) => {
+    await maybeNotifyForCommand("search");
     db.init();
     const results = searchEngine.search(query, {
         library: opts.library,
@@ -80,12 +167,12 @@ program
         console.log(`Source: ${r.page_url}\n`);
     }
 });
-program
-    .command("list")
+cli
+    .command("list", "List indexed libraries")
     .alias("l")
-    .description("List indexed libraries (aliases: l, -l)")
-    .option("-s, --status <status>", "Filter by status (indexed, crawling, error, all)", "all")
-    .action((opts) => {
+    .option("-s, --status <status>", "Filter by status (indexed, crawling, error, all)", { default: "all" })
+    .action(async (opts) => {
+    await maybeNotifyForCommand("list");
     db.init();
     const libs = db.listLibraries(opts.status);
     if (libs.length === 0) {
@@ -101,11 +188,11 @@ program
         "Last Crawled": l.last_crawled_at || "never",
     })));
 });
-program
-    .command("refresh <name>")
+cli
+    .command("refresh <name>", "Refresh an existing documentation library")
     .alias("r")
-    .description("Refresh an existing documentation library (aliases: r, -r)")
     .action(async (name) => {
+    await maybeNotifyForCommand("refresh");
     db.init();
     try {
         const lib = db.getLibraryByName(name);
@@ -122,11 +209,11 @@ program
         process.exit(1);
     }
 });
-program
-    .command("remove <name>")
+cli
+    .command("remove <name>", "Remove a documentation library and its index")
     .alias("rm")
-    .description("Remove a documentation library and its index (aliases: rm, -rm)")
-    .action((name) => {
+    .action(async (name) => {
+    await maybeNotifyForCommand("remove");
     db.init();
     try {
         const lib = db.getLibraryByName(name);
@@ -140,13 +227,13 @@ program
         process.exit(1);
     }
 });
-program
-    .command("get [url]")
+cli
+    .command("get [url]", "Get the full markdown content of a specific indexed page")
     .alias("g")
-    .description("Get the full markdown content of a specific indexed page (aliases: g, -g)")
     .option("-l, --library <name>", "Library name to search within")
     .option("-p, --path <path>", "Relative path within the library")
-    .action((url, opts) => {
+    .action(async (url, opts) => {
+    await maybeNotifyForCommand("get");
     if (!url && (!opts.library || !opts.path)) {
         console.error(`\n❌ Please provide either a URL, or both --library and --path\n`);
         process.exit(1);
@@ -162,8 +249,20 @@ program
     console.log(page.content_markdown);
     console.log("\n");
 });
+cli
+    .command("update", "Update the global Bun installation of DocShark")
+    .alias("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 maybeNotifyForCommand("update");
+    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 args = process.argv.slice(2);
 const cmdAliases = {
     "-s": "start",
     "-a": "add",
@@ -173,15 +272,31 @@ const cmdAliases = {
     "-rm": "remove",
     "-g": "get",
     "-i": "info",
+    "-u": "update",
 };
-if (args[2] && cmdAliases[args[2]]) {
-    args[2] = cmdAliases[args[2]];
+const normalizedArgs = [...args];
+if (normalizedArgs[0] && cmdAliases[normalizedArgs[0]]) {
+    normalizedArgs[0] = cmdAliases[normalizedArgs[0]];
+}
+const helpRequest = getHelpRequest(normalizedArgs);
+if (helpRequest === "root") {
+    printRootHelp();
+    process.exit(0);
+}
+if (helpRequest && helpRequest !== "root") {
+    printCommandHelp(helpRequest);
+    process.exit(0);
 }
-program
-    .command("info <name>")
+if (normalizedArgs.includes("-v") || normalizedArgs.includes("--version")) {
+    printVersion();
+    process.exit(0);
+}
+const parseArgv = [process.argv[0], process.argv[1], ...normalizedArgs];
+cli
+    .command("info <name>", "Get information about a library and list its pages")
     .alias("i")
-    .description("Get information about a library and list its pages (aliases: i, -i)")
-    .action((name) => {
+    .action(async (name) => {
+    await maybeNotifyForCommand("info");
     db.init();
     const lib = db.getLibraryByName(name);
     if (!lib) {
@@ -207,7 +322,13 @@ program
         console.log(`\nNo pages found for this library.\n`);
     }
 });
-program.parse(args);
+try {
+    cli.parse(parseArgv, { run: false });
+    await cli.runMatchedCommand();
+}
+catch (error) {
+    handleCliError(error);
+}
 /** Helper to wait for a crawl job to finish (CLI blocking mode) */
 async function waitForCrawl(jobId) {
     const { jobManager } = await import("./server.js");
@@ -232,3 +353,94 @@ async function waitForCrawl(jobId) {
         check();
     });
 }
+async function maybeNotifyForCommand(commandName, stdioMode = false) {
+    await maybeNotifyAboutUpdate({ commandName, stdioMode });
+}
+function getHelpRequest(args) {
+    if (args.length === 0) {
+        return null;
+    }
+    if (args[0] === "-h" || args[0] === "--help") {
+        return "root";
+    }
+    if (args[0] === "help") {
+        return args[1] ? normalizeCommandName(args[1]) : "root";
+    }
+    if (args[1] === "help") {
+        return normalizeCommandName(args[0]);
+    }
+    if (args.includes("-h") || args.includes("--help")) {
+        return normalizeCommandName(args[0]);
+    }
+    return null;
+}
+function normalizeCommandName(name) {
+    return cmdAliases[name] ?? name;
+}
+function printVersion() {
+    console.log(`${paint("DocShark", color.cyan)} ${VERSION}`);
+}
+function printRootHelp() {
+    printHeader();
+    console.log(`${paint("USAGE", color.gray)}`);
+    console.log(`  docshark [options] [command]\n`);
+    console.log(`${paint("OPTIONS", color.gray)}`);
+    console.log(`  ${paint("-v, --version", color.cyan).padEnd(18)} Show version`);
+    console.log(`  ${paint("-h, --help", color.cyan).padEnd(18)} Show this help\n`);
+    console.log(`${paint("COMMANDS", color.gray)}`);
+    const rows = helpCommands.map((command) => ({
+        primary: [
+            command.name,
+            ...command.aliases.filter((alias) => !alias.startsWith("-")),
+        ].join(", "),
+        shortAliases: command.aliases.filter((alias) => alias.startsWith("-")),
+        args: command.args,
+        description: command.description,
+    }));
+    const primaryWidth = Math.max(...rows.map((row) => row.primary.length));
+    const argsWidth = Math.max(...rows.map((row) => row.args.length));
+    for (const row of rows) {
+        const aliasSuffix = row.shortAliases.length > 0
+            ? `  [aliases: ${row.shortAliases.join(", ")}]`
+            : "";
+        const label = `${row.primary.padEnd(primaryWidth)}${row.args ? ` ${row.args.padEnd(argsWidth)}` : `${"".padEnd(argsWidth + 1)}`}${aliasSuffix}`.trimEnd();
+        console.log(`  ${paint(label.padEnd(36), color.cyan)} ${row.description}`);
+    }
+    console.log(`\n${paint("Run `docshark help <command>` for more information.", color.dim)}`);
+}
+function printCommandHelp(commandName) {
+    const command = helpCommands.find((item) => item.name === normalizeCommandName(commandName));
+    printHeader();
+    if (!command) {
+        console.log(`${paint(`Unknown command: ${commandName}`, color.cyan)}\n`);
+        printRootHelp();
+        return;
+    }
+    console.log(`${paint("USAGE", color.gray)}`);
+    console.log(`  docshark ${command.name} ${command.args ? paint(command.args, color.yellow) : ""}`.trimEnd());
+    console.log(``);
+    console.log(`${paint("ALIASES", color.gray)}`);
+    console.log(`  ${command.aliases.join(", ")}\n`);
+    console.log(`${paint("SUMMARY", color.gray)}`);
+    console.log(`  ${command.description}\n`);
+    console.log(`${paint("Run `docshark help` to see all commands.", color.dim)}`);
+}
+function printHeader() {
+    console.log();
+    console.log(`${paint("🦈 DocShark", color.cyan)}  ${paint("Documentation MCP Server", color.bold)}`);
+    console.log(`   ${paint("Scrape • Index • Search any docs site", color.dim)}\n`);
+}
+function paint(text, code) {
+    if (!useColor) {
+        return text;
+    }
+    return `${code}${text}${color.reset}`;
+}
+function handleCliError(error) {
+    const message = error instanceof Error ? error.message : "Unknown command error";
+    const prettyMessage = message.startsWith("Unused args:")
+        ? "Too many arguments passed. Run `docshark help <command>` for usage."
+        : message;
+    console.error(`\n❌ ${prettyMessage}\n`);
+    process.exit(1);
+}

package/dist/server.d.ts

@@ -1,10 +1,10 @@
-import { McpServer } from 'tmcp';
-import * as v from 'valibot';
-import { Database } from './storage/db.js';
-import { SearchEngine } from './storage/search.js';
-import { LibraryService } from './services/library.js';
-import { JobManager } from './jobs/manager.js';
-import { EventBus } from './jobs/events.js';
+import { McpServer } from "tmcp";
+import * as v from "valibot";
+import { Database } from "./storage/db.js";
+import { SearchEngine } from "./storage/search.js";
+import { LibraryService } from "./services/library.js";
+import { JobManager } from "./jobs/manager.js";
+import { EventBus } from "./jobs/events.js";
 export declare const db: Database;
 export declare const eventBus: EventBus;
 export declare const searchEngine: SearchEngine;