logomarks 0.0.0-stage → 1.1.0

package/src/cli/commands/specks.js

@@ -0,0 +1,103 @@
+/**
+ * @module logomarks/cli/commands/specks
+ *
+ * `logomarks specks <folder | file.svg…>`: the set's speck review (what
+ * speckcheck.mjs printed). Every mark's pieces under `--piece` (60) and holes
+ * under `--hole` (30), smallest first, with their boxes, so you know where to
+ * zoom; tiny, hairline, repeated and reviewed parts are left out unless
+ * `--all`. `--raster` reads every mark from the scanline raster. Run it on
+ * fitted marks, then render each hit large before changing anything: many
+ * small parts are meant.
+ */
+
+import fs from 'node:fs';
+import { shapes } from '@logomarks/core/svg';
+import { markParts, smallParts } from '@logomarks/core/analyse';
+import { SPECKS, REVIEWED } from '../../rules.js';
+import { UsageError } from '../args.js';
+import { svgFiles, slugOf } from '../files.js';
+
+/** What `specks` takes. */
+export const spec = { flags: ['json', 'all', 'raster'], options: { piece: '', hole: '', allow: '' } };
+
+/** `logomarks specks --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'List every speck, sliver and pin-hole, with its box.',
+	usage: ['<file.svg | folder>… [options]'],
+	about: [
+		'The speck review: pieces under --piece and holes under --hole, smallest first. Tiny,',
+		'hairline, repeated and reviewed parts are left out unless --all. Render each hit large',
+		'before changing anything: many small parts are meant. Exit 1 when anything is listed.',
+	],
+	options: [
+		['--piece <area>', 'Report pieces smaller than this, in square units. Default 60.'],
+		['--hole <area>', 'Report holes smaller than this. Default 30.'],
+		['--allow <slugs>', 'Marks whose small parts are meant, comma-separated.'],
+		['--all', 'Report every small part, reviewed and repeated ones included.'],
+		['--raster', 'Read each mark from the scanline raster instead of its outline.'],
+	],
+	examples: ['logomarks specks out/', 'logomarks specks mark.svg --piece 80 --json'],
+};
+
+/**
+ * A number option.
+ *
+ * @param {string | undefined} v The option's value.
+ * @param {number} d Its default.
+ * @param {string} name Its name, for the error.
+ * @returns {number} The number.
+ */
+const num = (v, d, name) => {
+	if (v === undefined) return d;
+	const n = Number(v);
+	if (!Number.isFinite(n) || n < 0) throw new UsageError(`--${name} takes a number`);
+	return n;
+};
+
+/**
+ * One mark's small parts, each tagged with why it is left out ('' = reported).
+ *
+ * @param {string} file The mark.
+ * @param {{ piece: number, hole: number, raster: boolean, allow: Set<string> }} o The limits.
+ * @returns {import('./specks.js').MarkSpecks} Its small parts.
+ */
+function review(file, { piece, hole, raster, allow }) {
+	const slug = slugOf(file);
+	let read;
+	try {
+		read = markParts(shapes(fs.readFileSync(file, 'utf8')), { seed: slug, raster });
+	} catch (e) {
+		return { slug, note: `unreadable: ${/** @type {Error} */ (e).message.slice(0, 40)}`, raster: false, parts: [{ kind: 'mark', area: 0, width: 0, box: [0, 0, 0, 0], skip: '' }] };
+	}
+	const note = read.error ? `svgShape failed: ${read.error.slice(0, 40)}` : '';
+	const parts = smallParts(read.parts, { piece, hole, raster: read.raster }).map((p) => (allow.has(slug) ? { ...p, skip: 'allowed' } : p));
+	return { slug, note, raster: read.raster, parts };
+}
+
+/**
+ * Runs `specks`.
+ *
+ * @param {import('../args.js').Parsed} args The parsed arguments.
+ * @param {import('../index.js').IO} io Where output goes.
+ * @returns {Promise<number>} The exit code: 1 when anything is reported.
+ */
+export async function run(args, io) {
+	const files = svgFiles(args.positionals).slice().sort((a, b) => (slugOf(a) < slugOf(b) ? -1 : slugOf(a) > slugOf(b) ? 1 : 0));
+	const piece = num(args.options.piece, SPECKS.piece, 'piece'), hole = num(args.options.hole, SPECKS.hole, 'hole');
+	const all = args.flags.has('all');
+	const allow = new Set([...Object.keys(REVIEWED), ...(args.options.allow ?? '').split(',').filter(Boolean)]);
+	const results = files.map((f) => review(f, { piece, hole, raster: args.flags.has('raster'), allow }));
+	const f1 = (/** @type {number} */ v) => v.toFixed(1);
+	const shown = results.map((r) => ({ ...r, parts: r.parts.filter((p) => all || !p.skip) })).filter((r) => r.parts.length);
+	if (args.flags.has('json')) {
+		io.out(JSON.stringify(shown.map(({ slug, note, parts }) => ({ slug, note, parts: parts.map((p) => ({ ...p, area: +p.area.toFixed(2), width: +p.width.toFixed(3), box: p.box.map((v) => +v.toFixed(1)) })) })), null, 1));
+	} else {
+		for (const { slug, note, parts } of shown) io.out(slug.padEnd(28) + ' ' + parts.map((p) => (p.kind === 'mark' ? 'could not be read' : `${p.kind} ${f1(p.area)} at ${f1(p.box[0])},${f1(p.box[1])}–${f1(p.box[2])},${f1(p.box[3])}${'raster' in p && p.raster ? ' (raster)' : ''}${p.skip ? ` [${p.skip}]` : ''}`)).join(' · ') + (note ? `  (${note})` : ''));
+		const count = (/** @type {string} */ k) => results.reduce((s, r) => s + r.parts.filter((p) => p.skip === k).length, 0);
+		io.out(`${results.filter((r) => r.parts.some((p) => !p.skip)).length} of ${files.length} marks with specks (pieces < ${piece}, holes < ${hole}); `
+			+ `left out ${count('tiny')} tiny, ${count('hairline')} hairline, ${count('repeated')} repeated, ${count('allowed')} allowed${all ? '' : ' (--all lists them)'}; `
+			+ `${results.filter((r) => r.raster).length} read by raster${results.some((r) => r.note) ? ': ' + results.filter((r) => r.note).map((r) => r.slug).join(', ') : ''}`);
+	}
+	return results.some((r) => r.parts.some((p) => !p.skip)) ? 1 : 0;
+}

