trueicon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manikumarkv
+
+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,334 @@
+# TrueIcon
+
+TrueIcon is an [MCP](https://modelcontextprotocol.io) server that gives AI coding assistants exact, version-correct icon references. Your assistant searches the icon packages your project actually uses (`lucide-react`, `react-icons`, `@heroicons/react`) and gets back real icon names, import paths and a ready-to-paste `import` line.
+
+## Why
+
+AI assistants often guess icon names. The guess can be an icon that never existed, one renamed a few releases ago, or one from a different library, and you only find out when the build fails. TrueIcon closes that gap:
+
+- It reads which icon packages and versions your project uses.
+- It downloads those exact versions from npm and indexes every icon once.
+- The assistant calls `search_icons` and gets results that are guaranteed to exist in that version, for example `import { Trash2 } from 'lucide-react';`.
+
+## Supported providers
+
+| Provider id   | npm package        | Icon naming                                                      |
+| ------------- | ------------------ | ---------------------------------------------------------------- |
+| `lucide`      | `lucide-react`     | Lucide's file names, e.g. `trash-2` → `Trash2`                   |
+| `heroicons`   | `@heroicons/react` | `<icon>-<size>-<style>`, e.g. `trash-24-outline` → `TrashIcon`    |
+| `react-icons` | `react-icons`      | `<set>-<icon>`, e.g. `fa6-beer-mug-empty` → `FaBeerMugEmpty`      |
+
+Tools accept either the provider id or the npm package name (`"lucide"` or `"lucide-react"`). Usage snippets are for React.
+
+## Install
+
+TrueIcon needs Node.js 20 or newer.
+
+```sh
+# Run without installing (this is what the MCP configs below do)
+npx -y trueicon
+
+# Or install globally and run the `trueicon` binary
+npm i -g trueicon
+trueicon
+```
+
+`trueicon` is a stdio MCP server. Your MCP client starts it; running it by hand only prints `trueicon: v0.1.0 running on stdio` to stderr and waits for JSON-RPC on stdin.
+
+## Quick start
+
+1. Add a `.iconmcp.json` to your project root that lists your icon packages:
+
+   ```json
+   {
+     "providers": [
+       { "package": "lucide-react" },
+       { "package": "@heroicons/react", "version": "2.1.5" }
+     ]
+   }
+   ```
+
+2. Register TrueIcon with your MCP client ([Claude Code](#claude-code) or [Claude Desktop](#claude-desktop)).
+3. Ask your assistant for an icon. The first search for each package downloads and indexes it, which takes a few seconds. Later searches use the local cache.
+
+## Configuration: `.iconmcp.json`
+
+TrueIcon looks for `.iconmcp.json` in the project directory. That is `$TRUEICON_PROJECT_DIR` if set, otherwise the server's working directory.
+
+```json
+{
+  "providers": [
+    { "package": "lucide-react" },
+    { "package": "react-icons", "version": "5.3.0" },
+    { "package": "@heroicons/react", "version": "^2.1.0" }
+  ]
+}
+```
+
+| Field                   | Type   | Required | Meaning                                                                                  |
+| ----------------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
+| `providers`             | array  | yes      | Icon packages the project uses. `search_icons` searches all of them by default.          |
+| `providers[].package`   | string | yes      | npm package name: `lucide-react`, `react-icons` or `@heroicons/react`.                   |
+| `providers[].version`   | string | no       | Exact version or npm range. If omitted, it is read from `package.json` (see below).      |
+
+- If the file is missing, no providers are configured. `search_icons` then only works when you pass `provider` explicitly, and `get_icon` still works.
+- Unsupported packages in the list are skipped, and `search_icons` reports them as a warning.
+- Invalid JSON or a malformed entry makes the tools return an error that names the file and the bad field.
+
+### Environment variables
+
+| Variable               | Default               | Purpose                                              |
+| ---------------------- | --------------------- | ---------------------------------------------------- |
+| `TRUEICON_PROJECT_DIR` | working directory     | Project root holding `.iconmcp.json` and `package.json` |
+| `TRUEICON_CACHE`       | `~/.trueicon/cache`   | Where downloaded packages and indexes are stored     |
+
+## Versions
+
+### Auto-detection
+
+A provider's version is resolved in this order:
+
+1. The `version` argument passed to the tool call, if any.
+2. The provider's `version` in `.iconmcp.json`.
+3. The version range declared for the package in the project's `package.json`, checking `dependencies` first and then `devDependencies`.
+
+If none of these is available, the tool asks you to pin the version or add the package to `package.json`. TrueIcon reads the declared range from `package.json`. It does not read `node_modules` or the lockfile. For a range, it indexes the range's base version: `^0.460.0` indexes `lucide-react@0.460.0`. For `a || b` ranges, only the first part counts. To match an exact installed version, pin it in `.iconmcp.json`.
+
+### Version policy
+
+Indexes are keyed by **major.minor**:
+
+- **Patch versions are ignored.** One index serves all of `0.460.x`. The index built from `0.460.0` answers requests for `0.460.3`.
+- **A minor change gets its own index.** Bumping `lucide-react` from `0.460` to `0.461` builds a fresh index on the next search, with no manual step.
+- **Majors are strict.** A different major is always a separate index and is never served from another major's index.
+- **Cached indexes rebuild automatically** when the bundled `synonyms.json` changes (detected by hash) or the index format changes.
+
+## Using it with Claude
+
+### Claude Code
+
+Add TrueIcon from your project directory:
+
+```sh
+claude mcp add trueicon -- npx -y trueicon
+```
+
+Or commit a `.mcp.json` at the project root to share it with your team:
+
+```json
+{
+  "mcpServers": {
+    "trueicon": {
+      "command": "npx",
+      "args": ["-y", "trueicon"]
+    }
+  }
+}
+```
+
+Claude Code starts the server in your project directory, so it finds `.iconmcp.json` and `package.json` there. If it runs from somewhere else, add `"env": { "TRUEICON_PROJECT_DIR": "/absolute/path/to/project" }`.
+
+### Claude Desktop
+
+Claude Desktop doesn't start servers in your project directory, so set `TRUEICON_PROJECT_DIR`. Edit `claude_desktop_config.json`: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows.
+
+```json
+{
+  "mcpServers": {
+    "trueicon": {
+      "command": "npx",
+      "args": ["-y", "trueicon"],
+      "env": {
+        "TRUEICON_PROJECT_DIR": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing the file.
+
+## Tools
+
+Every tool returns a single JSON text block. On failure, the block is `{"error": "..."}` and the MCP result is flagged with `isError: true`.
+
+### `search_icons`
+
+Searches the index and returns ranked matches with import statements.
+
+| Argument   | Type    | Required | Description                                                                          |
+| ---------- | ------- | -------- | ------------------------------------------------------------------------------------ |
+| `query`    | string  | yes      | What the icon should depict, e.g. `"trash"`                                          |
+| `provider` | string  | no       | Provider id or package. Default: every provider in `.iconmcp.json`                   |
+| `version`  | string  | no       | Version or range. Default: resolved as described in [Versions](#versions)            |
+| `style`    | string  | no       | Exact style filter: `"outline"` or `"solid"` (lucide icons are all `outline`)         |
+| `set`      | string  | no       | Exact set filter, e.g. `"fa6"` or `"md"` for react-icons                             |
+| `limit`    | integer | no       | Maximum results, 1 to 50, default 10                                                 |
+
+Example call:
+
+```json
+{ "query": "trash", "provider": "lucide", "limit": 3 }
+```
+
+Response:
+
+```json
+{
+  "results": [
+    { "name": "trash", "importName": "Trash", "importPath": "lucide-react", "package": "lucide-react",
+      "version": "0.460.0", "style": "outline", "set": "lucide",
+      "usage": "import { Trash } from 'lucide-react';", "score": 2.0e-14 },
+    { "name": "trash-2", "importName": "Trash2", "importPath": "lucide-react", "package": "lucide-react",
+      "version": "0.460.0", "style": "outline", "set": "lucide",
+      "usage": "import { Trash2 } from 'lucide-react';", "score": 1.6e-6 },
+    { "name": "delete", "importName": "Delete", "importPath": "lucide-react", "package": "lucide-react",
+      "version": "0.460.0", "style": "outline", "set": "lucide",
+      "usage": "import { Delete } from 'lucide-react';", "score": 1.2e-4 }
+  ]
+}
+```
+
+How search works:
+
+- `provider`, `style` and `set` are exact, case-insensitive filters. They are applied before ranking.
+- Ranking uses [Fuse.js](https://www.fusejs.io/) fuzzy matching over the icon name, import name, keywords and tags. Small typos are tolerated: `"detele"` finds `Delete`.
+- `score` runs from `0` (perfect) to `1`, so lower is better. Results from several providers are merged and sorted by score.
+- Short keyword queries (`"trash"`, `"settings"`, `"beer"`) work best. The query is matched as one string, so a multi-word phrase such as `"trash can"` may return fewer results than its main keyword alone.
+- If one provider fails, for example because its version can't be resolved or the download fails, its results are skipped and a `warnings` array explains why. The other providers still return results.
+
+### `list_providers`
+
+Takes no arguments. Returns the providers configured in `.iconmcp.json` with their resolved versions, plus every provider TrueIcon supports.
+
+```json
+{
+  "configured": [
+    { "id": "lucide", "package": "lucide-react", "version": "^0.460.0", "source": "package.json" },
+    { "id": "heroicons", "package": "@heroicons/react", "version": "2.1.5", "source": "iconmcp.json" }
+  ],
+  "registry": [
+    { "id": "react-icons", "package": "react-icons", "description": "Aggregated icon sets (Font Awesome, Material, Feather, and more) as React components" },
+    { "id": "lucide", "package": "lucide-react", "description": "Lucide icons as React components" },
+    { "id": "heroicons", "package": "@heroicons/react", "description": "Heroicons by the Tailwind CSS team as React components" }
+  ]
+}
+```
+
+`source` is `"iconmcp.json"` or `"package.json"`. `version` and `source` are `null` when neither file provides a version. `id` is `null` for a configured package TrueIcon doesn't support.
+
+### `get_icon`
+
+Gets the full record and import statement for an icon whose name the assistant already knows.
+
+| Argument   | Type   | Required | Description                                                        |
+| ---------- | ------ | -------- | ------------------------------------------------------------------ |
+| `name`     | string | yes      | Icon name (`"trash-2"`) or import name (`"Trash2"`). Exact match first, then case-insensitive |
+| `provider` | string | yes      | Provider id or package                                             |
+| `version`  | string | no       | Version or range. Default: resolved as described in [Versions](#versions) |
+
+Example call:
+
+```json
+{ "name": "Trash2", "provider": "lucide" }
+```
+
+Response:
+
+```json
+{
+  "id": "lucide-react@0.460:trash-2",
+  "name": "trash-2",
+  "importName": "Trash2",
+  "importPath": "lucide-react",
+  "provider": "lucide",
+  "package": "lucide-react",
+  "version": "0.460.0",
+  "style": "outline",
+  "set": "lucide",
+  "categories": [],
+  "tags": [],
+  "keywords": ["trash", "2", "delete", "remove", "bin", "garbage", "rubbish"],
+  "svg": "<path d=\"M3 6h18\"/><path d=\"M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6\"/>…",
+  "usage": "import { Trash2 } from 'lucide-react';"
+}
+```
+
+`svg` is the icon's inner SVG markup, meaning the children of the root `<svg>` element. Heroicons uses the same import name in every size and style (`TrashIcon`). Pass the full variant name, such as `"trash-24-outline"`, to get a specific one.
+
+### `ping`
+
+A health check that returns `{"status":"ok","server":"trueicon"}`.
+
+## Indexing and caching
+
+The first time a tool needs `package@major.minor`, TrueIcon does the following:
+
+1. It downloads the package tarball from `https://registry.npmjs.org`, verifies its sha512 integrity, and extracts it into the cache.
+2. It parses the package's shipped files with the provider's adapter. Nothing is executed. Icons are read from the compiled source.
+3. It writes `index.json` (one record per icon) and `meta.json` (exact version, synonyms hash, index format, build time).
+
+Later calls only read `index.json`. Package files are never touched at query time, and your `node_modules` is never read or modified. If several tool calls need the same index at once, they share one download.
+
+The cache root is `~/.trueicon/cache`, or `$TRUEICON_CACHE` if set:
+
+```
+~/.trueicon/cache/
+├── lucide-react@0.460/          # extracted package + index.json + meta.json
+├── react-icons@5.3/             # extracted package + index.json + meta.json
+├── heroicons-react@2.1/         # extracted @heroicons/react package
+└── @heroicons/react@2.1/        # index.json + meta.json for @heroicons/react
+```
+
+- Downloads go to `<package>@<major.minor>`, where scoped names are flattened: `@heroicons/react` becomes `heroicons-react`. A `.download-complete` marker is written last, and a directory without it is treated as partial and replaced.
+- Indexes go to `<package>@<major.minor>/index.json` and `meta.json`. For unscoped packages this is the same directory as the download.
+- The cache is safe to delete. It is rebuilt on demand, which needs network access.
+
+Each record's `keywords` combine the name parts, the tags, and synonym expansions from the bundled `synonyms.json`. The expansions are added at index time, so `"bin"` finds `Trash2` without any extra work at query time.
+
+## Contributing
+
+```sh
+git clone https://github.com/manikumarkv/trueicon.git
+cd trueicon
+npm ci
+npm run build      # compile to dist/
+npm test           # vitest
+npm run lint       # eslint
+npm run typecheck  # tsc --noEmit
+```
+
+CI runs lint, typecheck and tests on Node 20 and 22 for every push and pull request.
+
+### Extending `synonyms.json`
+
+`src/synonyms/synonyms.json` maps a term to extra search terms:
+
+```json
+{
+  "trash": ["delete", "remove", "bin", "garbage", "rubbish"],
+  "logout": ["sign-out", "signout", "exit", "leave"]
+}
+```
+
+- Keys are matched against an icon's name parts (the name split on `-`) and its tags. `trash-2` matches the key `trash`.
+- Values are added to that icon's `keywords`.
+- Expansion is one-way. If `bin` should also find icons named `delete`, add both `"trash": ["bin"]` and `"delete": ["bin"]`, or add a reverse entry.
+- Write keys and values in lowercase, and give every key a non-empty array of strings. `tests/synonyms.test.ts` checks this.
+- Changing the file changes its hash, so cached indexes rebuild automatically on the next search.
+
+### Adding a provider
+
+1. **Register it** in `src/providers/registry.ts` with a stable `id`, the npm `package` and a short `description`.
+2. **Write an adapter** in `src/providers/adapters/<provider>.ts` that exports `parseIcons(packageDir: string): RawIcon[]` (see `src/providers/adapter.ts`). It gets the extracted package directory and returns one `RawIcon` per icon:
+   - `name`: kebab-case and **unique within the package**, because it becomes part of the record id. Use `toKebabCase` from `adapter.ts`. If the package has variants with clashing component names, add the variant to the name, as the heroicons and react-icons adapters do.
+   - `importName` and `importPath`: the exact export and module specifier a user would import.
+   - `svg`: the inner SVG markup. `LiteralCursor` (`src/providers/jsLiteral.ts`) parses JS object and array literals without executing code. `toSvgAttrs` and `renderSvg` (`src/providers/svg.ts`) turn React props into SVG markup.
+   - Optional `style`, `set`, `categories` and `tags`.
+   - Put a comment at the top of the adapter describing the package's file layout, as the existing adapters do.
+3. **Wire it up** in `src/providers/adapters/index.ts` by adding it to `ADAPTERS` under the provider id.
+4. **Test it.** Add a small pinned fixture under `tests/fixtures/<provider>/` that mirrors the package layout, with a few real icon files plus any files the adapter must skip. Then add `tests/adapters/<provider>.test.ts`, covering name mapping, import paths, SVG output and `buildIndex` record ids like the existing adapter tests. `tests/adapters/common.test.ts` fails if a registered provider has no adapter.
+
+## License
+
+[MIT](LICENSE) © 2026 manikumarkv

package/dist/cache/downloader.d.ts

@@ -0,0 +1,18 @@
+export declare const REGISTRY_URL = "https://registry.npmjs.org";
+export declare const MARKER_FILE = ".download-complete";
+export interface DownloadOptions {
+    cacheRoot?: string;
+}
+export interface DownloadResult {
+    dir: string;
+    version: string;
+}
+export declare function resolveCacheRoot(opts?: DownloadOptions): string;
+export declare function sanitizePackageName(pkg: string): string;
+export declare function cacheDirName(pkg: string, version: string): string;
+/**
+ * Downloads and extracts pkg@version from the npm registry into the local cache (see layout
+ * above). `version` may be an exact version or a dist-tag such as "latest". Returns the
+ * cache dir and the exact version it contains; skips the download if already cached.
+ */
+export declare function downloadPackage(pkg: string, version: string, opts?: DownloadOptions): Promise<DownloadResult>;

package/dist/cache/downloader.js

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { x as extractTar } from "tar";
+/*
+ * Cache layout
+ * ------------
+ * Each downloaded package lives in its own directory:
+ *
+ *   <cacheRoot>/<sanitizedPackage>@<major>.<minor>/
+ *
+ * - cacheRoot: opts.cacheRoot, else $TRUEICON_CACHE, else ~/.trueicon/cache
+ * - sanitizedPackage: package name with the leading "@" removed and "/" replaced by "-"
+ *   (e.g. "@heroicons/react" -> "heroicons-react")
+ * - Only major.minor is kept: patch releases of an icon package share one cache entry
+ *   (e.g. @heroicons/react@1.0.6 -> heroicons-react@1.0).
+ *
+ * The tarball's "package/" prefix is stripped, so <dir>/package.json is the package manifest.
+ * A ".download-complete" marker (containing the exact version) is written last; a directory
+ * without it is treated as a partial download and replaced on the next call.
+ */
+export const REGISTRY_URL = "https://registry.npmjs.org";
+export const MARKER_FILE = ".download-complete";
+const EXACT_VERSION = /^(\d+)\.(\d+)\.\d+(?:[-+].*)?$/;
+// Scoped or unscoped npm package name; rejects anything that could escape the cache root.
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+export function resolveCacheRoot(opts = {}) {
+    return opts.cacheRoot ?? process.env.TRUEICON_CACHE ?? join(homedir(), ".trueicon", "cache");
+}
+export function sanitizePackageName(pkg) {
+    return pkg.replace(/^@/, "").replace(/\//g, "-");
+}
+// Returns the cache directory name for an exact version, e.g. "heroicons-react@1.0".
+export function cacheDirName(pkg, version) {
+    const match = EXACT_VERSION.exec(version);
+    if (!match)
+        throw new Error(`Expected an exact semver version for ${pkg}, got "${version}"`);
+    return `${sanitizePackageName(pkg)}@${match[1]}.${match[2]}`;
+}
+async function readMarker(dir) {
+    try {
+        return (await readFile(join(dir, MARKER_FILE), "utf8")).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchOrThrow(url, what) {
+    try {
+        return await fetch(url);
+    }
+    catch (error) {
+        throw new Error(`Network error fetching ${what} from ${url}: ${String(error)}`, { cause: error });
+    }
+}
+async function fetchVersionMetadata(pkg, version) {
+    const url = `${REGISTRY_URL}/${pkg}/${encodeURIComponent(version)}`;
+    const res = await fetchOrThrow(url, `metadata for ${pkg}@${version}`);
+    if (res.status === 404)
+        throw new Error(`Unknown package or version: ${pkg}@${version}`);
+    if (!res.ok)
+        throw new Error(`Registry returned HTTP ${res.status} for ${pkg}@${version}`);
+    const meta = (await res.json());
+    if (!meta.dist?.tarball)
+        throw new Error(`Registry metadata for ${pkg}@${version} has no dist.tarball`);
+    return meta;
+}
+// Verifies an SRI string's sha512 entry (if any) against the tarball bytes.
+function verifyIntegrity(data, integrity, label) {
+    const expected = integrity
+        ?.split(/\s+/)
+        .find((entry) => entry.startsWith("sha512-"))
+        ?.slice("sha512-".length);
+    if (!expected)
+        return;
+    const actual = createHash("sha512").update(data).digest("base64");
+    if (actual !== expected) {
+        throw new Error(`Integrity check failed for ${label}: expected sha512-${expected}, got sha512-${actual}`);
+    }
+}
+/**
+ * Downloads and extracts pkg@version from the npm registry into the local cache (see layout
+ * above). `version` may be an exact version or a dist-tag such as "latest". Returns the
+ * cache dir and the exact version it contains; skips the download if already cached.
+ */
+export async function downloadPackage(pkg, version, opts = {}) {
+    if (!PACKAGE_NAME.test(pkg))
+        throw new Error(`Invalid npm package name: "${pkg}"`);
+    const cacheRoot = resolveCacheRoot(opts);
+    // Exact versions can be checked against the cache without touching the network.
+    if (EXACT_VERSION.test(version)) {
+        const dir = join(cacheRoot, cacheDirName(pkg, version));
+        const cached = await readMarker(dir);
+        if (cached)
+            return { dir, version: cached };
+    }
+    const meta = await fetchVersionMetadata(pkg, version);
+    const dir = join(cacheRoot, cacheDirName(pkg, meta.version));
+    const cached = await readMarker(dir);
+    if (cached)
+        return { dir, version: cached };
+    const label = `${pkg}@${meta.version}`;
+    const tarballUrl = meta.dist.tarball;
+    const res = await fetchOrThrow(tarballUrl, `tarball for ${label}`);
+    if (!res.ok)
+        throw new Error(`Tarball download for ${label} failed with HTTP ${res.status}`);
+    let data;
+    try {
+        data = Buffer.from(await res.arrayBuffer());
+    }
+    catch (error) {
+        throw new Error(`Network error reading tarball for ${label}: ${String(error)}`, { cause: error });
+    }
+    verifyIntegrity(data, meta.dist.integrity, label);
+    // Clear any partial previous attempt, then extract (dropping the tarball's "package/" prefix).
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    try {
+        await pipeline(Readable.from(data), extractTar({ cwd: dir, strip: 1 }));
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw new Error(`Failed to extract tarball for ${label}: ${String(error)}`, { cause: error });
+    }
+    await writeFile(join(dir, MARKER_FILE), `${meta.version}\n`);
+    return { dir, version: meta.version };
+}
+//# sourceMappingURL=downloader.js.map

package/dist/cache/downloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloader.js","sourceRoot":"","sources":["../../src/cache/downloader.ts"],"names":[],"mappings":"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"}

package/dist/config/ensureIndex.d.ts

@@ -0,0 +1,16 @@
+import type { Synonyms } from "../indexer/types.js";
+import { type IndexAction } from "./versions.js";
+export interface EnsureIndexOptions {
+    cacheRoot: string;
+    providerId: string;
+    packageName: string;
+    /** Exact version or npm range, e.g. "^0.460.0". */
+    version: string;
+    synonyms: Synonyms;
+}
+export interface EnsureIndexResult {
+    cacheDir: string;
+    action: IndexAction;
+}
+/** Makes sure an up-to-date index for packageName@version exists under cacheRoot. */
+export declare function ensureIndex(opts: EnsureIndexOptions): Promise<EnsureIndexResult>;

package/dist/config/ensureIndex.js

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { downloadPackage } from "../cache/downloader.js";
+import { buildIndexFromPackage, hashSynonyms, META_FILE } from "../indexer/buildIndex.js";
+import { indexKey, parseVersion, resolveIndexAction } from "./versions.js";
+// meta.json is written last by writeIndex, so its presence marks a complete index.
+async function readMeta(cacheDir) {
+    try {
+        return JSON.parse(await readFile(join(cacheDir, META_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// In-progress builds by index dir, so concurrent tool calls share one download instead of racing.
+const inFlight = new Map();
+/** Makes sure an up-to-date index for packageName@version exists under cacheRoot. */
+export function ensureIndex(opts) {
+    const cacheDir = join(opts.cacheRoot, indexKey(opts.packageName, opts.version));
+    const pending = inFlight.get(cacheDir);
+    if (pending)
+        return pending;
+    const run = ensureIndexAt(cacheDir, opts).finally(() => inFlight.delete(cacheDir));
+    inFlight.set(cacheDir, run);
+    return run;
+}
+async function ensureIndexAt(cacheDir, opts) {
+    const { cacheRoot, providerId, packageName, version, synonyms } = opts;
+    const action = resolveIndexAction(version, await readMeta(cacheDir), hashSynonyms(synonyms));
+    if (action === "use")
+        return { cacheDir, action };
+    // Download the range's base version exactly so the result lands under the same index key.
+    const { major, minor, patch } = parseVersion(version);
+    const downloaded = await downloadPackage(packageName, `${major}.${minor}.${patch}`, { cacheRoot });
+    const built = await buildIndexFromPackage(downloaded.dir, providerId, downloaded.version, cacheRoot, synonyms);
+    if (built.dir !== cacheDir) {
+        throw new Error(`Index for ${packageName}@${version} was written to ${built.dir}, expected ${cacheDir}`);
+    }
+    return { cacheDir, action };
+}
+//# sourceMappingURL=ensureIndex.js.map

package/dist/config/ensureIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureIndex.js","sourceRoot":"","sources":["../../src/config/ensureIndex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,kBAAkB,EAAoB,MAAM,eAAe,CAAC;AAgB7F,mFAAmF;AACnF,KAAK,UAAU,QAAQ,CAAC,QAAgB;IACtC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAc,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,kGAAkG;AAClG,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsC,CAAC;AAE/D,qFAAqF;AACrF,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAChF,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnF,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,IAAwB;IACrE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACvE,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7F,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAElD,0FAA0F;IAC1F,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,WAAW,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACnG,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/G,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,aAAa,WAAW,IAAI,OAAO,mBAAmB,KAAK,CAAC,GAAG,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}

package/dist/config/loadConfig.d.ts

@@ -0,0 +1,12 @@
+export declare const CONFIG_FILE = ".iconmcp.json";
+export interface ProviderConfig {
+    package: string;
+    version?: string;
+}
+export interface ProjectConfig {
+    providers: ProviderConfig[];
+}
+/** Reads <projectDir>/.iconmcp.json; a missing file means no configured providers. */
+export declare function loadProjectConfig(projectDir: string): ProjectConfig;
+/** Returns the version range declared for packageName in <projectDir>/package.json. */
+export declare function detectVersion(projectDir: string, packageName: string): string;