logomarks 0.0.0-stage → 1.1.0

package/src/cli/commands/index.js

@@ -0,0 +1,24 @@
+/**
+ * @module logomarks/cli/commands
+ *
+ * The verbs, by name.
+ */
+
+import * as check from './check.js';
+import * as similar from './similar.js';
+import * as specks from './specks.js';
+import * as sheet from './sheet.js';
+import * as get from './get.js';
+import * as kit from './kit.js';
+import * as mockup from './mockup.js';
+import * as cover from './cover.js';
+import * as parts from './parts.js';
+import * as glitch from './glitch.js';
+import * as edit from './edit.js';
+import * as combine from './combine.js';
+import * as social from './social.js';
+import * as find from './find.js';
+import * as mcp from './mcp.js';
+
+/** Every verb the CLI runs. */
+export const COMMANDS = { check, similar, specks, sheet, find, parts, glitch, edit, combine, get, kit, social, mockup, cover, mcp };

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

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `kit` takes. */
+export const spec: ArgSpec;
+/** What `logomarks kit --help` prints. */
+export const help: CommandHelp;
+/** Runs `kit`; resolves to its exit code (0). */
+export function run(args: Parsed, io: IO): Promise<number>;

package/src/cli/commands/kit.js

@@ -0,0 +1,66 @@
+/**
+ * @module logomarks/cli/commands/kit
+ *
+ * `logomarks kit <slug|file.svg> --name "Brand" -o dir/`: the brand kit
+ * (`@logomarks/brand-kit`) written to a folder.
+ */
+
+import path from 'node:path';
+import { kit } from '../../kit/index.js';
+import { slugify } from '../../brand/mark.js';
+import { brandArgs, packArgs, asUsage, writeFiles } from '../options.js';
+import { style } from '../style.js';
+import { FONTS } from '../../brand/fonts.js';
+import { STYLE_IDS, DEFAULT_STYLES } from '@logomarks/brand-kit';
+import { wrapList } from '../help.js';
+
+/** What `kit` takes. */
+export const spec = { flags: ['json', 'animated', 'no-social'], options: { out: 'o', name: '', color: '', font: '', tagline: '', url: '', handle: '', styles: '', platforms: '' } };
+
+/** `logomarks kit --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'Build a brand kit on a mark and write it to a folder.',
+	usage: ['<mark> --name "Brand" [-o dir/] [options]'],
+	about: [
+		'Writes mark/ (SVG on light, dark and colour; PNG 64–2048), favicon/ (.ico, favicon.svg,',
+		'touch and maskable icons, manifest, head.html), lockup/, colors/ (CSS, a Tailwind theme',
+		'and tokens: a 50–950 OKLCH scale with WCAG pairings), social/, brand-sheet.png and .svg,',
+		'brand.json and README.md. Look at brand-sheet.png before handing the kit over.',
+	],
+	options: [
+		['--name <text>', "The brand's name. Default: the mark's name."],
+		['--color <hex>', 'The brand colour, e.g. #ff5c3a. Default #d4ff3a.'],
+		['--font <id>', `The typeface for the name (SIL OFL). Default inter.\n${wrapList(Object.keys(FONTS), 48)}.`],
+		['--tagline <text>', 'A short line under the name on social images and the brand sheet.'],
+		['--url <url>', "The brand's website, for the brand sheet and email signature."],
+		['--handle <@name>', 'The social handle. Default: @ and the name.'],
+		['--styles <ids>', `Social styles: ${STYLE_IDS.join(', ')}.\nDefault: ${DEFAULT_STYLES.join(', ')}.`],
+		['--platforms <ids>', 'Social images by id or platform, e.g. instagram,x-header.\nDefault: every one.'],
+		['--animated', 'Also write animated SVGs for avatars, stories and banners.'],
+		['--no-social', 'Leave the social pack out.'],
+		['-o, --out <dir>', 'The folder to write. Default <name>-kit.'],
+	],
+	examples: ["logomarks kit hex-gem --name \"Hexa Labs\" --color '#ff5c3a' --font space-grotesk -o hexa/", 'logomarks kit mark.svg --name Acme --no-social'],
+};
+
+/**
+ * Runs `kit`.
+ *
+ * @param {import('../args.js').Parsed} args The parsed arguments.
+ * @param {import('../index.js').IO} io Where output goes.
+ * @returns {Promise<number>} The exit code: 0.
+ */
+export async function run(args, io) {
+	const brand = brandArgs(args);
+	const dir = args.options.out ?? `${slugify(brand.name) || 'brand'}-kit`;
+	const k = await asUsage(() => kit({ ...brand, ...packArgs(args), social: !args.flags.has('no-social') }));
+	const n = writeFiles(dir, k.files);
+	if (args.flags.has('json')) io.out(JSON.stringify({ ok: true, dir, ...k.brand }, null, 2));
+	else {
+		io.out(`${style.green('✓')} wrote ${style.bold(`${n} files`)} to ${style.bold(dir)}: ${brand.name} in ${k.brand.colors.primary}, ${k.brand.font.name}, on ${brand.mark.name}.`);
+		io.out(style.dim('  mark/  favicon/  lockup/  colors/  social/  brand.json  README.md'));
+		io.out(`  Look at ${style.bold(path.join(dir, 'brand-sheet.png'))}.`);
+	}
+	return 0;
+}

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