package/src/cli/edited.d.ts

@@ -0,0 +1,6 @@
+import type { Parsed } from './args.js';
+import type { IO } from './index.js';
+import type { Edited } from '../edit/doc.js';
+
+/** Writes (`-o` .svg or .png) or prints an edited mark and its checks; resolves to 0 when it passes, 1 otherwise. */
+export function output(args: Parsed, io: IO, r: Edited & Record<string, unknown>, o: { name: string; summary: string }): Promise<number>;

package/src/cli/edited.js

@@ -0,0 +1,32 @@
+/**
+ * @module logomarks/cli/edited
+ *
+ * How the editing verbs hand back a result: the SVG to `-o` (or a PNG to
+ * look at, for `.png`) or to stdout, and its checks; `--json` for both as
+ * one object. Exit 1 when the result fails a check.
+ */
+
+import { markPreview } from '../edit/preview.js';
+import { writeFile } from '../util/files.js';
+import { reportLines } from './report.js';
+import { style } from './style.js';
+
+/**
+ * Writes or prints an edited mark and its checks.
+ *
+ * @param {import('./args.js').Parsed} args The parsed arguments (`-o`, `--json`).
+ * @param {import('./index.js').IO} io Where output goes.
+ * @param {import('../edit/doc.js').Edited & Record<string, unknown>} r The result, and anything more to report.
+ * @param {{ name: string, summary: string }} o The mark's name, and a line on what was done.
+ * @returns {Promise<number>} The exit code: 0 when the result passes its checks, 1 otherwise.
+ */
+export async function output(args, io, { svg, checks, ...more }, { name, summary }) {
+	const file = args.options.out;
+	if (file) writeFile(file, file.toLowerCase().endsWith('.png') ? await markPreview(svg) : svg);
+	if (args.flags.has('json')) io.out(JSON.stringify({ ok: checks.ok, ...more, ...(file && { file }), svg, checks }, null, 2));
+	else if (!file) {
+		io.out(svg.trimEnd());
+		io.err(`${summary}\n${reportLines(name, checks)}`);
+	} else io.out(`${style.green('✓')} wrote ${style.bold(file)}: ${summary}\n${reportLines(file, checks)}`);
+	return checks.ok ? 0 : 1;
+}

