burgee 0.0.0 → 0.2.0

package/README.md

@@ -8,6 +8,33 @@ belongs to — a flag of identity, not of instruction. That is what this framewo
 a command-line program: a command declares itself once, and every surface is that
 declaration read by a different reader.
 
+```js
+// cli.mjs — the whole CLI
+import { defineCommand, run } from 'burgee';
+
+run(defineCommand({
+  name: 'greet',
+  description: 'Greet someone by name',
+  options: { name: { type: 'string', required: true, description: 'who to greet' } },
+  run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
+}));
+```
+
+```console
+$ node cli.mjs --name ada
+greeting: hello, ada
+
+$ node cli.mjs --json --name ada
+{"ok":true,"data":{"greeting":"hello, ada"}}
+
+$ node cli.mjs            # exit 2
+error: missing required option --name
+hint: pass --name <value>
+```
+
+One file. No build step, no config file, no directory convention. A test enforces
+that on every commit.
+
 ```
 defineCommand()  ──▶  manifest  ──┬──▶  human help
                                   ├──▶  --json      one stable envelope
@@ -30,6 +57,6 @@ It stays a library you import in one file: no build step, no config, no director
 convention, no scaffold. A test enforces that.
 
 Roadmap, architecture and the 79-requirement floor:
-<https://github.com/ofri-peretz/cli>
+<https://github.com/ofri-peretz/burgee>
 
 MIT © Interlace

package/dist/agent.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agent detection, not just `isTTY` (N12). An agent may well have a terminal; what it
+ * does not have is a person. Non-interactive is the default under a detected agent;
+ * `FORCE_TTY=1` overrides. The variables mirror what `@vercel/detect-agent` probes; the
+ * list is data, and `AI_AGENT` is the generic escape hatch any agent can set.
+ */
+export interface AgentProbe {
+    /** Environment variable whose presence names the agent. */
+    variable: string;
+    agent: string;
+}
+export declare const AGENT_PROBES: readonly AgentProbe[];
+export interface Detection {
+    /** The agent named by the environment, if any; `AI_AGENT`'s own value when it names one. */
+    agent?: string;
+    /** Prompts and other blocking interaction are allowed. */
+    interactive: boolean;
+}
+export declare function detectAgent(env: Record<string, string | undefined>, tty: boolean, probes?: readonly AgentProbe[]): Detection;

package/dist/agent.js

@@ -0,0 +1,25 @@
+export const AGENT_PROBES = [
+    { variable: 'AI_AGENT', agent: 'generic' },
+    { variable: 'CLAUDECODE', agent: 'claude-code' },
+    { variable: 'CURSOR_AGENT', agent: 'cursor' },
+    { variable: 'CODEX_THREAD_ID', agent: 'codex' },
+    { variable: 'GEMINI_CLI', agent: 'gemini' },
+];
+function agentName(hit, value) {
+    if (hit.variable !== 'AI_AGENT' || value === '1')
+        return hit.agent;
+    return value;
+}
+export function detectAgent(env, tty, probes = AGENT_PROBES) {
+    let agent;
+    for (const probe of probes) {
+        const value = env[probe.variable];
+        if (value !== undefined && value !== '') {
+            agent = agentName(probe, value);
+            break;
+        }
+    }
+    const forced = env['FORCE_TTY'] === '1';
+    const interactive = forced || (tty && agent === undefined);
+    return agent === undefined ? { interactive } : { agent, interactive };
+}

package/dist/brand.d.ts

@@ -0,0 +1,186 @@
+/**
+ * burgee/brand — a brand declares itself once; every identity surface is that
+ * declaration read by a different reader.
+ *
+ * The same thesis as the rest of the package, applied to identity instead of
+ * argv. You declare a field and a mark; out come the flag, the favicon, the OG
+ * card and the article cover, every one a projection of that declaration, so
+ * none of them can drift from the others.
+ *
+ * THE FLAG. A burgee is the swallowtail flag a boat flies to say which club it
+ * belongs to — a flag of identity, not of instruction. This one is composed the
+ * way real club burgees are: a field, and one charge upon it. The field is a
+ * gradient run BACKWARDS along the axis the two Interlace bars are stacked on,
+ * so the leading bar sits over the following bar's colour and the reverse. The
+ * charge is the Interlace mark itself.
+ *
+ * WHY THE MIDPOINT STOP IS LOAD-BEARING. Deep rock on deep juniper measures
+ * 1.16:1 — invisible. The middle stop drops the field to near-black exactly
+ * where the charge sits, lifting the two bars to 3.50:1 and 3.02:1, both
+ * clearing the 3:1 floor WCAG sets for a graphical object. Remove that stop and
+ * the mark disappears. It is contrast, not decoration.
+ *
+ * NOT in the core entry point. `import { defineCommand } from "burgee"` must
+ * stay one import of one file with no build step; this is a separate subpath and
+ * costs that path nothing.
+ *
+ * DETERMINISM. No timestamps, no randomness, coordinates rounded to 2dp. The one
+ * id in the output — a gradient cannot be anonymous — is derived from the
+ * declaration itself, so the same brand always produces the same bytes and two
+ * different brands can share a page without colliding.
+ */
+/** A point in the mark space. */
+export type Point = readonly [number, number];
+export declare const BURGEE_FLAG: readonly Point[];
+export declare const BURGEE_ANGLE: number;
+/** The charge occupies this fraction of the flag, and sits here within it. */
+export declare const CHARGE: {
+    readonly scale: 0.4;
+    readonly x: 42;
+    readonly y: 50;
+};
+/**
+ * The gradient axis: the direction the two bars are stacked on, traversed
+ * backwards — hoist-top to fly-bottom, in mark-space coordinates.
+ */
+export declare const FIELD_AXIS: {
+    readonly x1: 25;
+    readonly y1: 6.7;
+    readonly x2: 75;
+    readonly y2: 93.3;
+};
+/** One gradient stop: how far along the axis, and what colour. */
+export interface FieldStop {
+    offset: number;
+    color: string;
+}
+/** One band of the outline. */
+export interface Bordure {
+    color: string;
+    /** Visible thickness, in mark-space units. */
+    width: number;
+}
+export interface BurgeeColors {
+    /** Leading bar, hoist side. */
+    lead: string;
+    /** Following bar, fly side. */
+    follow: string;
+}
+export interface BurgeeBrand {
+    /** Accessible name for the flag. Without one the flag is decorative. */
+    name?: string;
+    /**
+     * The charge, as a two-colour bar pair. Ignored when {@link BurgeeBrand.charge}
+     * is given — that is the escape hatch for a CLI bringing its own glyph.
+     */
+    mark: BurgeeColors;
+    /**
+     * Your own charge instead of the bars: SVG markup drawn in a 0 0 100 100 box,
+     * which burgee places and scales for you. Everything else — the swallowtail,
+     * the reversed field, the sizes — still comes from this one declaration.
+     *
+     * The markup is emitted verbatim, so it is yours to trust: this runs at build
+     * time on a file you wrote, not on anything a user supplies at runtime.
+     */
+    charge?: string;
+    /**
+     * The field, as gradient stops along {@link FIELD_AXIS}. One stop is a flat
+     * field. Keep a dark stop under the charge or the mark will not read.
+     */
+    field: readonly FieldStop[];
+    /**
+     * The outline, outermost band first.
+     *
+     * One band is enough when you control the ground. Two is what you want when
+     * you do not: no single flat colour clears 3:1 against both a near-black and a
+     * white page, so a dark outer band and a light inner band are given, and
+     * whichever one the ground does not match is the one carrying the silhouette.
+     * That is one asset that holds its outline anywhere — which a favicon, having
+     * no stylesheet to read a theme from, actually needs.
+     *
+     * `width` is the visible thickness of each band in mark-space units.
+     */
+    bordure?: Bordure | readonly Bordure[];
+}
+/** The midpoint a field falls through when none is given. Near-black. */
+export declare const DEFAULT_GROUND = "#0a0a0a";
+/**
+ * The field two colours imply.
+ *
+ * Reversed on purpose: the leading colour goes at the FAR end, so the leading
+ * half of the charge sits against the following colour and the reverse. Through
+ * a dark midpoint, because the charge sits at the centre and two saturated
+ * colours of similar weight cannot be told apart — the reason this is a default
+ * rather than something each caller re-derives.
+ */
+export declare function opposedField(colors: BurgeeColors, ground?: string): FieldStop[];
+/** The flag silhouette, as SVG path data. */
+export declare function burgeeFlagPath(): string;
+/**
+ * A stable id for the field gradient, derived from the declaration.
+ *
+ * A gradient is the one thing in SVG that cannot be anonymous. Deriving the id
+ * from the brand keeps output byte-identical across runs, and keeps two
+ * different brands from colliding when they share a page. Two instances of the
+ * SAME brand do share an id, which is harmless — the definitions are identical —
+ * and a React caller can pass its own `useId()` value instead.
+ */
+export declare function fieldId(brand: BurgeeBrand): string;
+/**
+ * Where the charge sits, as an SVG transform. Exported because consumers that
+ * hand-write the flag (a React component, say) must place it identically, and
+ * recomputing it at the call site is how the two drift apart.
+ */
+export declare function chargeTransform(scale?: number): string;
+/** The angle the charge is rotated by, as an SVG transform. */
+export declare function chargeRotation(): string;
+/** Place any charge markup where the charge belongs, at the charge's scale. */
+export declare function placeCharge(markup: string, scale?: number): string;
+/** The two Interlace bars, rotated and placed as the charge. */
+export declare function chargeGroup(colors: BurgeeColors, scale?: number): string;
+/** Field, charge and optional bordure — everything inside the viewBox. */
+export declare function burgeeBody(brand: BurgeeBrand, id?: string): string;
+export interface CardOptions {
+    width?: number;
+    height?: number;
+    /** Large line. Defaults to the brand name. */
+    title?: string;
+    /** Small line under it; wraps. */
+    subtitle?: string;
+    theme?: 'light' | 'dark';
+    background?: string;
+    foreground?: string;
+    muted?: string;
+}
+/** Everything one brand declaration projects into. */
+export interface Burgee {
+    /** The flag alone, square, at any size. */
+    flag(size?: number): string;
+    /** Favicon master. One file serves both themes — the flag carries its own field. */
+    favicon(size?: number): string;
+    /** Social card, 1200×630. */
+    og(options?: CardOptions): string;
+    /** Article cover, 1000×420. */
+    cover(options?: CardOptions): string;
+    /** Flag and wordmark, laid out horizontally. */
+    lockup(options?: CardOptions): string;
+    /** The gradient id this brand emits, for callers that need to match it. */
+    fieldId(): string;
+}
+/**
+ * Declare a brand. Everything on the returned object is a projection of it.
+ *
+ * ```js
+ * const brand = defineBurgee({
+ *   name: 'burgee',
+ *   mark: { lead: '#a84c17', follow: '#0a6b47' },
+ *   field: [
+ *     { offset: 0, color: '#0a6b47' },
+ *     { offset: 0.5, color: '#0a0a0a' },
+ *     { offset: 1, color: '#a84c17' },
+ *   ],
+ * });
+ * writeFileSync('icon.svg', brand.favicon());
+ * ```
+ */
+export declare function defineBurgee(brand: BurgeeBrand): Burgee;

package/dist/brand.js

@@ -0,0 +1,232 @@
+const MARK = { SPAN: 100, CENTRE: 50 };
+const INTEGER_EPSILON = 0.005;
+const HOIST = { x: 10, top: 20, bottom: 80 };
+const FLY = { x: 94, top: 32, bottom: 68 };
+const NOTCH = { x: 66, y: 50 };
+export const BURGEE_FLAG = [
+    [HOIST.x, HOIST.top],
+    [FLY.x, FLY.top],
+    [NOTCH.x, NOTCH.y],
+    [FLY.x, FLY.bottom],
+    [HOIST.x, HOIST.bottom],
+];
+const BAR = { width: 52, height: 24, radius: 12 };
+const LEAD_BAR = { x: 15, y: 24 };
+const FOLLOW_BAR = { x: 33, y: 52 };
+const INTERLACE_ROTATION_DEGREES = 30;
+export const BURGEE_ANGLE = -INTERLACE_ROTATION_DEGREES;
+export const CHARGE = { scale: 0.4, x: 42, y: 50 };
+export const FIELD_AXIS = { x1: 25, y1: 6.7, x2: 75, y2: 93.3 };
+export const DEFAULT_GROUND = '#0a0a0a';
+const MIDPOINT = 0.5;
+export function opposedField(colors, ground = DEFAULT_GROUND) {
+    return [
+        { offset: 0, color: colors.follow },
+        { offset: MIDPOINT, color: ground },
+        { offset: 1, color: colors.lead },
+    ];
+}
+function round(n) {
+    return Math.abs(n - Math.round(n)) < INTEGER_EPSILON ? String(Math.round(n)) : n.toFixed(2);
+}
+function toPath(points) {
+    return `M${points.map(([x, y]) => `${round(x)} ${round(y)}`).join(' L')} Z`;
+}
+export function burgeeFlagPath() {
+    return toPath(BURGEE_FLAG);
+}
+function escape(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const HASH_SEED = 5381;
+const HASH_SHIFT = 5;
+const HASH_RADIX = 36;
+export function fieldId(brand) {
+    const source = JSON.stringify([brand.field, brand.mark, brand.bordure, brand.charge]);
+    let h = HASH_SEED;
+    for (let i = 0; i < source.length; i++) {
+        h = ((h << HASH_SHIFT) + h + (source.codePointAt(i) ?? 0)) >>> 0;
+    }
+    return `burgee-${h.toString(HASH_RADIX)}`;
+}
+function gradient(brand, id) {
+    const stops = brand.field
+        .map((s) => `<stop offset="${round(s.offset)}" stop-color="${s.color}"/>`)
+        .join('');
+    return (`<linearGradient id="${id}" gradientUnits="userSpaceOnUse"` +
+        ` x1="${FIELD_AXIS.x1}" y1="${FIELD_AXIS.y1}" x2="${FIELD_AXIS.x2}" y2="${FIELD_AXIS.y2}">` +
+        `${stops}</linearGradient>`);
+}
+export function chargeTransform(scale = CHARGE.scale) {
+    const tx = round(CHARGE.x - MARK.CENTRE * scale);
+    const ty = round(CHARGE.y - MARK.CENTRE * scale);
+    return `translate(${tx} ${ty}) scale(${round(scale)})`;
+}
+export function chargeRotation() {
+    return `rotate(${BURGEE_ANGLE} ${MARK.CENTRE} ${MARK.CENTRE})`;
+}
+export function placeCharge(markup, scale = CHARGE.scale) {
+    return `<g transform="${chargeTransform(scale)}">${markup}</g>`;
+}
+export function chargeGroup(colors, scale = CHARGE.scale) {
+    const bar = (at, fill) => `<rect x="${at.x}" y="${at.y}" width="${BAR.width}" height="${BAR.height}"` +
+        ` rx="${BAR.radius}" fill="${fill}"/>`;
+    return (`<g transform="${chargeTransform(scale)}">` +
+        `<g transform="${chargeRotation()}">` +
+        `${bar(LEAD_BAR, colors.lead)}${bar(FOLLOW_BAR, colors.follow)}</g></g>`);
+}
+function bordureBands(brand) {
+    if (brand.bordure === undefined)
+        return '';
+    const bands = Array.isArray(brand.bordure)
+        ? [...brand.bordure]
+        : [brand.bordure];
+    if (bands.length === 0)
+        return '';
+    let total = bands.reduce((sum, band) => sum + band.width, 0);
+    const path = burgeeFlagPath();
+    const drawn = [];
+    for (const band of bands) {
+        drawn.push(`<path d="${path}" fill="none" stroke="${band.color}"` +
+            ` stroke-width="${round(total * 2)}" stroke-linejoin="round"/>`);
+        total -= band.width;
+    }
+    return drawn.join('');
+}
+export function burgeeBody(brand, id = fieldId(brand)) {
+    const charge = brand.charge === undefined ? chargeGroup(brand.mark) : placeCharge(brand.charge);
+    return (`${gradient(brand, id)}${bordureBands(brand)}` +
+        `<path d="${burgeeFlagPath()}" fill="url(#${id})"/>${charge}`);
+}
+const FONT = 'ui-monospace, SFMono-Regular, Menlo, monospace';
+const TRACKING_TIGHTEN = 0.03;
+const LAYOUT = {
+    GAP: 0.28,
+    TITLE: 0.42,
+    SUBTITLE: 0.13,
+    ADVANCE: 0.62,
+    TITLE_CENTRE: 0.36,
+    SUBTITLE_LEAD: 1.6,
+    LINE_HEIGHT: 1.4,
+    TEXT_COLUMN: 0.46,
+    TRACKING: -TRACKING_TIGHTEN,
+};
+const SIZES = {
+    OG: { width: 1200, height: 630, mark: 260 },
+    COVER: { width: 1000, height: 420, mark: 180 },
+    LOCKUP: { width: 480, height: 120, mark: 84 },
+    FAVICON: 512,
+};
+const GROUND = {
+    dark: { background: '#12201b', foreground: '#f0f3f6', muted: '#9aada5' },
+    light: { background: '#efe9dd', foreground: '#0a0a0a', muted: '#5c6058' },
+};
+function flagGroup(brand, x, y, size) {
+    const scale = size / MARK.SPAN;
+    return (`<g transform="translate(${round(x)} ${round(y)}) scale(${round(scale)})">` +
+        `${burgeeBody(brand)}</g>`);
+}
+function wrap(text, columns) {
+    if (text === '')
+        return [];
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        const candidate = line === '' ? word : `${line} ${word}`;
+        if (candidate.length > columns && line !== '') {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = candidate;
+        }
+    }
+    if (line !== '')
+        lines.push(line);
+    return lines;
+}
+const advance = (chars, size) => chars * size * LAYOUT.ADVANCE;
+function textElement({ x, y, size, fill, bold, text }) {
+    const weight = bold ? ` font-weight="700" letter-spacing="${round(size * LAYOUT.TRACKING)}"` : '';
+    return (`<text x="${round(x)}" y="${round(y)}" font-family="${FONT}" font-size="${round(size)}"` +
+        `${weight} fill="${fill}">${escape(text)}</text>`);
+}
+function renderCard(brand, options, size) {
+    const theme = options.theme ?? 'dark';
+    const ground = GROUND[theme];
+    const background = options.background ?? ground.background;
+    const foreground = options.foreground ?? ground.foreground;
+    const muted = options.muted ?? ground.muted;
+    const width = options.width ?? size.width;
+    const height = options.height ?? size.height;
+    const title = options.title ?? brand.name ?? '';
+    const subtitle = options.subtitle ?? '';
+    const gap = size.mark * LAYOUT.GAP;
+    const titleSize = size.mark * LAYOUT.TITLE;
+    const subSize = size.mark * LAYOUT.SUBTITLE;
+    const lineHeight = subSize * LAYOUT.LINE_HEIGHT;
+    const columns = Math.floor((width * LAYOUT.TEXT_COLUMN) / (subSize * LAYOUT.ADVANCE));
+    const lines = wrap(subtitle, columns);
+    const textWidth = Math.max(advance(title.length, titleSize), ...lines.map((line) => advance(line.length, subSize)));
+    const left = (width - (size.mark + gap + textWidth)) / 2;
+    const centreY = height / 2;
+    const textX = left + size.mark + gap;
+    const blockHeight = titleSize +
+        (lines.length === 0 ? 0 : subSize * LAYOUT.SUBTITLE_LEAD + (lines.length - 1) * lineHeight);
+    const titleY = lines.length === 0
+        ? centreY + titleSize * LAYOUT.TITLE_CENTRE
+        : centreY - blockHeight / 2 + titleSize;
+    const label = escape([title, subtitle].filter(Boolean).join(' — ') || brand.name || 'burgee');
+    const parts = [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"` +
+            ` viewBox="0 0 ${width} ${height}" role="img" aria-label="${label}">`,
+        `<rect width="${width}" height="${height}" fill="${background}"/>`,
+        flagGroup(brand, left, centreY - size.mark / 2, size.mark),
+    ];
+    if (title) {
+        parts.push(textElement({
+            x: textX,
+            y: titleY,
+            size: titleSize,
+            fill: foreground,
+            bold: true,
+            text: title,
+        }));
+    }
+    lines.forEach((line, i) => {
+        parts.push(textElement({
+            x: textX,
+            y: titleY + subSize * LAYOUT.SUBTITLE_LEAD + i * lineHeight,
+            size: subSize,
+            fill: muted,
+            bold: false,
+            text: line,
+        }));
+    });
+    parts.push('</svg>');
+    return parts.join('\n');
+}
+function renderFlag(brand, size) {
+    const label = brand.name ? ` role="img" aria-label="${escape(brand.name)}"` : ' aria-hidden="true"';
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${MARK.SPAN} ${MARK.SPAN}"` +
+            ` width="${size}" height="${size}"${label}>`,
+        `  ${burgeeBody(brand)}`,
+        '</svg>',
+    ].join('\n');
+}
+export function defineBurgee(brand) {
+    return {
+        flag: (size = MARK.SPAN) => renderFlag(brand, size),
+        favicon: (size = SIZES.FAVICON) => renderFlag(brand, size),
+        og: (options = {}) => renderCard(brand, options, SIZES.OG),
+        cover: (options = {}) => renderCard(brand, options, SIZES.COVER),
+        lockup: (options = {}) => renderCard(brand, options, SIZES.LOCKUP),
+        fieldId: () => fieldId(brand),
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,51 @@
+export declare const brandCommand: import("./execute.js").Command<{
+    readonly lead: {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "leading colour, hex. Your primary; it leads the charge upper-left";
+    };
+    readonly follow: {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "following colour, hex. Your secondary; it follows lower-right";
+    };
+    readonly name: {
+        readonly type: "string";
+        readonly description: "brand name, used as the accessible label and card title";
+    };
+    readonly ground: {
+        readonly type: "string";
+        readonly default: "#0a0a0a";
+        readonly description: "the field’s dark midpoint, which is what keeps the charge legible";
+    };
+    readonly charge: {
+        readonly type: "string";
+        readonly description: "path to an SVG whose contents replace the bars, drawn in a 0 0 100 100 box";
+    };
+    readonly bordure: {
+        readonly type: "string";
+        readonly description: "outline colour, hex. Omit for no outline";
+    };
+    readonly 'bordure-width': {
+        readonly type: "string";
+        readonly default: "1.5";
+        readonly description: "outline width";
+    };
+    readonly tagline: {
+        readonly type: "string";
+        readonly description: "one line under the name on the card and cover";
+    };
+    readonly out: {
+        readonly type: "string";
+        readonly description: "directory to write into. Omit to print the flag only";
+    };
+    readonly on: {
+        readonly type: "string";
+        readonly description: "page colour(s) the flag will fly on, comma separated. Checked for contrast";
+    };
+    readonly 'allow-low-contrast': {
+        readonly type: "boolean";
+        readonly description: "emit anyway when a contrast check fails. Says so in the output";
+    };
+}>;
+export declare const program: import("./manifest.js").Manifest;

package/dist/cli.js

@@ -0,0 +1,105 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_GROUND, defineBurgee, opposedField } from './brand.js';
+import { auditBurgee, report } from './contrast.js';
+import { defineCommand, defineProgram, run } from './execute.js';
+const MASTER = 512;
+const CONTRAST_HINT = 'hint: darken the --ground stop under the charge, or pass --allow-low-contrast';
+const DEFAULT_BORDURE_WIDTH = '1.5';
+function surfaces(brand, tagline) {
+    const burgee = defineBurgee(brand);
+    const subtitle = tagline === '' ? {} : { subtitle: tagline };
+    return [
+        { file: 'flag.svg', svg: burgee.flag(MASTER) },
+        { file: 'icon.svg', svg: burgee.favicon() },
+        { file: 'og.svg', svg: burgee.og(subtitle) },
+        { file: 'cover.svg', svg: burgee.cover(subtitle) },
+        { file: 'lockup.svg', svg: burgee.lockup({ theme: 'dark' }) },
+        { file: 'lockup-light.svg', svg: burgee.lockup({ theme: 'light' }) },
+    ];
+}
+export const brandCommand = defineCommand({
+    name: 'brand',
+    description: 'Generate a burgee — flag, favicon, social card, cover and lockup — from two colours',
+    options: {
+        lead: {
+            type: 'string',
+            required: true,
+            description: 'leading colour, hex. Your primary; it leads the charge upper-left',
+        },
+        follow: {
+            type: 'string',
+            required: true,
+            description: 'following colour, hex. Your secondary; it follows lower-right',
+        },
+        name: { type: 'string', description: 'brand name, used as the accessible label and card title' },
+        ground: {
+            type: 'string',
+            default: DEFAULT_GROUND,
+            description: 'the field’s dark midpoint, which is what keeps the charge legible',
+        },
+        charge: {
+            type: 'string',
+            description: 'path to an SVG whose contents replace the bars, drawn in a 0 0 100 100 box',
+        },
+        bordure: { type: 'string', description: 'outline colour, hex. Omit for no outline' },
+        'bordure-width': { type: 'string', default: DEFAULT_BORDURE_WIDTH, description: 'outline width' },
+        tagline: { type: 'string', description: 'one line under the name on the card and cover' },
+        out: { type: 'string', description: 'directory to write into. Omit to print the flag only' },
+        'on': {
+            type: 'string',
+            description: 'page colour(s) the flag will fly on, comma separated. Checked for contrast',
+        },
+        'allow-low-contrast': {
+            type: 'boolean',
+            description: 'emit anyway when a contrast check fails. Says so in the output',
+        },
+    },
+    run: ({ options }) => {
+        const lead = options.lead ?? '';
+        const follow = options.follow ?? '';
+        const colors = { lead, follow };
+        const charge = options.charge === undefined
+            ? {}
+            : { charge: readFileSync(options.charge, 'utf8').replace(/<\/?svg[^>]*>/g, '').trim() };
+        const bordure = options.bordure === undefined
+            ? {}
+            : {
+                bordure: {
+                    color: options.bordure,
+                    width: Number(options['bordure-width'] ?? DEFAULT_BORDURE_WIDTH),
+                },
+            };
+        const brand = {
+            ...(options.name === undefined ? {} : { name: options.name }),
+            mark: colors,
+            field: opposedField(colors, options.ground ?? DEFAULT_GROUND),
+            ...charge,
+            ...bordure,
+        };
+        const grounds = (options.on ?? '')
+            .split(',')
+            .map((g) => g.trim())
+            .filter((g) => g !== '');
+        const findings = auditBurgee(brand, grounds);
+        const failed = findings.filter((f) => !f.passes);
+        if (failed.length > 0 && options['allow-low-contrast'] !== true) {
+            throw new Error(`contrast below WCAG AA:\n${report(failed)}\n${CONTRAST_HINT}`);
+        }
+        const written = surfaces(brand, options.tagline ?? '');
+        const contrast = findings.map((f) => ({ what: f.what, ratio: f.ratio, passes: f.passes }));
+        if (options.out === undefined) {
+            return { flag: defineBurgee(brand).flag(MASTER), files: [], contrast };
+        }
+        mkdirSync(options.out, { recursive: true });
+        for (const s of written)
+            writeFileSync(join(options.out, s.file), `${s.svg}\n`);
+        return { out: options.out, files: written.map((s) => s.file), contrast };
+    },
+});
+export const program = defineProgram({
+    name: 'burgee',
+    description: 'The agent-native CLI framework, and the tools that come with it',
+    commands: [brandCommand],
+});
+run(program);

package/dist/commander-argument.d.ts

@@ -0,0 +1,22 @@
+export type ParseArg = (value: string, previous: unknown) => unknown;
+export declare class Argument {
+    description: string;
+    variadic: boolean;
+    parseArg: ParseArg | undefined;
+    defaultValue: unknown;
+    defaultValueDescription: string | undefined;
+    argChoices: string[] | undefined;
+    required: boolean;
+    _name: string;
+    /** `<required>`, `[optional]`, bare = required; a trailing `...` makes it variadic. */
+    constructor(name: string, description?: string);
+    name(): string;
+    _collectValue(value: unknown, previous: unknown): unknown[];
+    default(value: unknown, description?: string): this;
+    argParser(fn?: ParseArg): this;
+    choices(values: readonly string[]): this;
+    argRequired(): this;
+    argOptional(): this;
+}
+/** `<name>` / `[name]` / `<name...>` for usage strings. */
+export declare function humanReadableArgName(arg: Argument): string;