@@ -0,0 +1,9 @@
+import type { ArgSpec } from '../args.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `mcp` takes: nothing. */
+export const spec: ArgSpec;
+/** What `logomarks mcp --help` prints. */
+export const help: CommandHelp;
+/** Starts the MCP server on stdio; resolves to 0 once it is connected. */
+export function run(): Promise<number>;

package/src/cli/commands/mcp.js

@@ -0,0 +1,36 @@
+/**
+ * @module logomarks/cli/commands/mcp
+ *
+ * `logomarks mcp`: the MCP server on stdio, for Claude Code, Codex, Cursor
+ * and any MCP client. Nothing is written to stdout but the protocol.
+ */
+
+/** What `mcp` takes. */
+export const spec = { flags: [], options: {} };
+
+/** `logomarks mcp --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'Run the MCP server on stdio, for Claude Code, Codex, Cursor and other agents.',
+	usage: [''],
+	about: [
+		'Every verb as an MCP tool, run locally; nothing leaves the machine. Add it to an agent:',
+		'  claude mcp add logomarks -- npx -y logomarks mcp',
+		'  codex mcp add logomarks -- npx -y logomarks mcp',
+		'Or install the Claude Code plugin, which adds the skills too:',
+		'  /plugin marketplace add logomarks/skills',
+		'  /plugin install logomarks@logomarks',
+	],
+	json: false,
+};
+
+/**
+ * Runs `mcp`: starts the server and returns; the process lives until the client hangs up.
+ *
+ * @returns {Promise<number>} The exit code: 0.
+ */
+export async function run() {
+	const { serve } = await import('../../mcp/index.js');
+	await serve();
+	return 0;
+}

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

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `mockup` takes. */
+export const spec: ArgSpec;
+/** What `logomarks mockup --help` prints. */
+export const help: CommandHelp;
+/** Runs `mockup`; resolves to its exit code (0). */
+export function run(args: Parsed, io: IO): Promise<number>;

package/src/cli/commands/mockup.js

