@hmh-3080/kpm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kpm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# kpm
+
+> Kotlin/Java package manager for Gradle. Search, pick, done.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bun](https://img.shields.io/badge/bun-1.3+-fbf0df?logo=bun)](https://bun.sh)
+
+kpm is a CLI tool that lets you search Maven Central and Google Maven interactively, pick a version, and add the dependency to your `build.gradle` or `build.gradle.kts` — including required plugins and annotation processors.
+
+```
+$ kpm add room
+┌  kpm add
+│
+◇  Search complete
+│
+◆  Choose a library (12 results)
+│  ● androidx.room:room-runtime (2.8.4 • 45 versions • aar • 2d ago)
+│  ○ androidx.room:room-ktx
+│  ○ androidx.room:room-compiler
+│  ○ → Refine search...
+│
+◆  Choose a version
+│  2.8.4 ✓ latest stable
+│  2.8.3
+│  2.8.2
+│  ── pre-release ──
+│  2.9.0-alpha01
+│
+◇  Added androidx.room:room-runtime:2.8.4 to app/build.gradle.kts
+```
+
+---
+
+## Features
+
+- **Search across sources** — queries Maven Central and Google Maven in parallel
+- **Ranked results** — official/first-party libraries appear first, sorted by popularity
+- **Smart hints** — shows version count, packaging type, and last update for each result
+- **Stable vs pre-release** — clearly separated in the version picker
+- **Auto plugin management** — detects libraries that need KSP, kapt, or Compose plugins and adds them automatically
+- **Auto processor detection** — adds annotation processors (Room compiler, Hilt compiler, etc.) alongside the main dependency
+- **Idempotent** — running `kpm add` twice won't duplicate entries
+- **Multi-module support** — detects and lets you choose which module to add the dependency to
+- **Refine search** — if too many results, refine your query without restarting
+
+---
+
+## Installation
+
+Requires [Bun](https://bun.sh) v1.3+.
+
+```bash
+# Clone
+git clone https://github.com/HMH-3080/kpm.git
+cd kpm
+
+# Install dependencies
+bun install
+
+# Run directly
+bun run index.ts add <library>
+
+# Or build a standalone binary
+bun run build
+./kpm add <library>
+```
+
+---
+
+## Usage
+
+### Add a dependency
+
+```bash
+# Search and add interactively
+kpm add coil-compose
+
+# Specify a module
+kpm add retrofit --module app
+
+# Search with a specific query
+kpm add "ktor client"
+```
+
+### How it works
+
+1. **Search** — queries Maven Central (Solr API) and Google Maven (XML API) in parallel
+2. **Pick library** — shows top 10 results ranked by popularity; use `→ Refine search...` to narrow down
+3. **Pick version** — stable versions listed first, pre-release clearly marked
+4. **Choose module** — if multiple modules exist, pick one
+5. **Write** — adds `implementation(...)` line (and plugins/processors if needed)
+
+---
+
+## Auto-detected libraries
+
+These libraries get automatic plugin and processor handling:
+
+| Library | Plugin | Processor |
+|---------|--------|-----------|
+| `androidx.room:room-runtime` | KSP | `room-compiler` (ksp) |
+| `androidx.room:room-ktx` | KSP | `room-compiler` (ksp) |
+| `com.google.dagger:hilt-android` | Hilt | `hilt-android-compiler` (kapt) |
+| `com.google.dagger:dagger` | KSP | `dagger-compiler` (ksp) |
+| `com.squareup.moshi:moshi-kotlin` | — | `moshi-kotlin-codegen` (ksp) |
+| `androidx.compose.ui:ui` | Compose | — |
+| `androidx.compose.material3:material3` | Compose | — |
+| `androidx.compose.runtime:runtime` | Compose | — |
+| `androidx.compose.foundation:foundation` | Compose | — |
+| `org.jetbrains.kotlinx:kotlinx-serialization-json` | Serialization | — |
+| `com.github.bumptech.glide:glide` | KSP | `glide:ksp` |
+
+For example, adding `room-runtime` will:
+
+1. Add `id("com.google.devtools.ksp")` to the `plugins {}` block
+2. Add `implementation("androidx.room:room-runtime:2.8.4")` to `dependencies {}`
+3. Add `ksp("androidx.room:room-compiler:2.8.4")` to `dependencies {}`
+
+---
+
+## Ranking system
+
+Search results are ranked by:
+
+1. **Group match** — libraries whose group ID matches the query get a massive boost (official libraries first)
+2. **Version count** — more versions = more mature project
+3. **Recency** — recently updated libraries score higher
+
+This ensures `io.ktor:ktor` appears before third-party wrappers when you search for "ktor".
+
+---
+
+## Project structure
+
+```
+kpm/
+├── index.ts                    # CLI entry point
+├── src/
+│   ├── commands/
+│   │   └── add.ts              # Add command orchestrator
+│   └── lib/
+│       ├── types.ts            # Artifact, SpecialDep interfaces
+│       ├── ranking.ts          # Popularity scoring algorithm
+│       ├── mavenCentral.ts     # Maven Central Solr API + metadata.xml
+│       ├── googleMaven.ts      # Google Maven XML API
+│       ├── findGradleFile.ts   # Recursive walk for build.gradle(.kts)
+│       ├── gradleWriter.ts     # Writes dependencies into Gradle files
+│       └── specialDeps.ts      # Auto-detected plugin/processor map
+├── ARCHITECTURE.md             # Detailed architecture and known issues
+├── IMPROVEMENTS.md             # Roadmap and improvement proposals
+└── package.json
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `commander` | CLI framework |
+| `@clack/prompts` | Interactive terminal UI |
+| `picocolors` | Terminal colors |
+
+Zero runtime dependencies beyond these three.
+
+---
+
+## Development
+
+```bash
+# Install
+bun install
+
+# Run in dev mode
+bun run dev
+
+# Build standalone binary
+bun run build
+
+# Type check
+bunx tsc --noEmit
+```
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Make your changes
+4. Run `bunx tsc --noEmit` to verify types
+5. Submit a PR
+
+See `ARCHITECTURE.md` for codebase structure and `IMPROVEMENTS.md` for planned features.
+
+---
+
+## Documentation
+
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — codebase structure, known issues, and resolved bugs
+- [`IMPROVEMENTS.md`](./IMPROVEMENTS.md) — roadmap, API analysis, and improvement proposals
+
+---
+
+## License
+
+MIT

package/bin/kpm.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../index.ts";

package/index.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { addCommand } from "./src/commands/add";
+
+const program = new Command();
+
+program.name("kpm").description("Kotlin/Java Package Manager for Gradle").version("1.0.0");
+
+program
+  .command("add")
+  .description("Search and add a dependency to your Gradle project")
+  .argument("<query>", "Library name to search for")
+  .option("-m, --module <path>", "Target module directory")
+  .action(addCommand);
+
+program.parseAsync();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hmh-3080/kpm",
+  "version": "1.0.0",
+  "description": "Kotlin/Java package manager for Gradle. Search Maven Central & Google Maven interactively, pick a version, and add the dependency — including plugins and annotation processors.",
+  "type": "module",
+  "bin": {
+    "kpm": "./bin/kpm.js"
+  },
+  "scripts": {
+    "dev": "bun run index.ts",
+    "build": "bun build ./index.ts --compile --minify --outfile kpm"
+  },
+  "keywords": [
+    "kotlin",
+    "java",
+    "gradle",
+    "maven",
+    "package-manager",
+    "dependency",
+    "android",
+    "compose",
+    "room",
+    "hilt",
+    "ktor"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HMH-3080/kpm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HMH-3080/kpm/issues"
+  },
+  "homepage": "https://github.com/HMH-3080/kpm#readme",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,187 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { searchMavenCentral, getMavenCentralVersions } from "../lib/mavenCentral";
+import { searchGoogleMaven, getGoogleMavenVersions } from "../lib/googleMaven";
+import { findGradleModules } from "../lib/findGradleFile";
+import { addDependency } from "../lib/gradleWriter";
+import { resolveSpecialDep } from "../lib/specialDeps";
+import type { Artifact } from "../lib/types";
+
+const PAGE_SIZE = 10;
+
+function formatHint(a: Artifact): string {
+  const parts = [a.latestVersion];
+  if (a.versionCount) parts.push(`${a.versionCount} versions`);
+  if (a.packaging) parts.push(a.packaging);
+  if (a.lastUpdate) {
+    const days = Math.floor((Date.now() - a.lastUpdate) / 86_400_000);
+    if (days === 0) parts.push("today");
+    else if (days === 1) parts.push("1d ago");
+    else if (days < 30) parts.push(`${days}d ago`);
+    else if (days < 365) parts.push(`${Math.floor(days / 30)}mo ago`);
+    else parts.push(`${Math.floor(days / 365)}y ago`);
+  }
+  return parts.join(" • ");
+}
+
+const REFINE = Symbol("REFINE");
+
+async function searchAll(query: string): Promise<Artifact[]> {
+  const spinner = p.spinner();
+  spinner.start("Searching Maven Central and Google Maven");
+
+  const [centralResults, googleResults] = await Promise.all([
+    searchMavenCentral(query),
+    searchGoogleMaven(query),
+  ]);
+
+  spinner.stop("Search complete");
+
+  const all = [...googleResults, ...centralResults];
+  const seen = new Set<string>();
+  return all.filter((a) => {
+    const key = `${a.group}:${a.artifact}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+async function pickArtifact(initialQuery: string): Promise<Artifact | null> {
+  let query = initialQuery;
+
+  while (true) {
+    const results = await searchAll(query);
+
+    if (results.length === 0) {
+      p.log.error(`No artifacts found for "${query}"`);
+      const retry = await p.text({
+        message: "Try a different search?",
+        placeholder: "e.g. retrofit, glide, room",
+      });
+      if (p.isCancel(retry)) return null;
+      query = retry;
+      continue;
+    }
+
+    const page = results.slice(0, PAGE_SIZE);
+    const hasMore = results.length > PAGE_SIZE;
+
+    const options = [
+      ...page.map((a) => ({
+        value: a as Artifact | typeof REFINE,
+        label: `${a.group}:${a.artifact}`,
+        hint: formatHint(a),
+      })),
+      ...(hasMore
+        ? [{ value: REFINE as Artifact | typeof REFINE, label: pc.dim("→ Refine search..."), hint: pc.dim(`${results.length} total results`) }]
+        : []),
+    ];
+
+    const selected = await p.select({
+      message: `Choose a library (${results.length} results)`,
+      options,
+    });
+
+    if (p.isCancel(selected)) return null;
+
+    if (selected === REFINE) {
+      const refined = await p.text({
+        message: "Refine your search",
+        placeholder: query,
+        defaultValue: query,
+      });
+      if (p.isCancel(refined)) return null;
+      query = refined;
+      continue;
+    }
+
+    return selected as Artifact;
+  }
+}
+
+export async function addCommand(query: string, options: { module?: string }) {
+  p.intro(pc.bgCyan(pc.black(" kpm add ")));
+
+  try {
+    const artifact = await pickArtifact(query);
+
+    if (!artifact) {
+      p.cancel("Cancelled");
+      return;
+    }
+
+    const versionsSpinner = p.spinner();
+    versionsSpinner.start("Fetching versions");
+
+    const rawVersions =
+        artifact.source === "google"
+            ? await getGoogleMavenVersions(artifact.group, artifact.artifact)
+            : await getMavenCentralVersions(artifact.group, artifact.artifact);
+
+    versionsSpinner.stop("Versions fetched");
+
+    const stableVersions = rawVersions.filter(
+        (v) => !/(alpha|beta|rc|^m\d|dev|snapshot|preview|eap)/i.test(v)
+    );
+    const preReleaseVersions = rawVersions.filter(
+        (v) => /(alpha|beta|rc|^m\d|dev|snapshot|preview|eap)/i.test(v)
+    );
+    const latestStable = stableVersions[0] ?? rawVersions[0] ?? artifact.latestVersion;
+
+    const versionOptions = [
+      ...stableVersions.slice(0, 10).map((v) => ({
+        value: v,
+        label: v,
+        hint: v === latestStable ? pc.green("latest stable") : undefined,
+      })),
+      ...preReleaseVersions.slice(0, 5).map((v) => ({
+        value: v,
+        label: v,
+        hint: pc.yellow("pre-release"),
+      })),
+    ];
+
+    const selectedVersion = await p.select({
+      message: "Choose a version",
+      options: versionOptions,
+    });
+
+    if (p.isCancel(selectedVersion)) {
+      p.cancel("Cancelled");
+      return;
+    }
+
+    const modules = findGradleModules(options.module ?? process.cwd());
+
+    if (modules.length === 0) {
+      p.outro(pc.red("No build.gradle or build.gradle.kts found"));
+      return;
+    }
+
+    let targetModule = modules[0];
+
+    if (modules.length > 1) {
+      const moduleChoice = await p.select({
+        message: "Choose a module",
+        options: modules.map((m) => ({ value: m, label: m.path })),
+      });
+      if (p.isCancel(moduleChoice)) {
+        p.cancel("Cancelled");
+        return;
+      }
+      targetModule = moduleChoice as typeof modules[number];
+    }
+
+    const special = resolveSpecialDep(artifact.group, artifact.artifact);
+
+    addDependency(targetModule, artifact.group, artifact.artifact, selectedVersion as string, special);
+
+    p.outro(
+        pc.green(`Added ${pc.bold(`${artifact.group}:${artifact.artifact}:${selectedVersion}`)} to ${targetModule.path}`)
+    );
+  } catch (err) {
+    p.cancel(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}

package/src/lib/findGradleFile.ts

@@ -0,0 +1,41 @@
+import { readdirSync, statSync } from "fs";
+import { join } from "path";
+
+export interface GradleModule {
+  path: string;
+  kotlinDsl: boolean;
+}
+
+export function findGradleModules(root: string): GradleModule[] {
+  const modules: GradleModule[] = [];
+  const ignore = new Set(["node_modules", ".git", "build", ".gradle", ".idea"]);
+
+  function walk(dir: string) {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (ignore.has(entry)) continue;
+      const full = join(dir, entry);
+      let stats;
+      try {
+        stats = statSync(full);
+      } catch {
+        continue;
+      }
+      if (stats.isDirectory()) {
+        walk(full);
+      } else if (entry === "build.gradle.kts") {
+        modules.push({ path: full, kotlinDsl: true });
+      } else if (entry === "build.gradle") {
+        modules.push({ path: full, kotlinDsl: false });
+      }
+    }
+  }
+
+  walk(root);
+  return modules;
+}

package/src/lib/googleMaven.ts

@@ -0,0 +1,48 @@
+import type { Artifact } from "./types";
+import { sortVersionsDesc } from "./mavenCentral";
+import { computeScore } from "./ranking";
+
+let masterIndexCache: string[] | null = null;
+
+async function getGroups(): Promise<string[]> {
+    if (masterIndexCache) return masterIndexCache;
+    const res = await fetch("https://maven.google.com/master-index.xml");
+    const xml = await res.text();
+    const matches = [...xml.matchAll(/<([\w.\-]+)\/?>/g)].map((m) => m[1]);
+    masterIndexCache = matches.filter((g) => g !== "metadata");
+    return masterIndexCache;
+}
+
+export async function searchGoogleMaven(query: string): Promise<Artifact[]> {
+    const groups = await getGroups();
+    const lower = query.toLowerCase();
+    const matchedGroups = groups.filter((g) => g.toLowerCase().includes(lower)).slice(0, 8);
+    const results: Artifact[] = [];
+    await Promise.all(
+        matchedGroups.map(async (group) => {
+            const path = group.replace(/\./g, "/");
+            const res = await fetch(`https://maven.google.com/${path}/group-index.xml`);
+            if (!res.ok) return;
+            const xml = await res.text();
+            const entries = [...xml.matchAll(/<([\w.\-]+)\s+versions="([^"]+)"/g)];
+            for (const [, artifact, versions] of entries) {
+                if (artifact.toLowerCase().includes(lower) || group.toLowerCase().includes(lower)) {
+                    const versionList = versions.split(",");
+                    results.push({ group, artifact, latestVersion: sortVersionsDesc(versionList)[0], source: "google" });
+                }
+            }
+        })
+    );
+    results.sort((a, b) => computeScore({ group: b.group, artifact: b.artifact, versionCount: 0, timestamp: 0 }, query) - computeScore({ group: a.group, artifact: a.artifact, versionCount: 0, timestamp: 0 }, query));
+    return results;
+}
+
+export async function getGoogleMavenVersions(group: string, artifact: string): Promise<string[]> {
+    const path = group.replace(/\./g, "/");
+    const res = await fetch(`https://maven.google.com/${path}/group-index.xml`);
+    if (!res.ok) return [];
+    const xml = await res.text();
+    const match = xml.match(new RegExp(`<${artifact}\\s+versions="([^"]+)"`));
+    if (!match) return [];
+    return sortVersionsDesc(match[1].split(","));
+}

package/src/lib/gradleWriter.ts

@@ -0,0 +1,59 @@
+import { readFileSync, writeFileSync } from "fs";
+import type { GradleModule } from "./findGradleFile";
+import type { SpecialDep } from "./types";
+
+function formatDependencyLine(kotlinDsl: boolean, scope: string, coordinate: string): string {
+  return kotlinDsl ? `    ${scope}("${coordinate}")` : `    ${scope} '${coordinate}'`;
+}
+
+function insertIntoBlock(content: string, blockName: string, line: string): string {
+  const regex = new RegExp(`(${blockName}\\s*\\{)`);
+  const match = content.match(regex);
+  if (match) {
+    const index = match.index! + match[0].length;
+    return content.slice(0, index) + "\n" + line + content.slice(index);
+  }
+  return content + `\n${blockName} {\n${line}\n}\n`;
+}
+
+function ensurePlugin(content: string, kotlinDsl: boolean, pluginId: string, version?: string): string {
+  if (content.includes(pluginId)) return content;
+  const line = kotlinDsl
+    ? version
+      ? `    id("${pluginId}") version "${version}"`
+      : `    id("${pluginId}")`
+    : version
+    ? `    id '${pluginId}' version '${version}'`
+    : `    id '${pluginId}'`;
+  return insertIntoBlock(content, "plugins", line);
+}
+
+export function addDependency(
+  module: GradleModule,
+  group: string,
+  artifact: string,
+  version: string,
+  special?: SpecialDep
+): void {
+  let content = readFileSync(module.path, "utf-8");
+
+  if (special?.plugin) {
+    content = ensurePlugin(content, module.kotlinDsl, special.plugin.id, special.plugin.version);
+  }
+
+  const coordinate = `${group}:${artifact}:${version}`;
+  if (!content.includes(coordinate)) {
+    const mainLine = formatDependencyLine(module.kotlinDsl, "implementation", coordinate);
+    content = insertIntoBlock(content, "dependencies", mainLine);
+  }
+
+  if (special?.processor) {
+    const processorCoordinate = `${special.processor.coordinate}:${version}`;
+    if (!content.includes(processorCoordinate)) {
+      const processorLine = formatDependencyLine(module.kotlinDsl, special.processor.type, processorCoordinate);
+      content = insertIntoBlock(content, "dependencies", processorLine);
+    }
+  }
+
+  writeFileSync(module.path, content, "utf-8");
+}

package/src/lib/mavenCentral.ts

@@ -0,0 +1,100 @@
+import type { Artifact } from "./types";
+import { computeScore } from "./ranking";
+
+function normalizeVersion(v: string): string {
+  return v.replace(/[-+]/g, ".").replace(/\.\.+/g, ".");
+}
+
+function compareVersions(a: string, b: string): number {
+  const isPreReleaseA = /(alpha|beta|rc|^m\d|dev|snapshot|preview|eap)/i.test(a);
+  const isPreReleaseB = /(alpha|beta|rc|^m\d|dev|snapshot|preview|eap)/i.test(b);
+  if (isPreReleaseA !== isPreReleaseB) return isPreReleaseA ? -1 : 1;
+
+  const partsA = normalizeVersion(a).split(".").map((p) => (isNaN(Number(p)) ? p : Number(p)));
+  const partsB = normalizeVersion(b).split(".").map((p) => (isNaN(Number(p)) ? p : Number(p)));
+  const len = Math.max(partsA.length, partsB.length);
+
+  for (let i = 0; i < len; i++) {
+    const pa = partsA[i];
+    const pb = partsB[i];
+    if (pa === undefined) return -1;
+    if (pb === undefined) return 1;
+    if (typeof pa === "number" && typeof pb === "number") {
+      if (pa !== pb) return pa - pb;
+    } else {
+      const sa = String(pa);
+      const sb = String(pb);
+      if (sa !== sb) return sa.localeCompare(sb);
+    }
+  }
+  return 0;
+}
+
+export function sortVersionsDesc(versions: string[]): string[] {
+  return [...versions].sort(compareVersions).reverse();
+}
+
+interface RawDoc {
+  g: string;
+  a: string;
+  latestVersion: string;
+  timestamp: number;
+  versionCount: number;
+  packaging: string;
+}
+
+export async function searchMavenCentral(query: string): Promise<Artifact[]> {
+  const url = `https://search.maven.org/solrsearch/select?q=${encodeURIComponent(query)}&rows=30&wt=json`;
+  const res = await fetch(url);
+  if (!res.ok) return [];
+  const data = await res.json();
+
+  const docs: RawDoc[] = data.response.docs.map((doc: any) => ({
+    g: doc.g,
+    a: doc.a,
+    latestVersion: doc.latestVersion,
+    timestamp: doc.timestamp ?? 0,
+    versionCount: doc.versionCount ?? 0,
+    packaging: doc.p ?? "jar",
+  }));
+
+  const seen = new Set<string>();
+  const unique = docs.filter((d) => {
+    const key = `${d.g}:${d.a}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  unique.sort((a, b) => computeScore({ group: b.g, artifact: b.a, versionCount: b.versionCount, timestamp: b.timestamp }, query) - computeScore({ group: a.g, artifact: a.a, versionCount: a.versionCount, timestamp: a.timestamp }, query));
+
+  return unique.map((d) => ({
+    group: d.g,
+    artifact: d.a,
+    latestVersion: d.latestVersion,
+    source: "mavenCentral" as const,
+    versionCount: d.versionCount,
+    packaging: d.packaging,
+    lastUpdate: d.timestamp,
+  }));
+}
+
+export async function getMavenCentralVersions(group: string, artifact: string): Promise<string[]> {
+  const path = group.replace(/\./g, "/");
+  const metadataUrl = `https://repo1.maven.org/maven2/${path}/${artifact}/maven-metadata.xml`;
+
+  try {
+    const res = await fetch(metadataUrl);
+    if (res.ok) {
+      const xml = await res.text();
+      const versions = [...xml.matchAll(/<version>([^<]+)<\/version>/g)].map((m) => m[1]);
+      if (versions.length > 0) return sortVersionsDesc(versions);
+    }
+  } catch {}
+
+  const fallbackUrl = `https://search.maven.org/solrsearch/select?q=g:%22${encodeURIComponent(group)}%22+AND+a:%22${encodeURIComponent(artifact)}%22&core=gav&rows=200&wt=json`;
+  const fallbackRes = await fetch(fallbackUrl);
+  if (!fallbackRes.ok) return [];
+  const data = await fallbackRes.json();
+  return sortVersionsDesc(data.response.docs.map((doc: any) => doc.v));
+}

package/src/lib/ranking.ts

@@ -0,0 +1,25 @@
+export interface RankingMetrics {
+  group: string;
+  artifact: string;
+  versionCount: number;
+  timestamp: number;
+}
+
+export function computeScore(m: RankingMetrics, query?: string): number {
+  const daysSinceUpdate = (Date.now() - m.timestamp) / 86_400_000;
+  const recency = Math.max(0, 1 - daysSinceUpdate / 365);
+  const base = m.versionCount * 0.6 + recency * 100 * 0.4;
+
+  if (!query) return base;
+
+  const q = query.toLowerCase();
+  const g = m.group.toLowerCase();
+  const a = m.artifact.toLowerCase();
+
+  if (g === q || g.startsWith(q + ".") || g.startsWith(q + ":")) return base + 10000;
+  if (g.includes(q)) return base + 5000;
+  if (a.startsWith(q)) return base + 2000;
+  if (a.includes(q)) return base + 1000;
+
+  return base;
+}

package/src/lib/specialDeps.ts

@@ -0,0 +1,59 @@
+import type { SpecialDep } from "./types";
+
+export const specialDeps: Record<string, SpecialDep> = {
+  // Room
+  "androidx.room:room-runtime": {
+    plugin: { id: "com.google.devtools.ksp" },
+    processor: { coordinate: "androidx.room:room-compiler", type: "ksp" },
+  },
+  "androidx.room:room-ktx": {
+    plugin: { id: "com.google.devtools.ksp" },
+    processor: { coordinate: "androidx.room:room-compiler", type: "ksp" },
+  },
+
+  // Hilt
+  "com.google.dagger:hilt-android": {
+    plugin: { id: "com.google.dagger.hilt.android" },
+    processor: { coordinate: "com.google.dagger:hilt-android-compiler", type: "kapt" },
+  },
+
+  // Dagger (non-Hilt)
+  "com.google.dagger:dagger": {
+    plugin: { id: "com.google.devtools.ksp" },
+    processor: { coordinate: "com.google.dagger:dagger-compiler", type: "ksp" },
+  },
+
+  // Moshi
+  "com.squareup.moshi:moshi-kotlin": {
+    processor: { coordinate: "com.squareup.moshi:moshi-kotlin-codegen", type: "ksp" },
+  },
+
+  // Compose
+  "androidx.compose.ui:ui": {
+    plugin: { id: "org.jetbrains.kotlin.plugin.compose" },
+  },
+  "androidx.compose.material3:material3": {
+    plugin: { id: "org.jetbrains.kotlin.plugin.compose" },
+  },
+  "androidx.compose.runtime:runtime": {
+    plugin: { id: "org.jetbrains.kotlin.plugin.compose" },
+  },
+  "androidx.compose.foundation:foundation": {
+    plugin: { id: "org.jetbrains.kotlin.plugin.compose" },
+  },
+
+  // Kotlin Serialization
+  "org.jetbrains.kotlinx:kotlinx-serialization-json": {
+    plugin: { id: "org.jetbrains.kotlin.plugin.serialization" },
+  },
+
+  // Glide
+  "com.github.bumptech.glide:glide": {
+    plugin: { id: "com.google.devtools.ksp" },
+    processor: { coordinate: "com.github.bumptech.glide:ksp", type: "ksp" },
+  },
+};
+
+export function resolveSpecialDep(group: string, artifact: string): SpecialDep | undefined {
+  return specialDeps[`${group}:${artifact}`];
+}

package/src/lib/types.ts

@@ -0,0 +1,14 @@
+export interface Artifact {
+  group: string;
+  artifact: string;
+  latestVersion: string;
+  source: "mavenCentral" | "google";
+  versionCount?: number;
+  packaging?: string;
+  lastUpdate?: number;
+}
+
+export interface SpecialDep {
+  plugin?: { id: string; version?: string };
+  processor?: { coordinate: string; type: "ksp" | "kapt" };
+}