package/src/cli/files.d.ts

@@ -0,0 +1,4 @@
+/** Every SVG named, folders expanded (sorted, not recursive); throws a `UsageError` when nothing is named or a path is missing. */
+export function svgFiles(paths: readonly string[]): string[];
+/** A mark's name from its file: the slug. */
+export function slugOf(file: string): string;

package/src/cli/files.js

@@ -0,0 +1,27 @@
+/**
+ * @module logomarks/cli/files
+ *
+ * The SVG files a command was given: files as they are, folders expanded to
+ * the `.svg` files in them.
+ */
+
+import { UsageError } from './args.js';
+import { expandSvgs } from '../util/files.js';
+
+export { slugOf } from '../util/files.js';
+
+/**
+ * Every SVG named, folders expanded (sorted, not recursive).
+ *
+ * @param {readonly string[]} paths Files and folders.
+ * @returns {string[]} The files.
+ * @throws {UsageError} When nothing is named or a path is missing.
+ */
+export function svgFiles(paths) {
+	if (!paths.length) throw new UsageError('name at least one .svg file or folder');
+	try {
+		return expandSvgs(paths);
+	} catch (e) {
+		throw new UsageError(/** @type {Error} */ (e).message);
+	}
+}

package/src/cli/help.d.ts

@@ -0,0 +1,20 @@
+/** A verb's help. */
+export interface CommandHelp {
+	/** What it does, in one line. */
+	summary: string;
+	/** How to call it, after `logomarks <verb>`; one line per form. */
+	usage: string[];
+	/** Lines of explanation between the usage and the options. */
+	about?: string[];
+	/** Each option and what it does (`\n` starts an indented line). */
+	options?: ReadonlyArray<readonly [string, string]>;
+	/** Whether it takes `--json` (default true). */
+	json?: boolean;
+	/** Example command lines. */
+	examples?: string[];
+}
+
+/** Names joined with commas and wrapped to `width`, later lines starting with `indent`. */
+export function wrapList(names: readonly string[], width?: number, indent?: string): string;
+/** A verb's help as text, with the options every verb takes (`--json`, `--help`) listed last. */
+export function formatHelp(verb: string, help: CommandHelp): string;

package/src/cli/help.js

@@ -0,0 +1,55 @@
+/**
+ * @module logomarks/cli/help
+ *
+ * Each verb's `--help`: what it does, how to call it, its options and
+ * examples, laid out the same way for every verb.
+ */
+
+import { pad, style } from './style.js';
+
+/** The options every verb takes, listed last. */
+const COMMON = [
+	['--json', 'Machine-readable output on stdout.'],
+	['-h, --help', 'Show this help.'],
+];
+
+/** The width of the options' left-hand column. */
+const COLUMN = 24;
+
+/**
+ * Names as one line, joined with commas, wrapped to a width.
+ *
+ * @param {readonly string[]} names The names.
+ * @param {number} [width] The widest line.
+ * @param {string} [indent] What each line after the first starts with.
+ * @returns {string} The list.
+ */
+export function wrapList(names, width = 72, indent = '') {
+	const lines = [''];
+	for (const n of names) {
+		const last = lines.length - 1;
+		if (lines[last] && lines[last].length + n.length + 2 > width) lines.push('');
+		lines[lines.length - 1] += `${lines[lines.length - 1] ? ', ' : ''}${n}`;
+	}
+	return lines.join(`,\n${indent}`);
+}
+
+/**
+ * A verb's help as text.
+ *
+ * @param {string} verb The verb.
+ * @param {import('./help.js').CommandHelp} help What to say.
+ * @returns {string} The help.
+ */
+export function formatHelp(verb, { summary, usage, about = [], options = [], examples = [], json = true }) {
+	const indent = ' '.repeat(COLUMN + 2);
+	const option = (/** @type {readonly [string, string]} */ [flag, text]) => {
+		const body = text.replaceAll('\n', `\n${indent}`);
+		return flag.length >= COLUMN ? `  ${flag}\n${indent}${body}` : `  ${pad(flag, COLUMN)}${body}`;
+	};
+	const parts = [`${style.bold(`logomarks ${verb}`)}: ${summary}`, `${style.bold('Usage')}\n${usage.map((u) => `  logomarks ${verb} ${u}`).join('\n')}`];
+	if (about.length) parts.push(about.join('\n'));
+	parts.push(`${style.bold('Options')}\n${[...options, ...COMMON.filter(([flag]) => json || flag !== '--json')].map(option).join('\n')}`);
+	if (examples.length) parts.push(`${style.bold('Examples')}\n${examples.map((e) => `  ${e}`).join('\n')}`);
+	return parts.join('\n\n');
+}