@@ -0,0 +1,61 @@
+/**
+ * @module logomarks/cli/commands/mockup
+ *
+ * `logomarks mockup <slug|file> --object card -o out.png`: the brand on a
+ * 2D object. `-o` ending in `.svg` writes the layered SVG instead.
+ */
+
+import { mockup, OBJECTS } from '../../mockup/index.js';
+import { UsageError } from '../args.js';
+import { markArg, colorArg, fontArg, intArg, asUsage, writeFile } from '../options.js';
+import { style } from '../style.js';
+import { FONTS } from '../../brand/fonts.js';
+import { wrapList } from '../help.js';
+
+/** What `mockup` takes. */
+export const spec = { flags: ['json'], options: { out: 'o', object: '', name: '', color: '', font: '', layout: '', surface: '', view: '', base: '', size: '', seed: '' } };
+
+/** `logomarks mockup --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'Put a brand on an object and write the image.',
+	usage: ['<mark> --object <object> [-o file.png] [options]'],
+	about: [
+		`Objects: ${wrapList(Object.keys(OBJECTS), 80)}.`,
+		'Garments, mugs and bags carry the mark; prints carry the lockup on the brand colour.',
+	],
+	options: [
+		['--object <id>', 'The object (required).'],
+		['--name <text>', "The brand's name. Default: the mark's name."],
+		['--color <hex>', 'The brand colour, e.g. #ff5c3a. Default #d4ff3a.'],
+		['--font <id>', `The typeface for the name (SIL OFL). Default inter.\n${wrapList(Object.keys(FONTS), 48)}.`],
+		['--layout <id>', "One of the object's layouts (a wrong one lists them)."],
+		['--surface <id>', 'What it lies on: oak, concrete, linen, paper, light, dark or a hex.'],
+		['--view <front | angle>', "A screen's or a sign's view."],
+		['--base <colour>', "The object's own colour: white, black, navy or a hex."],
+		['--size <px>', 'The longest side, 200–4000. Default 1600.'],
+		['--seed <text>', "Drives every random choice. Default: the mark's slug."],
+		['-o, --out <file>', 'Write .png, or .svg for the layered SVG. Default <object>.png.'],
+	],
+	examples: ['logomarks mockup hex-gem --name "Hexa Labs" --object card -o card.png', 'logomarks mockup mark.svg --object tee --base black -o tee.png'],
+};
+
+/**
+ * Runs `mockup`.
+ *
+ * @param {import('../args.js').Parsed} args The parsed arguments.
+ * @param {import('../index.js').IO} io Where output goes.
+ * @returns {Promise<number>} The exit code: 0.
+ */
+export async function run(args, io) {
+	const mark = markArg(args.positionals);
+	const { object, out: file, name, layout, surface, view, base, seed } = args.options;
+	if (!object || !(object in OBJECTS)) throw new UsageError(`--object is one of ${Object.keys(OBJECTS).join(', ')}`);
+	const out = file ?? `${object}.png`;
+	const options = { mark, object, name: name?.trim() || undefined, color: colorArg(args.options.color), font: fontArg(args.options.font), layout, surface, view, base, seed, size: intArg('size', args.options.size, 200, 4000) };
+	const m = await asUsage(() => mockup(options));
+	writeFile(out, out.toLowerCase().endsWith('.svg') ? m.svg : m.png);
+	if (args.flags.has('json')) io.out(JSON.stringify({ ok: true, file: out, object, width: m.width, height: m.height }, null, 2));
+	else io.out(`${style.green('✓')} wrote ${style.bold(out)}: ${options.name ?? mark.name} on a ${object}, ${m.width} × ${m.height}.`);
+	return 0;
+}

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

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `parts` takes. */
+export const spec: ArgSpec;
+/** What `logomarks parts --help` prints. */
+export const help: CommandHelp;
+/** Runs `parts`; resolves to its exit code. */
+export function run(args: Parsed, io: IO): Promise<number>;

package/src/cli/commands/parts.js

