logomarks 1.1.0 → 2.0.0

package/src/live/ensure.js

@@ -0,0 +1,92 @@
+/**
+ * @module logomarks/live/ensure
+ *
+ * Getting the live set: `LOGOMARKS_INDEX` when set; else the cached index,
+ * re-checked against the site's manifest at most once a day; else downloaded
+ * from logomarks.ai (or `LOGOMARKS_INDEX_URL`), verified by sha256 and cached.
+ * Offline (`--offline`, `LOGOMARKS_OFFLINE=1`) uses the cache alone. When the
+ * site can't be reached or sends a bad file, a cached index is used with a
+ * warning; `force` (`logomarks update`) fails instead.
+ */
+
+import fs from 'node:fs';
+import { IndexError } from './errors.js';
+import { INDEX_FORMAT, formatError, indexHeader } from './format.js';
+import { cacheDir, indexUrl, isOn, localIndex, manifestUrl, MAX_AGE } from './paths.js';
+import { readCache, saveCache, saveRecord } from './cache.js';
+import { fetchIndex, fetchManifest, sha256, TIMEOUT } from './remote.js';
+import { useIndexFile, indexUnavailable } from './current.js';
+
+/**
+ * Settles on an index file for this process.
+ *
+ * @param {import('./ensure.js').IndexStatus} status Where it is and how it was had.
+ * @returns {import('./ensure.js').IndexStatus} The same.
+ */
+function settle(status) {
+	useIndexFile(status.file);
+	return status;
+}
+
+/**
+ * The live set's index file: local, cached, or downloaded and cached. It becomes the file `loadIndex()` reads.
+ *
+ * @param {import('./ensure.js').EnsureOptions} [o] Whether to force a check, stay offline, and where to look.
+ * @returns {Promise<import('./ensure.js').IndexStatus>} The file and how it was had.
+ * @throws {IndexError} When there's no index to use: `missing`, `offline`, `network`, `checksum` or `format`.
+ */
+export async function ensureIndex({ force = false, offline, env = process.env, url = indexUrl(env), dir = cacheDir({ env }), maxAge = MAX_AGE, timeout = TIMEOUT, now = Date.now(), warn = () => {} } = {}) {
+	const local = localIndex(env);
+	if (local) {
+		if (!fs.existsSync(local)) throw new IndexError('missing', `LOGOMARKS_INDEX names ${local}, which doesn't exist`);
+		return settle({ file: local, source: 'file', checked: false });
+	}
+	const cached = readCache(dir);
+	const fromCache = (checked = false) => settle({ file: /** @type {NonNullable<typeof cached>} */ (cached).file, source: 'cache', checked, manifest: cached?.record });
+	if (offline ?? isOn(env.LOGOMARKS_OFFLINE)) {
+		if (force) throw new IndexError('offline', 'updating the index needs the network: run it without --offline or LOGOMARKS_OFFLINE');
+		if (!cached) throw new IndexError('offline', `offline, and no index is cached in ${dir}: run logomarks update once online, or set LOGOMARKS_INDEX to an index file`);
+		return fromCache();
+	}
+	if (cached && !force && cached.record.url === url && now - cached.record.checked < maxAge) return fromCache();
+	try {
+		const manifest = await fetchManifest(manifestUrl(url), { timeout });
+		if (manifest.format !== INDEX_FORMAT) throw formatError(manifest.format);
+		const record = { format: manifest.format, marks: manifest.marks, letters: manifest.letters, bytes: manifest.bytes, sha256: manifest.sha256, built: manifest.built, url, checked: now };
+		if (cached && sha256(fs.readFileSync(cached.file)) === manifest.sha256) {
+			saveRecord(dir, record);
+			cached.record = record;
+			return fromCache(true);
+		}
+		const bytes = await fetchIndex(url, manifest, { timeout });
+		indexHeader(bytes);
+		return settle({ file: saveCache(dir, bytes, record), source: 'download', checked: true, manifest: record });
+	} catch (e) {
+		if (force || !cached || !(e instanceof IndexError)) {
+			if (e instanceof IndexError && e.code === 'network' && !cached) {
+				throw new IndexError('network', `${e.message}. The first run downloads the Logomarks index (about 3 MB) and caches it in ${dir}; after that it works offline. Without a network, set LOGOMARKS_INDEX to an index file`);
+			}
+			throw e;
+		}
+		warn(`logomarks: ${e.message}; using the cached index (built ${cached.record.built})`);
+		return fromCache();
+	}
+}
+
+/** The process's one `ensureIndex` run, shared by every command and tool call. */
+let pending = /** @type {Promise<import('./ensure.js').IndexStatus | undefined> | undefined} */ (undefined);
+
+/**
+ * Runs `ensureIndex` once per process and never throws: a failure is recorded, and `loadIndex()` throws it if and
+ * when something needs the live set (so `check mark.svg` works offline with nothing cached).
+ *
+ * @param {import('./ensure.js').EnsureOptions} [o] As `ensureIndex` (the first call's options win).
+ * @returns {Promise<import('./ensure.js').IndexStatus | undefined>} The status, or undefined when it failed.
+ */
+export function prepareIndex(o) {
+	pending ??= ensureIndex(o).catch((e) => {
+		indexUnavailable(e);
+		return undefined;
+	});
+	return pending;
+}