package/src/cli/index.d.ts

@@ -0,0 +1,10 @@
+/** Where the CLI writes: lines to stdout and stderr. */
+export interface IO {
+	out(s: string): void;
+	err(s: string): void;
+}
+
+/** The help text: every verb in a line, the common examples, and where to read more. */
+export const HELP: string;
+/** Runs the CLI with `argv` (no node or script) and resolves to its exit code: 0 ok, 1 a check failed or the command failed, 2 usage. */
+export function main(argv: readonly string[], io?: IO): Promise<number>;

package/src/cli/index.js

@@ -0,0 +1,104 @@
+/**
+ * @module logomarks/cli
+ *
+ * The command line: `logomarks <verb> …`, and `--help` for each verb.
+ * Exit codes: 0 ok, 1 a check failed or the command failed, 2 usage.
+ */
+
+import { COMMANDS } from './commands/index.js';
+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';
+
+/** The verbs as the help groups them. */
+const GROUPS = [
+	['Find and get', ['find', 'get']],
+	['Check', ['check', 'similar', 'specks', 'sheet']],
+	['Edit', ['parts', 'edit', 'glitch', 'combine']],
+	['Build', ['kit', 'social', 'mockup', 'cover']],
+	['Agents', ['mcp']],
+];
+
+/** The help text: every verb in a line, the common examples, and where to read more. */
+export const HELP = `logomarks ${version}: find, check, edit and build on free geometric logomarks.
+
+${style.bold('Usage')}
+  logomarks <command> [arguments] [options]
+  logomarks <command> --help
+
+${GROUPS.map(([group, verbs]) => `${style.bold(group)}\n${verbs.map((v) => `  ${pad(v, 10)}${COMMANDS[/** @type {keyof typeof COMMANDS} */ (v)].help.summary}`).join('\n')}`).join('\n\n')}
+
+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.
+
+${style.bold('Examples')}
+  logomarks find coffee
+  logomarks get hex-gem --color '#ff5c3a' -o logo.svg
+  logomarks check mark.svg
+  logomarks kit hex-gem --name "Hexa Labs" -o hexa/
+
+${style.bold('Options')}
+  -h, --help       Show help (for a command: logomarks <command> --help).
+  -v, --version    Show the version.
+
+Docs: https://logomarks.ai/agents  ·  The marks are CC0; the CLI is MIT.`;
+
+/**
+ * Whether the arguments ask for help.
+ *
+ * @param {readonly string[]} args The arguments after the verb.
+ * @returns {boolean} True for `--help` or `-h`.
+ */
+const wantsHelp = (args) => args.includes('--help') || args.includes('-h');
+
+/**
+ * What went wrong, in a line: a missing or unwritable file by its path, anything else by its message.
+ *
+ * @param {unknown} e The error.
+ * @returns {string} The message.
+ */
+function explain(e) {
+	const err = /** @type {NodeJS.ErrnoException} */ (e);
+	if (err?.code === 'ENOENT') return `no such file or folder: ${err.path}`;
+	if (err?.code === 'EACCES' || err?.code === 'EPERM') return `permission denied: ${err.path}`;
+	if (err?.code === 'EISDIR') return `${err.path} is a folder`;
+	return err instanceof Error ? err.message : String(e);
+}
+
+/**
+ * Runs the CLI.
+ *
+ * @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;
+	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; }
+	if (verb === 'help') {
+		const topic = COMMANDS[/** @type {keyof typeof COMMANDS} */ (rest[0])];
+		if (rest[0] && !topic) { io.err(`logomarks: unknown command "${rest[0]}". Run "logomarks --help" for the list.`); return 2; }
+		io.out(topic ? formatHelp(rest[0], topic.help) : HELP);
+		return 0;
+	}
+	const command = COMMANDS[/** @type {keyof typeof COMMANDS} */ (verb)];
+	if (!command) {
+		io.err(`logomarks: unknown command "${verb}". Run "logomarks --help" for the list.`);
+		return 2;
+	}
+	if (wantsHelp(rest)) { io.out(formatHelp(verb, command.help)); return 0; }
+	try {
+		return await command.run(parseArgs(rest, command.spec), io);
+	} catch (e) {
+		if (e instanceof UsageError) {
+			io.err(`logomarks ${verb}: ${e.message}\nRun "logomarks ${verb} --help" for usage.`);
+			return 2;
+		}
+		io.err(`logomarks ${verb}: ${explain(e)}`);
+		if (process.env.LOGOMARKS_DEBUG) io.err(String(/** @type {Error} */ (e)?.stack ?? e));
+		return 1;
+	}
+}