@@ -0,0 +1,44 @@
+/**
+ * @module logomarks/cli/commands/parts
+ *
+ * `logomarks parts <slug|file.svg>`: the parts by index, as `edit --ops`
+ * names them; `-o parts.png` draws them numbered.
+ */
+
+import { markParts } from '../../edit/ops.js';
+import { partsPreview } from '../../edit/preview.js';
+import { markArg, writeFile } from '../options.js';
+import { style, pad } from '../style.js';
+
+/** What `parts` takes. */
+export const spec = { flags: ['json'], options: { out: 'o' } };
+
+/** `logomarks parts --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: "List a mark's parts by index, as edit --ops names them.",
+	usage: ['<mark> [-o parts.png]'],
+	about: ['A mark is a live slug or name, or the path to your own .svg (fitted to the grid first).'],
+	options: [['-o, --out <file.png>', 'Also draw the mark with every part boxed and numbered.']],
+	examples: ['logomarks parts quad-cove', 'logomarks parts mark.svg -o parts.png'],
+};
+
+/**
+ * Runs `parts`.
+ *
+ * @param {import('../args.js').Parsed} args The parsed arguments.
+ * @param {import('../index.js').IO} io Where output goes.
+ * @returns {Promise<number>} The exit code: 0.
+ */
+export async function run(args, io) {
+	const mark = markArg(args.positionals);
+	const list = markParts(mark.svg);
+	if (args.options.out) writeFile(args.options.out, await partsPreview(mark.svg, list));
+	if (args.flags.has('json')) io.out(JSON.stringify({ count: list.length, parts: list, ...(args.options.out && { file: args.options.out }) }, null, 2));
+	else {
+		io.out(`${style.bold(mark.name)}: ${list.length} part${list.length === 1 ? '' : 's'}`);
+		for (const p of list) io.out(`  ${pad(String(p.index), 4)}${style.dim('box')} [${p.box.join(', ')}]  ${style.dim('area')} ${p.area}${p.holes ? `  ${p.holes} hole${p.holes > 1 ? 's' : ''}` : ''}${p.tone ? '  tone 2' : ''}`);
+		if (args.options.out) io.out(`  Numbered: ${style.bold(args.options.out)}`);
+	}
+	return 0;
+}

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

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `sheet` takes. */
+export const spec: ArgSpec;
+/** What `logomarks sheet --help` prints. */
+export const help: CommandHelp;
+/** Runs `sheet`; resolves to its exit code (0 pass, 1 fail). */
+export function run(args: Parsed, io: IO): Promise<number>;

package/src/cli/commands/sheet.js

@@ -0,0 +1,66 @@
+/**
+ * @module logomarks/cli/commands/sheet
+ *
+ * `logomarks sheet <file.svg…> -o sheet.png`: a review card per mark, for
+ * an AI or a person to look at.
+ */
+
+import fs from 'node:fs';
+import { sheet } from '../../sheet/index.js';
+import { gridSheet } from '../../sheet/grid.js';
+import { svgFiles, slugOf } from '../files.js';
+import { style } from '../style.js';
+
+/** What `sheet` takes. */
+export const spec = { flags: ['json', 'strict', 'plain'], options: { out: 'o', ignore: '', cols: '' } };
+
+/** `logomarks sheet --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'Draw review cards for marks, as one PNG.',
+	usage: ['<file.svg | folder>… [-o sheet.png] [options]'],
+	about: [
+		'Each card: the mark large on dark and light with its findings boxed and numbered, at 32',
+		'and 16 px, and beside its three nearest live marks. Exit 1 when any mark fails a check or',
+		'is a near-copy.',
+	],
+	options: [
+		['-o, --out <file.png>', 'The PNG to write. Default sheet.png.'],
+		['--strict', 'Count warnings as failures too.'],
+		['--ignore <ids>', 'Leave these finding ids out.'],
+		['--plain', 'A plain labelled grid instead of review cards.'],
+		['--cols <n>', 'Columns in the plain grid. Default 8.'],
+	],
+	examples: ['logomarks sheet out/*.svg -o sheet.png', 'logomarks sheet out/ --plain --cols 6 -o batch.png'],
+};
+
+/**
+ * Runs `sheet`.
+ *
+ * @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 any mark fails its check or is a near-copy of a live mark.
+ */
+export async function run(args, io) {
+	const files = svgFiles(args.positionals);
+	const out = args.options.out ?? 'sheet.png';
+	const marks = files.map((file) => ({ name: slugOf(file), svg: fs.readFileSync(file, 'utf8') }));
+	if (args.flags.has('plain')) {
+		fs.writeFileSync(out, await gridSheet(marks, { cols: Number(args.options.cols ?? 8) || 8 }));
+		io.out(`${style.green('✓')} wrote ${style.bold(out)}: ${marks.length} mark${marks.length === 1 ? '' : 's'} in a plain grid.`);
+		return 0;
+	}
+	const s = await sheet(marks, { strict: args.flags.has('strict'), ignore: (args.options.ignore ?? '').split(',').filter(Boolean) });
+	fs.writeFileSync(out, s.png);
+	const rows = s.marks.map((m, i) => ({
+		file: files[i],
+		ok: m.report.ok,
+		errors: m.report.errors,
+		warnings: m.report.warnings,
+		nearest: m.matches.map(({ slug, score, verdict }) => ({ slug, score, verdict })),
+	}));
+	const failing = rows.filter((r) => !r.ok || r.nearest.some((n) => n.verdict === 'near-copy')).length;
+	if (args.flags.has('json')) io.out(JSON.stringify({ ok: !failing, file: out, marks: rows }, null, 2));
+	else io.out(`${failing ? style.red('✗') : style.green('✓')} wrote ${style.bold(out)}: ${rows.length} card${rows.length === 1 ? '' : 's'}${failing ? `, ${failing} failing or a near-copy` : ''}. Look at it.`);
+	return failing ? 1 : 0;
+}

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

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `similar` takes. */
+export const spec: ArgSpec;
+/** What `logomarks similar --help` prints. */
+export const help: CommandHelp;
+/** Runs `similar`; resolves to its exit code (0 pass, 1 fail). */
+export function run(args: Parsed, io: IO): Promise<number>;

