logomarks 1.0.0 → 2.0.0

package/src/cli/commands/sheet.js

@@ -11,6 +11,9 @@ import { gridSheet } from '../../sheet/grid.js';
 import { svgFiles, slugOf } from '../files.js';
 import { style } from '../style.js';
 
+/** It reads the live set: the CLI gets it first. */
+export const live = true;
+
 /** What `sheet` takes. */
 export const spec = { flags: ['json', 'strict', 'plain'], options: { out: 'o', ignore: '', cols: '' } };
 

package/src/cli/commands/similar.d.ts

@@ -2,6 +2,8 @@ import type { ArgSpec, Parsed } from '../args.js';
 import type { IO } from '../index.js';
 import type { CommandHelp } from '../help.js';
 
+/** It reads the live set: the CLI gets it first. */
+export const live: true;
 /** What `similar` takes. */
 export const spec: ArgSpec;
 /** What `logomarks similar --help` prints. */

package/src/cli/commands/similar.js

@@ -5,7 +5,7 @@
  * Over the house threshold a match is too close (look at the two side by
  * side: solid shapes often share an outline); over the near-copy threshold
  * the mark fails. `--against <dir>` compares with a folder of SVGs instead of
- * the bundled index (the site's svg folder while a batch is drawn), `--each`
+ * the live set (the site's svg folder while a batch is drawn), `--each`
  * with the other candidates too, and `--all <data dir>` writes "More like this"
  * for a whole set (similar.json).
  */
@@ -23,6 +23,9 @@ import { UsageError } from '../args.js';
 import { svgFiles } from '../files.js';
 import { style, pad } from '../style.js';
 
+/** It reads the live set: the CLI gets it first. */
+export const live = true;
+
 /** What `similar` takes. */
 export const spec = { flags: ['json', 'letters', 'each'], options: { top: '', against: '', all: '', out: 'o' } };
 
@@ -38,7 +41,7 @@ export const help = {
 	options: [
 		['--top <n>', 'How many matches per mark. Default 5.'],
 		['--letters', `Compare a badge's knocked-out letter instead of its outline\n(${LETTERS.tooClose} too close, ${LETTERS.nearCopy} a near-copy).`],
-		['--against <dir>', 'Compare with a folder of SVGs instead of the bundled live set.'],
+		['--against <dir>', 'Compare with a folder of SVGs instead of the live set.'],
 		['--each', 'Compare the candidates with each other too (marked *).'],
 		['--all <data dir>', 'Write every mark\'s 8 nearest for a whole set ("More like this"),\nfrom its marks.json, descriptions.json and svg/.'],
 		['-o, --out <file>', 'Where --all writes. Default: stdout.'],

package/src/cli/commands/social.d.ts

@@ -2,6 +2,8 @@ import type { ArgSpec, Parsed } from '../args.js';
 import type { IO } from '../index.js';
 import type { CommandHelp } from '../help.js';
 
+/** It reads the live set: the CLI gets it first. */
+export const live: true;
 /** What `social` takes. */
 export const spec: ArgSpec;
 /** What `logomarks social --help` prints. */

package/src/cli/commands/social.js

@@ -15,6 +15,9 @@ import { FONTS } from '../../brand/fonts.js';
 import { STYLE_IDS, DEFAULT_STYLES } from '@logomarks/brand-kit';
 import { wrapList } from '../help.js';
 
+/** It reads the live set: the CLI gets it first. */
+export const live = true;
+
 /** What `social` takes. */
 export const spec = { flags: ['json', 'animated'], options: { out: 'o', name: '', color: '', font: '', tagline: '', url: '', handle: '', styles: '', platforms: '' } };
 

package/src/cli/commands/update.d.ts

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO, RunContext } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `update` takes. */
+export const spec: ArgSpec;
+/** What `logomarks update --help` prints. */
+export const help: CommandHelp;
+/** Runs `update`: checks the site now and downloads a newer set; resolves to 0, or throws an `IndexError`. */
+export function run(args: Parsed, io: IO, ctx?: RunContext): Promise<number>;

package/src/cli/commands/update.js

@@ -0,0 +1,54 @@
+/**
+ * @module logomarks/cli/commands/update
+ *
+ * `logomarks update`: ask logomarks.ai for the latest index now, rather than
+ * waiting for the daily check, and download it when it's newer.
+ */
+
+import fs from 'node:fs';
+import { ensureIndex } from '../../live/ensure.js';
+import { indexHeader } from '../../live/format.js';
+import { style } from '../style.js';
+
+/** What `update` takes. */
+export const spec = { flags: ['json'], options: {} };
+
+/** `logomarks update --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'Download the latest Logomarks set now (it is otherwise checked once a day).',
+	usage: [''],
+	about: [
+		'The set comes from https://logomarks.ai/cli/index.bin (about 3 MB), checked against its sha256,',
+		'and is cached in the user cache folder (~/.cache/logomarks, ~/Library/Caches/logomarks on macOS,',
+		'%LOCALAPPDATA%\\logomarks\\Cache on Windows; $XDG_CACHE_HOME/logomarks when set). Every command',
+		'reuses it, checking for a newer one at most once a day. Exit 1 when it can\'t be had.',
+		'Environment: LOGOMARKS_OFFLINE=1 (as --offline), LOGOMARKS_INDEX=<file> (use a local index),',
+		'LOGOMARKS_INDEX_URL=<url> (download from elsewhere).',
+	],
+	examples: ['logomarks update', 'logomarks update --json'],
+};
+
+/** How each source is described. */
+const SAID = {
+	download: 'Downloaded the latest set',
+	cache: 'Already up to date',
+	file: 'LOGOMARKS_INDEX is set; nothing to update. Using',
+};
+
+/**
+ * Runs `update`.
+ *
+ * @param {import('../args.js').Parsed} args The parsed arguments.
+ * @param {import('../index.js').IO} io Where output goes.
+ * @param {import('../index.js').RunContext} [ctx] Whether `--offline` was given (then it fails: updating needs the network).
+ * @returns {Promise<number>} The exit code: 0 when the set is current.
+ */
+export async function run(args, io, { offline } = {}) {
+	const status = await ensureIndex({ force: true, offline });
+	const bytes = fs.readFileSync(status.file);
+	const { format, built, marks } = indexHeader(bytes);
+	if (args.flags.has('json')) io.out(JSON.stringify({ source: status.source, file: status.file, format, built, marks, bytes: bytes.length, sha256: status.manifest?.sha256 }, null, 2));
+	else io.out(`${SAID[status.source]}: ${marks.toLocaleString('en-GB')} marks, built ${built} (${Math.round(bytes.length / 1024)} KB).\n${style.dim(status.file)}`);
+	return 0;
+}

package/src/cli/help.js

@@ -10,6 +10,7 @@ import { pad, style } from './style.js';
 /** The options every verb takes, listed last. */
 const COMMON = [
 	['--json', 'Machine-readable output on stdout.'],
+	['--offline', 'Use the cached set only, never the network.'],
 	['-h, --help', 'Show this help.'],
 ];
 

package/src/cli/index.d.ts

@@ -1,3 +1,9 @@
+/** What every verb is told besides its arguments. */
+export interface RunContext {
+	/** `--offline`: use the cached set only. */
+	offline?: boolean;
+}
+
 /** Where the CLI writes: lines to stdout and stderr. */
 export interface IO {
 	out(s: string): void;

package/src/cli/index.js

@@ -10,6 +10,7 @@ import { parseArgs, UsageError } from './args.js';
 import { formatHelp } from './help.js';
 import { style, pad } from './style.js';
 import { VERSION as version } from '../util/version.js';
+import { prepareIndex } from '../live/ensure.js';
 
 /** The verbs as the help groups them. */
 const GROUPS = [
@@ -18,6 +19,7 @@ const GROUPS = [
 	['Edit', ['parts', 'edit', 'glitch', 'combine']],
 	['Build', ['kit', 'social', 'mockup', 'cover']],
 	['Agents', ['mcp']],
+	['The set', ['update']],
 ];
 
 /** The help text: every verb in a line, the common examples, and where to read more. */
@@ -31,6 +33,7 @@ ${GROUPS.map(([group, verbs]) => `${style.bold(group)}\n${verbs.map((v) => `  ${
 
 A <mark> is a live slug or name (hex-gem, "Hex Gem") or the path to your own .svg.
 Every command takes --json. Exit codes: 0 ok, 1 a check failed or the command failed, 2 usage.
+The set is downloaded from logomarks.ai on first use and cached; it's checked for a newer one once a day.
 
 ${style.bold('Examples')}
   logomarks find coffee
@@ -41,6 +44,7 @@ ${style.bold('Examples')}
 ${style.bold('Options')}
   -h, --help       Show help (for a command: logomarks <command> --help).
   -v, --version    Show the version.
+  --offline        Use the cached set only, never the network (or LOGOMARKS_OFFLINE=1).
 
 Docs: https://logomarks.ai/agents  ·  The marks are CC0; the CLI is MIT.`;
 
@@ -66,15 +70,20 @@ function explain(e) {
 	return err instanceof Error ? err.message : String(e);
 }
 
+/** The flag every verb takes: use the cached set only. */
+const OFFLINE = '--offline';
+
 /**
- * Runs the CLI.
+ * Runs the CLI. A verb that reads the live set gets it first (cached, or downloaded from the site); when it can't be
+ * had, the verb still runs, and fails only if it needs a live mark.
  *
  * @param {readonly string[]} argv The arguments (without node and the script).
  * @param {import('./index.js').IO} [io] Where output goes (stdout and stderr).
  * @returns {Promise<number>} The exit code: 0 ok, 1 a check failed or the command failed, 2 usage.
  */
 export async function main(argv, io = { out: (s) => console.log(s), err: (s) => console.error(s) }) {
-	const [verb, ...rest] = argv;
+	const offline = argv.includes(OFFLINE) || undefined;
+	const [verb, ...rest] = argv.filter((a) => a !== OFFLINE);
 	if (!verb) { io.err(HELP); return 2; }
 	if (verb === '--help' || verb === '-h') { io.out(HELP); return 0; }
 	if (verb === '--version' || verb === '-v' || verb === 'version') { io.out(version); return 0; }
@@ -91,7 +100,9 @@ export async function main(argv, io = { out: (s) => console.log(s), err: (s) =>
 	}
 	if (wantsHelp(rest)) { io.out(formatHelp(verb, command.help)); return 0; }
 	try {
-		return await command.run(parseArgs(rest, command.spec), io);
+		const args = parseArgs(rest, command.spec);
+		if ('live' in command && command.live) await prepareIndex({ offline, warn: io.err });
+		return await command.run(args, io, { offline });
 	} catch (e) {
 		if (e instanceof UsageError) {
 			io.err(`logomarks ${verb}: ${e.message}\nRun "logomarks ${verb} --help" for usage.`);

package/src/cli/options.js

@@ -8,6 +8,7 @@
 
 import { UsageError } from './args.js';
 import { loadMark, MarkNotFound } from '../brand/mark.js';
+import { IndexError } from '../live/errors.js';
 import { parseColor } from '../util/color.js';
 import { fontId, FONTS } from '../brand/fonts.js';
 import { STYLE_IDS } from '@logomarks/brand-kit';
@@ -32,12 +33,14 @@ export function markArg(positionals) {
  * @param {string} ref The reference.
  * @returns {import('../brand/mark.js').Mark} The mark.
  * @throws {UsageError} When it isn't found or can't be read.
+ * @throws {IndexError} When it names a live mark and the live set can't be had.
  */
 export function markOf(ref) {
 	try {
 		return loadMark(ref);
 	} catch (e) {
 		if (e instanceof MarkNotFound) throw new UsageError(e.message);
+		if (e instanceof IndexError) throw e;
 		throw new UsageError(`can't read the mark: ${/** @type {Error} */ (e).message}`);
 	}
 }

package/src/find/index.d.ts

@@ -12,7 +12,7 @@ export interface FindOptions {
 	letter?: string;
 	/** How many to return (20). */
 	limit?: number;
-	/** The live set (the bundled index). */
+	/** The live set (the cached index). */
 	index?: MarkIndex;
 }
 

package/src/find/index.js

@@ -1,7 +1,7 @@
 /**
  * @module logomarks/find
  *
- * Searches the bundled live set the way the board on logomarks.ai does (its
+ * Searches the live set the way the board on logomarks.ai does (its
  * packed @arraypress/search index): every word must be found, typed at the
  * start of a word or as a synonym (UK and US trades: "solicitor" finds the
  * lawyers' marks), best first (a word of the name or a search word, then an
@@ -28,12 +28,12 @@ const searches = new WeakMap();
  *
  * @param {import('../similar/store.js').MarkIndex} index The live set.
  * @returns {import('@arraypress/search').Search<Record<string, unknown>>} Its search.
- * @throws {Error} When the index has no search (only the bundled one does).
+ * @throws {Error} When the index has no search (only the live set's does, not a folder's).
  */
 function searchOf(index) {
 	let s = searches.get(index);
 	if (!s) {
-		if (!index.search) throw new Error('this index has no search: findMarks needs the bundled index (npm run index)');
+		if (!index.search) throw new Error("this index has no search: findMarks needs the live set's index, not a folder's");
 		searches.set(index, (s = unpack(index.search, { stopWords: STOP })));
 	}
 	return s;

package/src/index.d.ts

@@ -5,7 +5,9 @@ export type { FindingKind } from './checks/finding.js';
 export { similar } from './similar/nearest.js';
 export type { Match, Verdict, SimilarOptions } from './similar/nearest.js';
 export { loadIndex } from './similar/store.js';
-export type { MarkIndex, IndexedMark, IndexedLetter, MarkAbout } from './similar/store.js';
+export type { MarkIndex, IndexedMark, IndexedLetter, MarkAbout, IndexInput } from './similar/store.js';
+export { ensureIndex, IndexError, INDEX_FORMAT, DEFAULT_INDEX_URL, cacheDir, buildIndex, encodeIndex, decodeIndex } from './live/index.js';
+export type { IndexErrorCode, EnsureOptions, IndexStatus, BuildInput, BuildMark, BuiltIndex, Manifest, CacheRecord } from './live/index.js';
 export { findMarks, facets } from './find/index.js';
 export type { FindOptions, FindResult, Found, Facets } from './find/index.js';
 export { sheet } from './sheet/index.js';

package/src/index.js

@@ -3,7 +3,9 @@
  *
  * Check logomarks the way the Logomarks set is checked: the house rules
  * (`check`, `fix`), the nearest live marks (`similar`), and review cards to
- * look at (`sheet`); searching the live set (`findMarks`). Then build a brand on one: the mark itself (`loadMark`,
+ * look at (`sheet`); searching the live set (`findMarks`). The live set is
+ * downloaded from logomarks.ai and cached: `await ensureIndex()` once before
+ * the functions that read it (`buildIndex` is how the site builds it). Then build a brand on one: the mark itself (`loadMark`,
  * `paint`, `markPng`), edits (`glitchMark`, `editMark`, `combineMarks`), the
  * brand kit and social pack (`kit`, `social`, from `@logomarks/brand-kit`),
  * mockups (`mockup`) and covers (`cover`). The same functions run the `logomarks` command and its MCP
@@ -14,6 +16,7 @@ export { check, fix } from './checks/index.js';
 export { FINDINGS } from './checks/finding.js';
 export { similar } from './similar/nearest.js';
 export { loadIndex } from './similar/store.js';
+export { ensureIndex, IndexError, INDEX_FORMAT, DEFAULT_INDEX_URL, cacheDir, buildIndex, encodeIndex, decodeIndex } from './live/index.js';
 export { findMarks, facets } from './find/index.js';
 export { sheet } from './sheet/index.js';
 export { fitMark } from '@logomarks/core/fit';

package/src/live/build.d.ts

@@ -0,0 +1,36 @@
+import type { SearchOptions } from '@arraypress/search';
+import type { MarkAbout } from '../similar/store.js';
+import type { Manifest } from './remote.js';
+
+/** A mark as the builder takes it: the site's mark, or the monorepo's data joined up. */
+export interface BuildMark extends Omit<MarkAbout, 'industries' | 'subject'> {
+	slug: string;
+	name: string;
+	/** The mark's SVG (trimmed when stored). */
+	svg: string;
+	/** What it depicts: subject ids. */
+	subject?: readonly string[];
+	/** The kinds of business it suits, best fit first. */
+	industries?: string[];
+}
+
+/** What the index is built from. */
+export interface BuildInput {
+	/** Every live mark, in the board's order. */
+	marks: readonly BuildMark[];
+	/** The board's search: each mark as a search record (same order) and the search options (with the synonyms). */
+	search: { records: readonly object[]; options: SearchOptions<object> };
+	/** The build date (YYYY-MM-DD; today). */
+	built?: string;
+}
+
+/** A built index: what the site serves as `/cli/index.bin` and `/cli/index.json`. */
+export interface BuiltIndex {
+	/** The file's bytes. */
+	bytes: Uint8Array<ArrayBuffer>;
+	/** The manifest: format, counts, size, sha256 and build date. */
+	manifest: Manifest & { letters: number };
+}
+
+/** Builds the live set's index (renders every mark's signatures: about 30 s for 4,000 marks) and its manifest. */
+export function buildIndex(input: BuildInput): Promise<BuiltIndex>;

package/src/live/build.js

@@ -0,0 +1,55 @@
+/**
+ * @module logomarks/live/build
+ *
+ * Builds the live set's index from the Logomarks data: each mark (in the
+ * board's order) with its SVG and what it is, its 48 px outline coverage, a
+ * letter signature for badges (their holes) and letter or number marks
+ * (their ink), and the board's search, packed (@arraypress/search), so `find`
+ * answers as logomarks.ai does. Returns the bytes and the manifest the site
+ * serves beside them (`/cli/index.bin`, `/cli/index.json`). Plain data in, so
+ * the site's build and the monorepo's `npm run index` share it.
+ */
+
+import { pack } from '@arraypress/search';
+import { outlineCoverage, letterSignatures } from '../similar/signature.js';
+import { encodeIndex, INDEX_FORMAT } from './format.js';
+import { sha256 } from './remote.js';
+
+/**
+ * Whether a mark is a badge, whose letter is its holes (every family: Badge, Pixel Badge, Stencil Badge …).
+ *
+ * @param {string} slug The mark's slug.
+ * @returns {boolean} Whether it is.
+ */
+const isBadge = (slug) => /(^|-)badge-/.test(slug);
+
+/**
+ * The index and its manifest.
+ *
+ * @param {import('./build.js').BuildInput} input The marks, in board order, and the search to pack.
+ * @returns {Promise<import('./build.js').BuiltIndex>} The file's bytes and the manifest that describes them.
+ */
+export async function buildIndex({ marks: list, search, built = new Date().toISOString().slice(0, 10) }) {
+	/** @type {import('../similar/store.js').IndexInput['marks']} */
+	const marks = [];
+	/** @type {Float32Array[]} */
+	const coverages = [];
+	/** @type {import('../similar/store.js').IndexInput['letters']} */
+	const letters = [];
+	for (const m of list) {
+		const svg = m.svg.trim();
+		const i = marks.push({
+			slug: m.slug, name: m.name, svg, tags: m.tags, collection: m.collection, style: m.style, mood: m.mood,
+			...(m.letter && { letter: m.letter }), subject: m.subject ?? [], description: m.description, industries: m.industries ?? [],
+		}) - 1;
+		coverages.push(await outlineCoverage(svg));
+		const lettery = m.tags.includes('letter') || m.tags.includes('number');
+		if (isBadge(m.slug) || lettery) {
+			const { holes, ink } = await letterSignatures(svg);
+			if (isBadge(m.slug) && holes) letters.push({ mark: i, kind: 'hole', sig: holes });
+			else if (lettery) letters.push({ mark: i, kind: 'ink', sig: ink });
+		}
+	}
+	const bytes = new Uint8Array(encodeIndex({ marks, coverages, letters, search: pack(search.records, search.options) }, { built }));
+	return { bytes, manifest: { format: INDEX_FORMAT, marks: marks.length, letters: letters.length, bytes: bytes.length, sha256: sha256(bytes), built } };
+}

package/src/live/cache.d.ts

@@ -0,0 +1,25 @@
+import type { Manifest } from './remote.js';
+
+/** What the cache keeps beside the index: the manifest it matched, where it came from, and when it was last checked. */
+export interface CacheRecord extends Manifest {
+	/** The index's URL. */
+	url: string;
+	/** When the site was last asked (ms since the epoch). */
+	checked: number;
+}
+
+/** A cached index this version can read. */
+export interface Cached {
+	/** The index file. */
+	file: string;
+	record: CacheRecord;
+}
+
+/** The cache's two files: `index.bin` and its record, `index.json`. */
+export function cacheFiles(dir: string): { index: string; record: string };
+/** The cached index, or null when there's none in a format this version reads. */
+export function readCache(dir: string): Cached | null;
+/** Saves the record alone (atomically). */
+export function saveRecord(dir: string, record: CacheRecord): void;
+/** Saves a verified index and its record (atomically); returns the index's path. */
+export function saveCache(dir: string, bytes: Uint8Array, record: CacheRecord): string;

package/src/live/cache.js

@@ -0,0 +1,75 @@
+/**
+ * @module logomarks/live/cache
+ *
+ * The cached index in the user's cache folder: `index.bin`, and beside it
+ * `index.json`, the manifest it was checked against with where it came from
+ * and when it was last checked. Writes are atomic (a temp file, then a
+ * rename), so two runs at once never leave half a file.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { INDEX_FORMAT } from './format.js';
+
+/**
+ * The cache's two files.
+ *
+ * @param {string} dir The cache folder.
+ * @returns {{ index: string, record: string }} The index and its record.
+ */
+export const cacheFiles = (dir) => ({ index: path.join(dir, 'index.bin'), record: path.join(dir, 'index.json') });
+
+/**
+ * The cached index, when there is one this version can read.
+ *
+ * @param {string} dir The cache folder.
+ * @returns {import('./cache.js').Cached | null} The file and its record, or null.
+ */
+export function readCache(dir) {
+	const { index, record } = cacheFiles(dir);
+	try {
+		const r = JSON.parse(fs.readFileSync(record, 'utf8'));
+		if (r.format !== INDEX_FORMAT || !fs.existsSync(index)) return null;
+		return { file: index, record: r };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Writes a file atomically: to a temp file beside it, then renamed over it.
+ *
+ * @param {string} file Where.
+ * @param {string | Uint8Array} data What.
+ */
+function writeAtomic(file, data) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+	fs.writeFileSync(tmp, data);
+	fs.renameSync(tmp, file);
+}
+
+/**
+ * Saves the record alone (the index is unchanged; it was checked again).
+ *
+ * @param {string} dir The cache folder.
+ * @param {import('./cache.js').CacheRecord} record The manifest, where it came from and when it was checked.
+ */
+export function saveRecord(dir, record) {
+	writeAtomic(cacheFiles(dir).record, `${JSON.stringify(record, null, 2)}\n`);
+}
+
+/**
+ * Saves a verified index and its record.
+ *
+ * @param {string} dir The cache folder.
+ * @param {Uint8Array} bytes The index.
+ * @param {import('./cache.js').CacheRecord} record The manifest, where it came from and when it was checked.
+ * @returns {string} The index's path.
+ */
+export function saveCache(dir, bytes, record) {
+	const { index } = cacheFiles(dir);
+	writeAtomic(index, bytes);
+	saveRecord(dir, record);
+	return index;
+}

package/src/live/current.d.ts

@@ -0,0 +1,9 @@
+/** Makes a file the process's index (what `loadIndex()` reads). */
+export function useIndexFile(file: string): void;
+/** Records why the index couldn't be had, for `loadIndex()` to throw when a command needs it. */
+export function indexUnavailable(error: unknown): void;
+/**
+ * The index file this process reads: the one `ensureIndex` settled on, else `LOGOMARKS_INDEX`, else the cached one.
+ * Throws the recorded reason, or an `IndexError` (`missing`), when there's none.
+ */
+export function currentIndexFile(env?: NodeJS.ProcessEnv): string;

package/src/live/current.js

@@ -0,0 +1,54 @@
+/**
+ * @module logomarks/live/current
+ *
+ * Which index file this process reads when `loadIndex()` is called with none:
+ * the one `ensureIndex` settled on; else `LOGOMARKS_INDEX`; else the cached
+ * one, when there is one. With none, the reason `ensureIndex` failed, or a
+ * message saying how to get it.
+ */
+
+import { IndexError } from './errors.js';
+import { cacheDir, localIndex } from './paths.js';
+import { readCache } from './cache.js';
+
+/** The file `ensureIndex` settled on. */
+let chosen = /** @type {string | undefined} */ (undefined);
+
+/** Why `prepareIndex` couldn't settle on one. */
+let failure = /** @type {unknown} */ (undefined);
+
+/**
+ * Makes a file the process's index.
+ *
+ * @param {string} file The index file.
+ */
+export function useIndexFile(file) {
+	chosen = file;
+	failure = undefined;
+}
+
+/**
+ * Records why the index couldn't be had, for `loadIndex()` to throw when a command needs it.
+ *
+ * @param {unknown} error The reason.
+ */
+export function indexUnavailable(error) {
+	failure = error;
+}
+
+/**
+ * The index file this process reads.
+ *
+ * @param {NodeJS.ProcessEnv} [env] The environment.
+ * @returns {string} The file.
+ * @throws {unknown} Why there's none: the recorded reason, or an `IndexError` (`missing`).
+ */
+export function currentIndexFile(env = process.env) {
+	if (chosen) return chosen;
+	const local = localIndex(env);
+	if (local) return local;
+	if (failure) throw failure;
+	const cached = readCache(cacheDir({ env }));
+	if (cached) return cached.file;
+	throw new IndexError('missing', "the Logomarks index isn't downloaded yet: run logomarks update (it's cached after that), or call await ensureIndex() first");
+}

package/src/live/ensure.d.ts

@@ -0,0 +1,43 @@
+import type { CacheRecord } from './cache.js';
+
+/** How to get the live set. */
+export interface EnsureOptions {
+	/** Ask the site even when the cache is fresh, and fail rather than fall back to the cache (`logomarks update`). */
+	force?: boolean;
+	/** Use the cache alone (default: `LOGOMARKS_OFFLINE`). */
+	offline?: boolean;
+	/** The environment read for `LOGOMARKS_INDEX`, `LOGOMARKS_INDEX_URL`, `LOGOMARKS_OFFLINE` and the cache folder. */
+	env?: NodeJS.ProcessEnv;
+	/** The index's URL (default: `LOGOMARKS_INDEX_URL`, or https://logomarks.ai/cli/index.bin). */
+	url?: string;
+	/** The cache folder (default: the user's, `cacheDir()`). */
+	dir?: string;
+	/** How long a checked index counts as fresh, in ms (a day). */
+	maxAge?: number;
+	/** How long one request may take, in ms (30 s). */
+	timeout?: number;
+	/** The time now, in ms (for tests). */
+	now?: number;
+	/** Told when the site couldn't be reached or sent a bad file and the cache is used instead. */
+	warn?: (message: string) => void;
+}
+
+/** The index file settled on, and how it was had. */
+export interface IndexStatus {
+	/** The index file. */
+	file: string;
+	/** `file`: `LOGOMARKS_INDEX`; `cache`: the cached one; `download`: just downloaded and cached. */
+	source: 'file' | 'cache' | 'download';
+	/** Whether the site was asked this time. */
+	checked: boolean;
+	/** The manifest it matched (absent for `LOGOMARKS_INDEX`). */
+	manifest?: CacheRecord;
+}
+
+/**
+ * The live set's index file: `LOGOMARKS_INDEX`; else the cached one, re-checked at most once a day; else downloaded,
+ * verified by sha256 and cached. It becomes the file `loadIndex()` reads. Throws an `IndexError` when there's none.
+ */
+export function ensureIndex(o?: EnsureOptions): Promise<IndexStatus>;
+/** Runs `ensureIndex` once per process and never throws: `loadIndex()` throws the failure when something needs the set. */
+export function prepareIndex(o?: EnsureOptions): Promise<IndexStatus | undefined>;