package/src/live/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Why the live set couldn't be had:
+ * - `missing`: no index yet (or `LOGOMARKS_INDEX` names no file);
+ * - `offline`: offline and nothing cached, or `update` asked for while offline;
+ * - `network`: the site couldn't be reached, or answered with an error;
+ * - `checksum`: the download didn't match the manifest's sha256 or size (nothing was saved);
+ * - `format`: the index is in a format this version of logomarks doesn't read.
+ */
+export type IndexErrorCode = 'missing' | 'offline' | 'network' | 'checksum' | 'format';
+
+/** The live set is missing, unreachable, corrupt or in a format this version can't read. */
+export class IndexError extends Error {
+	constructor(code: IndexErrorCode, message: string);
+	readonly name: 'IndexError';
+	readonly code: IndexErrorCode;
+}

package/src/live/errors.js

@@ -0,0 +1,19 @@
+/**
+ * @module logomarks/live/errors
+ *
+ * Why the live set couldn't be had, as one error with a code the CLI and the
+ * MCP server can tell apart, and a message that says what to do.
+ */
+
+/** The live set is missing, unreachable, corrupt or in a format this version can't read. */
+export class IndexError extends Error {
+	/**
+	 * @param {import('./errors.js').IndexErrorCode} code What went wrong.
+	 * @param {string} message What to do about it.
+	 */
+	constructor(code, message) {
+		super(message);
+		this.name = 'IndexError';
+		this.code = code;
+	}
+}

package/src/live/format.d.ts

@@ -0,0 +1,13 @@
+import type { IndexInput, MarkIndex } from '../similar/store.js';
+import type { IndexError } from './errors.js';
+
+/** The index format this version of logomarks writes and reads. */
+export const INDEX_FORMAT: number;
+/** The error for a file in another format (code `format`), saying how to update. */
+export function formatError(format: unknown): IndexError;
+/** An index's bytes (brotli), built today unless `built` (YYYY-MM-DD) is given. */
+export function encodeIndex(input: IndexInput, o?: { built?: string }): Buffer;
+/** An index's format, build date and counts, without reading its signatures. Throws an `IndexError` when it isn't an index or is in another format. */
+export function indexHeader(bytes: Uint8Array): { format: number; built: string; marks: number; letters: number };
+/** An index read back. Throws an `IndexError` when it isn't an index or is in another format. */
+export function decodeIndex(bytes: Uint8Array): MarkIndex;

package/src/live/format.js