package/src/cli/commands/similar.js

@@ -0,0 +1,111 @@
+/**
+ * @module logomarks/cli/commands/similar
+ *
+ * `logomarks similar <file.svg…>`: the nearest live marks, with scores.
+ * 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`
+ * with the other candidates too, and `--all <data dir>` writes "More like this"
+ * for a whole set (similar.json).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { nearestAll } from '@logomarks/core/similar';
+import { similar } from '../../similar/nearest.js';
+import { loadIndex } from '../../similar/store.js';
+import { folderIndex, indexOf, joinIndexes } from '../../similar/folder.js';
+import { outlineCoverage } from '../../similar/signature.js';
+import { slugOf } from '../files.js';
+import { SIMILAR, LETTERS } from '../../rules.js';
+import { UsageError } from '../args.js';
+import { svgFiles } from '../files.js';
+import { style, pad } from '../style.js';
+
+/** What `similar` takes. */
+export const spec = { flags: ['json', 'letters', 'each'], options: { top: '', against: '', all: '', out: 'o' } };
+
+/** `logomarks similar --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: 'Find the live marks nearest to yours, with scores.',
+	usage: ['<file.svg | folder>… [options]', '--all <data dir> [-o similar.json]'],
+	about: [
+		`Compares outlines, rotations and mirrors included. ${SIMILAR.tooClose} and up is too close (compare`,
+		`the two by eye); ${SIMILAR.nearCopy} and up is a near-copy. Exit 1 when any mark is a near-copy.`,
+	],
+	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.'],
+		['--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.'],
+	],
+	examples: ['logomarks similar mark.svg', 'logomarks similar out/ --top 3 --each', 'logomarks similar badge.svg --letters --json'],
+};
+
+/** Verdict labels for the readable output. */
+const LABEL = { 'near-copy': style.red('near-copy'), 'too-close': style.yellow('too close'), ok: style.dim('ok       ') };
+
+/**
+ * Runs `similar`.
+ *
+ * @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 any mark is a near-copy of a live one.
+ */
+export async function run(args, io) {
+	if (args.options.all) return all(args.options.all, args.options.out, io);
+	const files = svgFiles(args.positionals);
+	const top = Number(args.options.top ?? 5);
+	if (!Number.isInteger(top) || top < 1) throw new UsageError('--top takes a whole number');
+	const letters = args.flags.has('letters');
+	const base = args.options.against ? await folderIndex(args.options.against, { letters }) : loadIndex();
+	const index = args.flags.has('each') && files.length > 1 ? joinIndexes(base, await indexOf(files, { letters, candidate: true })) : base;
+	const results = [];
+	for (const file of files) {
+		const matches = await similar(fs.readFileSync(file, 'utf8'), { top, letters, index, exclude: args.flags.has('each') ? slugOf(file) : undefined });
+		results.push({ file, ok: !matches.some((m) => m.verdict === 'near-copy'), tooClose: matches.some((m) => m.verdict !== 'ok'), matches });
+	}
+	const copies = results.filter((r) => !r.ok).length;
+	const t = letters ? LETTERS : SIMILAR;
+	if (args.flags.has('json')) {
+		io.out(JSON.stringify({ ok: !copies, thresholds: { tooClose: t.tooClose, nearCopy: t.nearCopy }, live: base.marks.length, built: base.built, marks: results }, null, 2));
+	} else {
+		for (const { file, ok, tooClose, matches } of results) {
+			io.out(`${!ok ? style.red('✗') : tooClose ? style.yellow('!') : style.green('✓')} ${style.bold(file)}`);
+			if (!matches.length) io.out(style.dim('    no knocked-out letter (holes) to compare'));
+			for (const m of matches) io.out(`    ${m.score.toFixed(3)}  ${LABEL[m.verdict]}  ${pad(m.slug + (m.candidate ? ' *' : ''), 28)} ${style.dim(m.candidate ? 'another candidate' : m.name)}`);
+		}
+		const close = results.filter((r) => r.ok && r.tooClose).length;
+		io.out(`\n${results.length - copies} of ${results.length} not a near-copy of the ${base.marks.length} ${args.options.against ? 'marks' : 'live marks'}${index !== base ? ' or each other' : ''}${close ? `; ${close} too close, look at them side by side` : ''} (too close ≥ ${t.tooClose}, near-copy ≥ ${t.nearCopy})`);
+	}
+	return copies ? 1 : 0;
+}
+
+/**
+ * `similar --all <data dir>`: every mark's 8 nearest ("More like this"), by overlap of 48 px renders nudged for the
+ * same style and shared moods, from the folder's marks.json, descriptions.json and svg/.
+ *
+ * @param {string} dir The data folder.
+ * @param {string | undefined} out Where to write the JSON (default: stdout).
+ * @param {import('../index.js').IO} io Where output goes.
+ * @returns {Promise<number>} The exit code.
+ */
+async function all(dir, out, io) {
+	const read = (/** @type {string} */ f) => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+	/** @type {{ slug: string }[]} */
+	const marks = read('marks.json');
+	/** @type {Record<string, { style?: string, mood?: string[] }>} */
+	const desc = fs.existsSync(path.join(dir, 'descriptions.json')) ? read('descriptions.json') : {};
+	const set = [];
+	for (const m of marks) set.push({ slug: m.slug, alpha: await outlineCoverage(fs.readFileSync(path.join(dir, 'svg', `${m.slug}.svg`), 'utf8')), style: desc[m.slug]?.style, mood: desc[m.slug]?.mood });
+	const json = JSON.stringify(nearestAll(set)) + '\n';
+	if (out) {
+		fs.writeFileSync(out, json);
+		io.out(`similar for ${set.length} marks → ${out}`);
+	} else io.out(json.trimEnd());
+	return 0;
+}

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