package/src/cli/options.d.ts

@@ -0,0 +1,30 @@
+import type { Parsed } from './args.js';
+import type { BrandOptions } from '../brand/brand.js';
+import type { PackOptions } from '../kit/index.js';
+import type { Mark } from '../brand/mark.js';
+import type { FontId } from '../brand/fonts.js';
+
+/** The mark the positionals name (a live slug or name, or an .svg file); a `UsageError` otherwise. */
+export function markArg(positionals: readonly string[]): Mark;
+/** One mark by slug, name or file; a `UsageError` when it isn't found. */
+export function markOf(ref: string): Mark;
+/** A number option (undefined when not given); a `UsageError` when it isn't one. */
+export function numArg(name: string, value: string | undefined): number | undefined;
+/** A colour option as `#RRGGBB` (undefined when not given); a `UsageError` when it isn't one. */
+export function colorArg(value: string | undefined): string | undefined;
+/** A typeface option as its id (undefined when not given); a `UsageError` when it isn't bundled. */
+export function fontArg(value: string | undefined): FontId | undefined;
+/** A whole-number option in range (undefined when not given); a `UsageError` otherwise. */
+export function intArg(name: string, value: string | undefined, min: number, max: number): number | undefined;
+/** Writes a file, making its folder. */
+export function writeFile(file: string, data: string | Uint8Array): void;
+/** Writes files by path under a folder; returns how many. */
+export function writeFiles(dir: string, files: Iterable<[string, string | Uint8Array]>): number;
+/** A comma-separated option as a trimmed list (undefined when not given). */
+export function listArg(value: string | undefined): string[] | undefined;
+/** The brand: the mark, and `--name --color --font --tagline --url --handle`; a `UsageError` when one is wrong. */
+export function brandArgs(args: Parsed): BrandOptions & { mark: Mark; name: string };
+/** The social pack's `--platforms`, `--styles` and `--animated`; a `UsageError` for an unknown style. */
+export function packArgs(args: Parsed): PackOptions;
+/** Runs a call, its RangeErrors and TypeErrors (an unknown platform, style or object) as `UsageError`s. */
+export function asUsage<T>(build: () => Promise<T>): Promise<T>;

package/src/cli/options.js