@@ -0,0 +1,113 @@
+/**
+ * @module logomarks/live/format
+ *
+ * The index file's format: brotli over a 4-byte JSON length, the JSON (the
+ * format version, the build date, each mark and the packed search), then the
+ * signature bytes (48 px coverages ×255, letter signatures ×4). The version is
+ * checked on every read, so a CLI never misreads a file in a newer format.
+ */
+
+import zlib from 'node:zlib';
+import { SIMILAR, LETTERS } from '../rules.js';
+import { blur } from '../similar/signature.js';
+import { IndexError } from './errors.js';
+
+/** The format this version of logomarks writes and reads. Bump it with any change to the layout or the JSON. */
+export const INDEX_FORMAT = 3;
+
+/** Letter signatures are quarters (2×2 supersampling): stored ×4. */
+const QUARTERS = 4;
+
+/** Where to get a CLI that reads a newer format. */
+const UPGRADE = 'update logomarks (npm i -g logomarks@latest, or run npx logomarks@latest)';
+
+/**
+ * The error for a file in another format.
+ *
+ * @param {unknown} format The file's format.
+ * @returns {IndexError} The error, saying what to do.
+ */
+export function formatError(format) {
+	return new IndexError('format', `the index is format ${format}, and this version of logomarks reads format ${INDEX_FORMAT}: ${UPGRADE}`);
+}
+
+/**
+ * An index's bytes: what `decodeIndex` reads.
+ *
+ * @param {import('../similar/store.js').IndexInput} input The marks, their signatures and the packed search.
+ * @param {{ built?: string }} [o] The build date (YYYY-MM-DD; today).
+ * @returns {Buffer} The file's bytes (brotli).
+ */
+export function encodeIndex({ marks, coverages, letters, search }, { built = new Date().toISOString().slice(0, 10) } = {}) {
+	const head = Buffer.from(JSON.stringify({
+		version: INDEX_FORMAT,
+		built,
+		size: SIMILAR.size,
+		letterSize: LETTERS.size,
+		marks: marks.map(({ slug, name, svg, ...about }) => [slug, name, svg, about]),
+		letters: letters.map((l) => [l.mark, l.kind]),
+		search,
+	}));
+	const length = Buffer.alloc(4);
+	length.writeUInt32LE(head.length);
+	const bytes = (/** @type {ArrayLike<number>} */ a, /** @type {number} */ k) => Uint8Array.from(a, (v) => Math.round(v * k));
+	const body = Buffer.concat([length, head, ...coverages.map((c) => bytes(c, 255)), ...letters.map((l) => bytes(l.sig, QUARTERS))]);
+	return zlib.brotliCompressSync(body, { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 } });
+}
+
+/**
+ * An index's body and its JSON head, its format checked.
+ *
+ * @param {Uint8Array} bytes The file's bytes.
+ * @returns {{ body: Buffer, raw: any, at: number }} The body, the head and where the signatures start.
+ * @throws {IndexError} When it isn't an index, or is in another format.
+ */
+function open(bytes) {
+	let body, raw;
+	try {
+		body = zlib.brotliDecompressSync(bytes);
+		const n = body.readUInt32LE(0);
+		raw = JSON.parse(body.toString('utf8', 4, 4 + n));
+		if (raw.version !== INDEX_FORMAT) throw formatError(raw.version);
+		return { body, raw, at: 4 + n };
+	} catch (e) {
+		if (e instanceof IndexError) throw e;
+		throw new IndexError('checksum', `not a Logomarks index (${/** @type {Error} */ (e).message}): run logomarks update`);
+	}
+}
+
+/**
+ * An index's format and build date, without reading the marks' signatures.
+ *
+ * @param {Uint8Array} bytes The file's bytes.
+ * @returns {{ format: number, built: string, marks: number, letters: number }} What it is.
+ * @throws {IndexError} When it isn't an index, or is in another format.
+ */
+export function indexHeader(bytes) {
+	const { raw } = open(bytes);
+	return { format: raw.version, built: raw.built, marks: raw.marks.length, letters: raw.letters.length };
+}
+
+/**
+ * An index read back, its coverages blurred into outline signatures.
+ *
+ * @param {Uint8Array} bytes The file's bytes.
+ * @returns {import('../similar/store.js').MarkIndex} The index.
+ * @throws {IndexError} When it isn't an index, or is in another format.
+ */
+export function decodeIndex(bytes) {
+	const { body, raw, at: start } = open(bytes);
+	const S = raw.size * raw.size, L = raw.letterSize * raw.letterSize;
+	let at = start;
+	const take = (/** @type {number} */ len, /** @type {number} */ k) => {
+		const a = Float32Array.from(body.subarray(at, at + len), (v) => v / k);
+		at += len;
+		return a;
+	};
+	return {
+		built: raw.built,
+		marks: raw.marks.map((/** @type {[string, string, string, import('../similar/store.js').MarkAbout]} */ [slug, name, svg, about]) => ({ slug, name, svg, ...about, outline: blur(take(S, 255), raw.size) })),
+		letters: raw.letters.map((/** @type {[number, 'hole' | 'ink']} */ [mark, kind]) => ({ mark, kind, sig: take(L, QUARTERS) })),
+		search: raw.search,
+	};
+}

