burgee 0.4.0 → 0.5.0

package/dist/contrast.d.ts

@@ -10,18 +10,14 @@
  * WCAG 2.2 sets 4.5:1 for body text and 3:1 for large text and for the parts of
  * a graphic you need in order to understand it. A logo's bars are the latter, so
  * 3:1 is the floor used here — see `AA`.
+ *
+ * The measuring is `roundel`'s, not ours. Colour is the layer below this one, and until
+ * 2026-09-09 both packages carried the same forty lines of WCAG luminance — identical
+ * constants, identical maths, differing only in which package name the hex error says.
+ * What is left here is the part that is actually about a burgee: which pairs of a flag's
+ * own colours have to clear the floor, and how to say so to a person running `burgee brand`.
  */
-/** The floors WCAG 2.2 sets, as ratios. */
-export declare const AA: {
-    /** Body text against its background. */
-    readonly TEXT: 4.5;
-    /** Large text, UI components, and meaningful parts of a graphic. */
-    readonly GRAPHIC: 3;
-};
-/** WCAG relative luminance. */
-export declare function luminance(hex: string): number;
-/** The WCAG contrast ratio between two colours. Order does not matter. */
-export declare function contrast(a: string, b: string): number;
+import { AA, contrast, luminance } from 'roundel/contrast';
 /** Mix two colours in sRGB. Enough for reading a gradient stop, not for colour science. */
 export declare function mix(a: string, b: string, t: number): string;
 export interface ContrastFinding {
@@ -68,3 +64,5 @@ export interface AuditInput {
  * intrinsic pair and fails a ground has a page problem, not a logo problem.
  */
 export declare function auditBurgee(brand: AuditInput, grounds?: readonly string[]): ContrastFinding[];
+/** Re-exported so a caller reading a burgee's contrast needs one import, not two. */
+export { AA, contrast, luminance };

package/dist/contrast.js

@@ -1,38 +1,6 @@
-export const AA = {
-    TEXT: 4.5,
-    GRAPHIC: 3,
-};
+import { AA, channels, contrast, luminance } from 'roundel/contrast';
 const SRGB_MAX = 255;
-const LINEAR_THRESHOLD = 0.03928;
-const LINEAR_DIVISOR = 12.92;
-const GAMMA_OFFSET = 0.055;
-const GAMMA_SCALE = 1.055;
-const GAMMA_EXPONENT = 2.4;
-const LUMA = { r: 0.2126, g: 0.7152, b: 0.0722 };
-const CONTRAST_OFFSET = 0.05;
-const RED_AT = 1;
-const GREEN_AT = 3;
-const BLUE_AT = 5;
-const HEX_PAIRS = [RED_AT, GREEN_AT, BLUE_AT];
 const HEX_RADIX = 16;
-const SHORT_HEX_LENGTH = 4;
-function channels(hex) {
-    const full = hex.length === SHORT_HEX_LENGTH
-        ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`
-        : hex;
-    if (!/^#[0-9a-fA-F]{6}$/.test(full))
-        throw new Error(`burgee: "${hex}" is not a hex colour`);
-    const parsed = HEX_PAIRS.map((i) => Number.parseInt(full.slice(i, i + 2), HEX_RADIX) / SRGB_MAX);
-    return parsed;
-}
-export function luminance(hex) {
-    const [r, g, b] = channels(hex).map((v) => v <= LINEAR_THRESHOLD ? v / LINEAR_DIVISOR : ((v + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA_EXPONENT);
-    return LUMA.r * r + LUMA.g * g + LUMA.b * b;
-}
-export function contrast(a, b) {
-    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
-    return (hi + CONTRAST_OFFSET) / (lo + CONTRAST_OFFSET);
-}
 export function mix(a, b, t) {
     const [ca, cb] = [channels(a), channels(b)];
     const hex = ca
@@ -91,3 +59,4 @@ export function auditBurgee(brand, grounds = []) {
     }
     return findings;
 }
+export { AA, contrast, luminance };

package/dist/schema.d.ts

@@ -42,10 +42,42 @@ export interface CommandSchema {
     plugin?: string;
     arguments: ArgumentSpec[];
     options: Record<string, OptionSpec>;
+    /**
+     * The constraints between options (S2/S6), which `validate.ts` already enforces and the
+     * schema did not publish. Without them an agent can only discover that `--a` conflicts
+     * with `--b` by sending both and reading exit 2 — a round trip per constraint, and under
+     * E1 an exit 2 means *rewrite the command*, so it may well send the same pair again.
+     *
+     * Omitted entirely when a command declares none, so a reader can tell "no constraints"
+     * from "constraints not published".
+     */
+    relations?: PublishedRelation[];
     examples: Example[];
     /** The arguments and options as one JSON Schema object — what an MCP tool call takes. */
     inputSchema: JsonSchema;
 }
+/**
+ * A relation as JSON can carry it.
+ *
+ * `implies` takes either another option's name or a **predicate over the values**, and a
+ * function cannot be published. `JSON.stringify` turns it into `null` without a word, which
+ * would hand an agent `["force", null]` and let it conclude the constraint is malformed
+ * rather than unevaluable. So a predicate becomes the string `"(predicate)"`: the pair is
+ * still visible, and what is missing says so.
+ */
+export type PublishedRelation = {
+    exactlyOneOf: readonly string[];
+} | {
+    atLeastOneOf: readonly string[];
+} | {
+    atMostOneOf: readonly string[];
+} | {
+    conflicts: readonly string[];
+} | {
+    implies: readonly [string, string];
+};
+/** The marker a predicate leaves behind. Not a name any option can have — it has parentheses. */
+export declare const PREDICATE = "(predicate)";
 export interface ProgramSchema {
     schemaVersion: 1;
     name: string;

package/dist/schema.js

@@ -1,4 +1,11 @@
 import { kebab } from './names.js';
+export const PREDICATE = '(predicate)';
+function publishable(relation) {
+    if (!('implies' in relation))
+        return relation;
+    const [option, consequent] = relation.implies;
+    return { implies: [option, typeof consequent === 'function' ? PREDICATE : consequent] };
+}
 function argumentProperty(a) {
     const p = a.variadic === true ? { type: 'array', items: { type: 'string' } } : { type: 'string' };
     if (a.description !== undefined)
@@ -76,6 +83,8 @@ export function commandSchemaOf(node, root) {
         out.lazy = true;
     if (node.plugin !== undefined)
         out.plugin = node.plugin;
+    if (node.relations !== undefined && node.relations.length > 0)
+        out.relations = node.relations.map(publishable);
     return out;
 }
 export function runnable(manifest) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -95,6 +95,9 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "roundel": "^0.3.0"
+  },
   "devDependencies": {
     "vitest": "^5.0.0"
   },