@@ -0,0 +1,10 @@
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** What `social` takes. */
+export const spec: ArgSpec;
+/** What `logomarks social --help` prints. */
+export const help: CommandHelp;
+/** Runs `social`; resolves to its exit code. */
+export function run(args: Parsed, io: IO): Promise<number>;

package/src/cli/commands/social.js

@@ -0,0 +1,65 @@
+/**
+ * @module logomarks/cli/commands/social
+ *
+ * `logomarks social <slug|file.svg> --name "Brand" -o dir/`: the social pack
+ * (`@logomarks/brand-kit`): every platform image in each style, the email
+ * signature and the Open Graph card, written to a folder.
+ */
+
+import path from 'node:path';
+import { social } from '../../kit/index.js';
+import { slugify } from '../../brand/mark.js';
+import { brandArgs, packArgs, asUsage, writeFiles } from '../options.js';
+import { style } from '../style.js';
+import { FONTS } from '../../brand/fonts.js';
+import { STYLE_IDS, DEFAULT_STYLES } from '@logomarks/brand-kit';
+import { wrapList } from '../help.js';
+
+/** What `social` takes. */
+export const spec = { flags: ['json', 'animated'], options: { out: 'o', name: '', color: '', font: '', tagline: '', url: '', handle: '', styles: '', platforms: '' } };
+
+/** `logomarks social --help`. */
+/** @type {import('../help.js').CommandHelp} */
+export const help = {
+	summary: "Draw the brand for every social platform at its size, and write it to a folder.",
+	usage: ['<mark> --name "Brand" [-o dir/] [options]'],
+	about: [
+		'Every platform image with the logo inside its safe zone, in each style, as',
+		'<style>/<id>.png and .svg, plus an email signature, the Open Graph card and a README.',
+	],
+	options: [
+		['--name <text>', "The brand's name. Default: the mark's name."],
+		['--color <hex>', 'The brand colour, e.g. #ff5c3a. Default #d4ff3a.'],
+		['--font <id>', `The typeface for the name (SIL OFL). Default inter.\n${wrapList(Object.keys(FONTS), 48)}.`],
+		['--tagline <text>', 'A short line under the name on social images and the brand sheet.'],
+		['--url <url>', "The brand's website, for the brand sheet and email signature."],
+		['--handle <@name>', 'The social handle. Default: @ and the name.'],
+		['--styles <ids>', `Social styles: ${STYLE_IDS.join(', ')}.\nDefault: ${DEFAULT_STYLES.join(', ')}.`],
+		['--platforms <ids>', 'Social images by id or platform, e.g. instagram,x-header.\nDefault: every one.'],
+		['--animated', 'Also write animated SVGs for avatars, stories and banners.'],
+		['-o, --out <dir>', 'The folder to write. Default <name>-social.'],
+	],
+	examples: ['logomarks social hex-gem --name "Hexa Labs" --platforms instagram,linkedin --styles bold', 'logomarks social mark.svg --name Acme --animated -o acme-social/'],
+};
+
+/**
+ * Runs `social`.
+ *
+ * @param {import('../args.js').Parsed} args The parsed arguments.
+ * @param {import('../index.js').IO} io Where output goes.
+ * @returns {Promise<number>} The exit code: 0.
+ */
+export async function run(args, io) {
+	const brand = brandArgs(args);
+	const dir = args.options.out ?? `${slugify(brand.name) || 'brand'}-social`;
+	const pack = await asUsage(() => social({ ...brand, ...packArgs(args) }));
+	const files = [...pack.files.keys()];
+	writeFiles(dir, pack.files);
+	if (args.flags.has('json')) io.out(JSON.stringify({ ok: true, dir, count: files.length, files }, null, 2));
+	else {
+		const images = files.filter((f) => f.endsWith('.png'));
+		io.out(`${style.green('✓')} wrote ${style.bold(`${files.length} files`)} to ${style.bold(dir)}: ${images.length} images of ${brand.name}.`);
+		io.out(`  Sizes and sources: ${style.bold(path.join(dir, 'README.md'))}.`);
+	}
+	return 0;
+}

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

@@ -0,0 +1,20 @@
+import type { Box } from '@logomarks/core/geometry';
+import type { ArgSpec, Parsed } from '../args.js';
+import type { IO } from '../index.js';
+import type { CommandHelp } from '../help.js';
+
+/** One mark's small parts, as `specks` reports them. */
+export interface MarkSpecks {
+	slug: string;
+	/** Why it was read from the raster, or couldn't be read. */
+	note: string;
+	raster: boolean;
+	parts: { kind: 'piece' | 'hole' | 'mark'; area: number; width: number; box: Box | number[]; raster?: boolean; skip: string }[];
+}
+
+/** What `specks` takes. */
+export const spec: ArgSpec;
+/** What `logomarks specks --help` prints. */
+export const help: CommandHelp;
+/** Runs `specks`; resolves to 1 when anything is reported. */
+export function run(args: Parsed, io: IO): Promise<number>;