@@ -0,0 +1,155 @@
+/**
+ * @module logomarks/cli/options
+ *
+ * The options the brand verbs share, read and checked: the mark, a colour,
+ * a typeface, a whole number, a list; the brand and the social pack's
+ * choices; and writing a file, folders made as needed.
+ */
+
+import { UsageError } from './args.js';
+import { loadMark, MarkNotFound } from '../brand/mark.js';
+import { parseColor } from '../util/color.js';
+import { fontId, FONTS } from '../brand/fonts.js';
+import { STYLE_IDS } from '@logomarks/brand-kit';
+
+export { writeFile, writeFiles } from '../util/files.js';
+
+/**
+ * The mark the positionals name: a live slug or name (words may be unquoted), or an SVG file.
+ *
+ * @param {readonly string[]} positionals The positionals.
+ * @returns {import('../brand/mark.js').Mark} The mark.
+ * @throws {UsageError} When none is named or it isn't found.
+ */
+export function markArg(positionals) {
+	if (!positionals.length) throw new UsageError('name a live mark (slug or name) or an .svg file');
+	return markOf(positionals.join(' '));
+}
+
+/**
+ * One mark by slug, name or file.
+ *
+ * @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.
+ */
+export function markOf(ref) {
+	try {
+		return loadMark(ref);
+	} catch (e) {
+		if (e instanceof MarkNotFound) throw new UsageError(e.message);
+		throw new UsageError(`can't read the mark: ${/** @type {Error} */ (e).message}`);
+	}
+}
+
+/**
+ * A colour option.
+ *
+ * @param {string | undefined} value The option's value.
+ * @returns {string | undefined} `#RRGGBB`, or undefined when it wasn't given.
+ * @throws {UsageError} When it isn't a colour.
+ */
+export function colorArg(value) {
+	if (value === undefined) return undefined;
+	const hex = parseColor(value);
+	if (!hex) throw new UsageError(`--color takes a hex colour (#ff5c3a), not "${value}"`);
+	return hex;
+}
+
+/**
+ * A typeface option.
+ *
+ * @param {string | undefined} value The option's value.
+ * @returns {import('../brand/fonts.js').FontId | undefined} The face's id, or undefined when it wasn't given.
+ * @throws {UsageError} When it isn't bundled.
+ */
+export function fontArg(value) {
+	if (value === undefined) return undefined;
+	const id = fontId(value);
+	if (!id) throw new UsageError(`--font is one of ${Object.keys(FONTS).join(', ')}`);
+	return id;
+}
+
+/**
+ * A whole-number option.
+ *
+ * @param {string} name The option (for the message).
+ * @param {string | undefined} value Its value.
+ * @param {number} min The smallest allowed.
+ * @param {number} max The largest allowed.
+ * @returns {number | undefined} The number, or undefined when it wasn't given.
+ * @throws {UsageError} When it isn't a whole number in range.
+ */
+export function intArg(name, value, min, max) {
+	if (value === undefined) return undefined;
+	const n = Number(value);
+	if (!Number.isInteger(n) || n < min || n > max) throw new UsageError(`--${name} takes a whole number from ${min} to ${max}`);
+	return n;
+}
+
+/**
+ * A number option.
+ *
+ * @param {string} name The option (for the message).
+ * @param {string | undefined} value Its value.
+ * @returns {number | undefined} The number, or undefined when it wasn't given.
+ * @throws {UsageError} When it isn't a number.
+ */
+export function numArg(name, value) {
+	if (value === undefined) return undefined;
+	const n = Number(value);
+	if (value.trim() === '' || !Number.isFinite(n)) throw new UsageError(`--${name} takes a number, not "${value}"`);
+	return n;
+}
+
+/**
+ * A comma-separated option as a list.
+ *
+ * @param {string | undefined} value The option's value.
+ * @returns {string[] | undefined} The items, trimmed; undefined when it wasn't given.
+ */
+export const listArg = (value) => value?.split(',').map((v) => v.trim()).filter(Boolean);
+
+/**
+ * The brand the brand verbs build on: the mark, and `--name --color --font --tagline --url --handle`.
+ *
+ * @param {import('./args.js').Parsed} args The parsed arguments.
+ * @returns {import('../brand/brand.js').BrandOptions & { mark: import('../brand/mark.js').Mark, name: string }} The brand.
+ * @throws {UsageError} When the mark, colour or face is wrong.
+ */
+export function brandArgs(args) {
+	const mark = markArg(args.positionals);
+	const { tagline, url, handle } = args.options;
+	return { mark, name: args.options.name?.trim() || mark.name, color: colorArg(args.options.color), font: fontArg(args.options.font), tagline, url, handle };
+}
+
+/**
+ * What goes in a social pack: `--platforms`, `--styles`, `--animated`.
+ *
+ * @param {import('./args.js').Parsed} args The parsed arguments.
+ * @returns {import('../kit/index.js').PackOptions} The choices.
+ * @throws {UsageError} For a style that isn't one.
+ */
+export function packArgs(args) {
+	const styles = listArg(args.options.styles);
+	const bad = styles?.filter((s) => !(/** @type {readonly string[]} */ (STYLE_IDS)).includes(s));
+	if (bad?.length) throw new UsageError(`--styles takes ${STYLE_IDS.join(', ')}, not ${bad.join(', ')}`);
+	return { styles: /** @type {import('@logomarks/brand-kit').StyleId[] | undefined} */ (styles), platforms: listArg(args.options.platforms), animated: args.flags.has('animated') };
+}
+
+/**
+ * Runs a brand-kit call, its RangeErrors (an unknown platform or style) as usage errors.
+ *
+ * @template T
+ * @param {() => Promise<T>} build The call.
+ * @returns {Promise<T>} Its result.
+ * @throws {UsageError} For a RangeError.
+ */
+export async function asUsage(build) {
+	try {
+		return await build();
+	} catch (e) {
+		if (e instanceof RangeError || e instanceof TypeError) throw new UsageError(e.message.replace(/^brand-kit: /, ''));
+		throw e;
+	}
+}