package/src/live/index.d.ts

@@ -0,0 +1,7 @@
+export { IndexError, type IndexErrorCode } from './errors.js';
+export { INDEX_FORMAT, encodeIndex, decodeIndex, indexHeader } from './format.js';
+export { DEFAULT_INDEX_URL, MAX_AGE, cacheDir, indexUrl, manifestUrl } from './paths.js';
+export { ensureIndex, prepareIndex, type EnsureOptions, type IndexStatus } from './ensure.js';
+export { buildIndex, type BuildInput, type BuildMark, type BuiltIndex } from './build.js';
+export type { Manifest } from './remote.js';
+export type { CacheRecord } from './cache.js';

package/src/live/index.js

@@ -0,0 +1,12 @@
+/**
+ * @module logomarks/live
+ *
+ * The live set's index: where it comes from (the site, a cache, a local
+ * file), its format, and building it (for the site and the monorepo).
+ */
+
+export { IndexError } from './errors.js';
+export { INDEX_FORMAT, encodeIndex, decodeIndex, indexHeader } from './format.js';
+export { DEFAULT_INDEX_URL, MAX_AGE, cacheDir, indexUrl, manifestUrl } from './paths.js';
+export { ensureIndex, prepareIndex } from './ensure.js';
+export { buildIndex } from './build.js';

package/src/live/paths.d.ts