package/src/cli/report.d.ts

@@ -0,0 +1,4 @@
+import type { Report } from '../checks/index.js';
+
+/** A check report as readable lines. */
+export function reportLines(file: string, r: Report, fixed?: boolean): string;

package/src/cli/report.js

@@ -0,0 +1,28 @@
+/**
+ * @module logomarks/cli/report
+ *
+ * A check report as readable lines: a mark's verdict, size and counts, then
+ * each finding with its id, message and where it is.
+ */
+
+import { style, pad } from './style.js';
+
+/** Severity labels. */
+const LABEL = { error: style.red('error  '), warning: style.yellow('warning'), info: style.dim('note   ') };
+
+/**
+ * A report as readable lines.
+ *
+ * @param {string} file The file (or the mark's name).
+ * @param {import('../checks/index.js').Report} r Its report.
+ * @param {boolean} [fixed] Whether it was refitted.
+ * @returns {string} The lines.
+ */
+export function reportLines(file, r, fixed = false) {
+	const sym = !r.ok ? style.red('✗') : r.warnings ? style.yellow('!') : style.green('✓');
+	const counts = [r.errors && `${r.errors} error${r.errors > 1 ? 's' : ''}`, r.warnings && `${r.warnings} warning${r.warnings > 1 ? 's' : ''}`].filter(Boolean).join(', ');
+	const size = r.size ? `${r.size.w} × ${r.size.h}` : 'empty';
+	const head = `${sym} ${style.bold(file)}  ${style.dim(size)}${counts ? `  ${counts}` : ''}${fixed ? style.green('  refitted') : ''}`;
+	const body = r.findings.map((f) => `    ${LABEL[f.severity]}  ${pad(f.id, 12)} ${f.message}${f.box ? style.dim(`  [${f.box.join(', ')}]`) : f.point ? style.dim(`  (${f.point.join(', ')})`) : ''}`);
+	return [head, ...body].join('\n');
+}

package/src/cli/style.d.ts

@@ -0,0 +1,4 @@
+/** The output's colours (plain text off a terminal or with `NO_COLOR`). */
+export const style: Readonly<Record<'red' | 'yellow' | 'green' | 'dim' | 'bold', (s: string) => string>>;
+/** Text padded to a width, ignoring colour codes. */
+export function pad(s: string, n: number): string;

package/src/cli/style.js

@@ -0,0 +1,34 @@
+/**
+ * @module logomarks/cli/style
+ *
+ * Colour for the readable output, only on a terminal and never with
+ * `NO_COLOR` set.
+ */
+
+const on = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+/**
+ * A function that wraps text in an ANSI colour (or leaves it as it is).
+ *
+ * @param {number} code The colour's code.
+ * @returns {(s: string) => string} The wrapper.
+ */
+const paint = (code) => (s) => (on ? `\x1b[${code}m${s}\x1b[0m` : s);
+
+/** The output's colours. */
+export const style = {
+	red: paint(31),
+	yellow: paint(33),
+	green: paint(32),
+	dim: paint(2),
+	bold: paint(1),
+};
+
+/**
+ * Text padded to a width, ignoring colour codes.
+ *
+ * @param {string} s The text.
+ * @param {number} n The width.
+ * @returns {string} The padded text.
+ */
+export const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.replace(/\x1b\[\d+m/g, '').length));