@@ -0,0 +1,17 @@
+/** Where the site serves the index (`https://logomarks.ai/cli/index.bin`). Its manifest, `index.json`, sits beside it. */
+export const DEFAULT_INDEX_URL: string;
+/** How long a checked index counts as fresh, in ms: a day. */
+export const MAX_AGE: number;
+/** Whether an environment flag is on: `1`, `true` or `yes`, any case. */
+export function isOn(value: string | undefined): boolean;
+/** The index's URL: `LOGOMARKS_INDEX_URL`, or the site's. */
+export function indexUrl(env?: NodeJS.ProcessEnv): string;
+/** The manifest's URL: `index.json` in the index's folder. */
+export function manifestUrl(url: string): string;
+/** A local index file to use instead of the cache (`LOGOMARKS_INDEX`), as an absolute path; undefined when unset. */
+export function localIndex(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The user's cache folder for logomarks: `$XDG_CACHE_HOME/logomarks` when set; otherwise `~/Library/Caches/logomarks`
+ * on macOS, `%LOCALAPPDATA%\logomarks\Cache` on Windows and `~/.cache/logomarks` elsewhere.
+ */
+export function cacheDir(o?: { env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform; home?: string }): string;

package/src/live/paths.js

@@ -0,0 +1,64 @@
+/**
+ * @module logomarks/live/paths
+ *
+ * Where the live set comes from and where it is kept: the site's URL (or
+ * `LOGOMARKS_INDEX_URL`), a local file (`LOGOMARKS_INDEX`), whether to stay
+ * offline (`LOGOMARKS_OFFLINE`), and the user's cache folder for this platform.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+/** Where the site serves the index. Its manifest, `index.json`, sits beside it. */
+export const DEFAULT_INDEX_URL = 'https://logomarks.ai/cli/index.bin';
+
+/** How long a checked index counts as fresh: a day. */
+export const MAX_AGE = 24 * 60 * 60 * 1000;
+
+/**
+ * Whether an environment flag is on: `1`, `true` or `yes`, any case.
+ *
+ * @param {string | undefined} value The variable's value.
+ * @returns {boolean} Whether it is on.
+ */
+export const isOn = (value) => /^(1|true|yes)$/i.test(value?.trim() ?? '');
+
+/**
+ * The index's URL: `LOGOMARKS_INDEX_URL`, or the site's.
+ *
+ * @param {NodeJS.ProcessEnv} [env] The environment.
+ * @returns {string} The URL.
+ */
+export const indexUrl = (env = process.env) => env.LOGOMARKS_INDEX_URL?.trim() || DEFAULT_INDEX_URL;
+
+/**
+ * The manifest's URL: `index.json` in the index's folder.
+ *
+ * @param {string} url The index's URL.
+ * @returns {string} The manifest's.
+ */
+export const manifestUrl = (url) => new URL('index.json', url).href;
+
+/**
+ * A local index file to use instead of the cache (`LOGOMARKS_INDEX`), resolved.
+ *
+ * @param {NodeJS.ProcessEnv} [env] The environment.
+ * @returns {string | undefined} Its absolute path, or undefined when it isn't set.
+ */
+export const localIndex = (env = process.env) => (env.LOGOMARKS_INDEX?.trim() ? path.resolve(env.LOGOMARKS_INDEX.trim()) : undefined);
+
+/**
+ * The user's cache folder for logomarks: `$XDG_CACHE_HOME/logomarks` when set; otherwise
+ * `~/Library/Caches/logomarks` on macOS, `%LOCALAPPDATA%\logomarks\Cache` on Windows and `~/.cache/logomarks` elsewhere.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string }} [o] The environment, platform and
+ *   home folder (the process's).
+ * @returns {string} The folder (it may not exist yet).
+ */
+export function cacheDir({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+	const p = platform === 'win32' ? path.win32 : path.posix;
+	if (env.XDG_CACHE_HOME?.trim()) return p.join(env.XDG_CACHE_HOME.trim(), 'logomarks');
+	if (platform === 'darwin') return p.join(home, 'Library', 'Caches', 'logomarks');
+	if (platform === 'win32') return p.join(env.LOCALAPPDATA?.trim() || p.join(home, 'AppData', 'Local'), 'logomarks', 'Cache');
+	return p.join(home, '.cache', 'logomarks');
+}

package/src/live/remote.d.ts

@@ -0,0 +1,24 @@
+/** What the site says about the index it serves (`/cli/index.json`). */
+export interface Manifest {
+	/** The index's format (`INDEX_FORMAT`). */
+	format: number;
+	/** How many marks it holds. */
+	marks: number;
+	/** How many letter signatures. */
+	letters?: number;
+	/** Its size in bytes. */
+	bytes: number;
+	/** Its sha256, in hex. */
+	sha256: string;
+	/** When it was built (YYYY-MM-DD). */
+	built: string;
+}
+
+/** How long one request may take, in ms (30 s). */
+export const TIMEOUT: number;
+/** Bytes' sha256, in hex. */
+export function sha256(bytes: Uint8Array): string;
+/** The site's manifest. Throws an `IndexError` (`network`) when it can't be fetched or isn't one. */
+export function fetchManifest(url: string, o?: { timeout?: number }): Promise<Manifest>;
+/** The index a manifest describes, its size and sha256 checked. Throws an `IndexError`: `network` or `checksum`. */
+export function fetchIndex(url: string, manifest: Manifest, o?: { timeout?: number }): Promise<Uint8Array>;

package/src/live/remote.js

@@ -0,0 +1,109 @@
+/**
+ * @module logomarks/live/remote
+ *
+ * The site's side: the manifest (`index.json`: the format, the counts, the
+ * size, the sha256 and the build date) and the index it describes, fetched
+ * with a timeout (global `fetch`) and verified against the manifest.
+ */
+
+import { createHash } from 'node:crypto';
+import { IndexError } from './errors.js';
+import { VERSION } from '../util/version.js';
+
+/** How long one request may take, in ms. */
+export const TIMEOUT = 30_000;
+
+/** Sent with every request, so the site's logs can tell CLI versions apart. */
+const HEADERS = { 'user-agent': `logomarks/${VERSION} (+https://logomarks.ai/agents)` };
+
+/**
+ * Bytes' sha256, in hex.
+ *
+ * @param {Uint8Array} bytes The bytes.
+ * @returns {string} The digest (64 hex digits).
+ */
+export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/**
+ * Why a request failed, in a few words.
+ *
+ * @param {unknown} e The error `fetch` threw.
+ * @returns {string} The reason.
+ */
+function reason(e) {
+	const err = /** @type {Error & { cause?: { code?: string, message?: string } }} */ (e);
+	if (err?.name === 'TimeoutError') return 'timed out';
+	return err?.cause?.code ?? err?.cause?.message ?? err?.message ?? String(e);
+}
+
+/**
+ * A URL fetched, as an `IndexError` (`network`) when it can't be reached or answers with an error.
+ *
+ * @param {string} url The URL.
+ * @param {number} timeout How long it may take, in ms.
+ * @returns {Promise<Response>} The response (2xx).
+ * @throws {IndexError} When it fails.
+ */
+async function get(url, timeout) {
+	let res;
+	try {
+		res = await fetch(url, { headers: HEADERS, signal: AbortSignal.timeout(timeout) });
+	} catch (e) {
+		throw new IndexError('network', `couldn't reach ${url} (${reason(e)})`);
+	}
+	if (!res.ok) throw new IndexError('network', `${url} answered ${res.status} ${res.statusText}`.trim());
+	return res;
+}
+
+/**
+ * Whether a value is a manifest.
+ *
+ * @param {any} m The value.
+ * @returns {m is import('./remote.js').Manifest} Whether it has every field, of the right type.
+ */
+const isManifest = (m) =>
+	!!m && Number.isInteger(m.format) && Number.isInteger(m.marks) && Number.isInteger(m.bytes) && typeof m.built === 'string' && /^[0-9a-f]{64}$/.test(m.sha256);
+
+/**
+ * The site's manifest.
+ *
+ * @param {string} url The manifest's URL.
+ * @param {{ timeout?: number }} [o] How long it may take.
+ * @returns {Promise<import('./remote.js').Manifest>} The manifest.
+ * @throws {IndexError} When it can't be fetched (`network`) or isn't a manifest (`network`).
+ */
+export async function fetchManifest(url, { timeout = TIMEOUT } = {}) {
+	const res = await get(url, timeout);
+	let m;
+	try {
+		m = await res.json();
+	} catch {
+		m = null;
+	}
+	if (!isManifest(m)) throw new IndexError('network', `${url} isn't a Logomarks index manifest`);
+	return m;
+}
+
+/**
+ * The index a manifest describes, its size and sha256 checked.
+ *
+ * @param {string} url The index's URL.
+ * @param {import('./remote.js').Manifest} manifest What it must match.
+ * @param {{ timeout?: number }} [o] How long it may take.
+ * @returns {Promise<Uint8Array>} The verified bytes.
+ * @throws {IndexError} When it can't be fetched (`network`) or doesn't match (`checksum`).
+ */
+export async function fetchIndex(url, manifest, { timeout = TIMEOUT } = {}) {
+	const res = await get(url, timeout);
+	let bytes;
+	try {
+		bytes = new Uint8Array(await res.arrayBuffer());
+	} catch (e) {
+		throw new IndexError('network', `the download from ${url} broke off (${reason(e)})`);
+	}
+	const sum = sha256(bytes);
+	if (bytes.length !== manifest.bytes || sum !== manifest.sha256) {
+		throw new IndexError('checksum', `the index from ${url} doesn't match its manifest (sha256 ${sum.slice(0, 12)}…, ${bytes.length} bytes; expected ${manifest.sha256.slice(0, 12)}…, ${manifest.bytes} bytes), so it wasn't saved: try again later with logomarks update`);
+	}
+	return bytes;
+}

package/src/mcp/index.d.ts

@@ -27,15 +27,17 @@ export interface Tool<Input = Record<string, unknown>> {
 export interface ServerOptions {
 	/** Where relative paths resolve (the process's working folder). */
 	cwd?: string;
+	/** Use the cached set alone, never the network (default: `LOGOMARKS_OFFLINE`). */
+	offline?: boolean;
 }
 
 /** Every tool, in the order an agent uses them. */
 export const TOOLS: Tool<never>[];
 /** What the server tells the agent when it connects. */
 export const INSTRUCTIONS: string;
-/** An MCP server with every tool registered, not yet connected. */
+/** An MCP server with every tool registered, not yet connected. Each tool call first waits for the live set (cached or downloaded). */
 export function createServer(o?: ServerOptions): McpServer;
-/** Loads the renderer, the typefaces and the live set. */
-export function warm(): Promise<void>;
+/** Gets and loads the live set, and loads the renderer and the typefaces; rejects when the set can't be had. */
+export function warm(o?: Pick<ServerOptions, 'offline'>): Promise<void>;
 /** Runs the server over stdio until the client hangs up. */
 export function serve(o?: ServerOptions): Promise<McpServer>;

package/src/mcp/index.js

@@ -3,8 +3,11 @@
  *
  * The MCP server: the library's functions as typed tools for an AI agent
  * (Claude Code, Codex, Cursor …), over stdio. It runs on the user's machine;
- * nothing leaves it. The renderer, the typefaces and the live set load once
- * and stay warm across calls. `logomarks mcp` starts it.
+ * nothing leaves it. The live set is the CLI's (cached, or downloaded from
+ * logomarks.ai on first use: every tool call waits for it, and one that needs
+ * it fails with the reason when it can't be had). The renderer, the typefaces
+ * and the live set load once and stay warm across calls. `logomarks mcp`
+ * starts it.
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -12,32 +15,42 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { TOOLS } from './tools/index.js';
 import { failure } from './content.js';
 import { loadIndex } from '../similar/store.js';
+import { prepareIndex } from '../live/ensure.js';
 import { warmRenderer } from '../raster/render.js';
 import { VERSION } from '../util/version.js';
 
 export { TOOLS };
 
 /** What the server tells the agent when it connects. */
-export const INSTRUCTIONS = `Logomarks: the free Logomarks set of geometric logomarks (CC0, bundled, searched offline), and the checks the set is held to, run locally.
+export const INSTRUCTIONS = `Logomarks: the free Logomarks set of geometric logomarks (CC0; downloaded from logomarks.ai on first use, then cached and searched locally), and the checks the set is held to, run locally.
 - Pick a mark: find_marks, then get_mark.
 - Draw your own: write the SVG to the house rules (512 canvas, longest side 448, centred; filled paths in currentColor; one gap of 22; nothing under 10 units), then check_mark, similar_marks and review_sheet. Fix every error, look at the sheet, and repeat until check_mark is ok.
 - Make it your own: list_parts, then edit_mark (delete, move, round, offset, mirror, two-tone …), glitch_mark, combine_marks. Each result is fitted and checked.
 - Build on a mark: build_brand_kit and build_social_pack (folders of files), render_mockup, render_cover.
 Tools that make images return a preview to look at; pass out to write the file. Relative paths resolve against the server's working folder. The full brand kit, photoreal mockups and custom logos are at https://logomarks.ai/pricing.`;
 
+/**
+ * Gets the live set once per process (see `prepareIndex`), warnings to stderr (stdout is the protocol's).
+ *
+ * @param {boolean | undefined} offline Use the cache alone.
+ * @returns {Promise<unknown>} Resolves when it's settled, had or not.
+ */
+const ready = (offline) => prepareIndex({ offline, warn: (m) => console.error(m) });
+
 /**
  * An MCP server with every tool registered. Errors come back as tool errors
  * (`isError`) with a message the agent can act on.
  *
- * @param {import('./index.js').ServerOptions} [o] Where relative paths resolve.
+ * @param {import('./index.js').ServerOptions} [o] Where relative paths resolve, and whether to stay offline.
  * @returns {McpServer} The server, not yet connected.
  */
-export function createServer({ cwd = process.cwd() } = {}) {
+export function createServer({ cwd = process.cwd(), offline } = {}) {
 	const server = new McpServer({ name: 'logomarks', title: 'Logomarks', version: VERSION, websiteUrl: 'https://logomarks.ai' }, { instructions: INSTRUCTIONS });
 	for (const t of TOOLS) {
 		const run = /** @type {(args: object, ctx: import('./index.js').ToolContext) => Promise<import('./content.js').ToolResult>} */ (t.run);
 		server.registerTool(t.name, { title: t.title, description: t.description, inputSchema: t.inputSchema, annotations: t.annotations }, async (args) => {
 			try {
+				await ready(offline);
 				return await run(args, { cwd });
 			} catch (e) {
 				return failure(e);
@@ -48,25 +61,25 @@ export function createServer({ cwd = process.cwd() } = {}) {
 }
 
 /**
- * Loads the renderer, the typefaces and the live set in the background, so
- * the first call is as quick as the rest.
+ * Gets and loads the live set, the renderer and the typefaces in the background, so the first call is as quick as
+ * the rest.
  *
- * @returns {Promise<void>} Resolves when all three are ready.
+ * @param {Pick<import('./index.js').ServerOptions, 'offline'>} [o] Whether to stay offline.
+ * @returns {Promise<void>} Resolves when all three are ready; rejects when the live set can't be had.
  */
-export async function warm() {
-	loadIndex();
-	await warmRenderer();
+export async function warm({ offline } = {}) {
+	await Promise.all([ready(offline).then(() => loadIndex()), warmRenderer()]);
 }
 
 /**
  * Runs the server on stdin and stdout until the client hangs up.
  *
- * @param {import('./index.js').ServerOptions} [o] Where relative paths resolve.
+ * @param {import('./index.js').ServerOptions} [o] Where relative paths resolve, and whether to stay offline.
  * @returns {Promise<McpServer>} The connected server.
  */
 export async function serve(o) {
 	const server = createServer(o);
 	await server.connect(new StdioServerTransport());
-	setImmediate(() => warm().catch((e) => console.error(`logomarks: ${e.message}`)));
+	setImmediate(() => warm(o).catch((e) => console.error(`logomarks: ${e.message}`)));
 	return server;
 }

package/src/mcp/tools/find.js

@@ -1,7 +1,7 @@
 /**
  * @module logomarks/mcp/tools/find
  *
- * `find_marks`: search the bundled live set by words and filters.
+ * `find_marks`: search the live set by words and filters.
  */
 
 import { z } from 'zod';
@@ -13,7 +13,7 @@ export const tool = {
 	name: 'find_marks',
 	title: 'Find live Logomarks',
 	description: [
-		'Search the free Logomarks set (geometric logomarks, CC0, bundled offline): use it first when someone needs a logo, icon or brand mark, or a mark to build on.',
+		'Search the free Logomarks set (geometric logomarks, CC0; downloaded from logomarks.ai on first use, then cached and searched locally): use it first when someone needs a logo, icon or brand mark, or a mark to build on.',
 		'Search works as on logomarks.ai: every word must be found in a mark (its name, search words, industries, style, tags, mood, letter or description), trades by their UK and US names too ("solicitor" finds the lawyers\' marks); the best fits come first. Filler words (a, for, logo) are ignored.',
 		'Filters narrow it exactly. Call with no arguments to list every style, tag, mood and industry with its count.',
 		'Returns { total, marks: [{ slug, name, style, description, url … }] }: pass a slug to get_mark, build_brand_kit, render_mockup or render_cover.',

package/src/sheet/index.d.ts

@@ -11,7 +11,7 @@ export interface SheetMark {
 
 /** How to check the marks. */
 export interface SheetOptions {
-	/** The live marks (the bundled index). */
+	/** The live marks (the cached index). */
 	index?: MarkIndex;
 	/** Warnings fail a mark too (false). */
 	strict?: boolean;

package/src/similar/folder.js

@@ -2,11 +2,11 @@
  * @module logomarks/similar/folder
  *
  * An index built on the spot, for comparing against marks that aren't in the
- * bundled one: a folder of SVGs (the site's svg folder while a batch is
+ * live set: a folder of SVGs (the site's svg folder while a batch is
  * drawn), or the candidates themselves (each against the others). Names, tags
  * come from a `marks.json` beside the folder when there is one; the letter
  * signatures cover badges (their holes) and letter and number marks (their ink),
- * as the bundled index does.
+ * as the live set's index does.
  */
 
 import fs from 'node:fs';