burgee 0.4.0 → 0.6.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/execute.js

@@ -1,5 +1,6 @@
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
+import { ConfigError, explain, resolve as resolveLayers } from 'seniority';
 import { detectAgent } from './agent.js';
 import { ExitCode, isExitCode } from './exit-code.js';
 import { renderHelp } from './help.js';
@@ -7,7 +8,6 @@ import { Manifest } from './manifest.js';
 import { serveMcp } from './mcp.js';
 import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
-import { ConfigError, explain, resolve as resolveLayers } from './precedence.js';
 import { commandSchemaOf, machineJson, schemaOf, summaryOf } from './schema.js';
 import { checkDefinition, checkRelations, coerce, UsageError } from './validate.js';
 function helpFields(c) {
@@ -159,7 +159,7 @@ function packageLayer(pkg, name) {
     return typeof field === 'object' && field !== null && !Array.isArray(field) ? { path: pkg.path, data: field } : undefined;
 }
 async function configLayers(name, values, io) {
-    const { discover } = await import('./config.js');
+    const { discover } = await import('seniority');
     const explicit = values['config'];
     const disabled = values['noConfig'] === true;
     const loaded = await discover({ name, cwd: io.cwd, env: io.env, ...(typeof explicit === 'string' ? { explicit } : {}), disabled });

package/dist/index.d.ts

@@ -11,6 +11,6 @@ export { camel, checkDefinition, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent, type AgentProbe, type Detection } from './agent.js';
 export { renderHelp, type HelpOptions, type HelpTheme, type HelpToken } from './help.js';
 export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, type Invoke, type ServeOptions, type Tool, type ToolAnnotations } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from './precedence.js';
+export { ConfigError, envName, explain, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from 'seniority';
 export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, type CommandSchema, type JsonSchema, type ProgramSchema, type SchemaSummary } from './schema.js';
 export { definePlugin, Manifest, type ArgumentSpec, type CommandNode, type Effects, type Example, type Hook, type LazyModule, type OptionSpec, type ActionRequiredSpec, type Plugin, type Relation, type RunContext, type StandardResult, type StandardSchemaV1, } from './manifest.js';

package/dist/index.js

@@ -4,6 +4,6 @@ export { camel, checkDefinition, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent } from './agent.js';
 export { renderHelp } from './help.js';
 export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming } from './precedence.js';
+export { ConfigError, envName, explain, resolve, screaming } from 'seniority';
 export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
 export { definePlugin, Manifest, } from './manifest.js';

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.6.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,10 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "roundel": "^0.3.0",
+    "seniority": "^0.1.0"
+  },
   "devDependencies": {
     "vitest": "^5.0.0"
   },

package/dist/config.d.ts

@@ -1,28 +0,0 @@
-import { type Layer } from './precedence.js';
-export interface Discovery {
-    name: string;
-    cwd: string;
-    env: Record<string, string | undefined>;
-    /** `--config <path>`. */
-    explicit?: string;
-    /** `--no-config`. */
-    disabled?: boolean;
-}
-export interface Loaded extends Layer {
-    /** The files merged, outermost first — what `--explain` shows. */
-    chain: string[];
-}
-/** Objects merge recursively; anything else, the later value wins. */
-export declare function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown>;
-/** Load a file and everything it extends, outermost first, the file's own keys winning. */
-export declare function loadWithExtends(path: string, seen?: string[]): Promise<Loaded>;
-/** The discovery order as candidate paths, first hit wins; each entry says why it was tried. */
-export declare function candidates(d: Discovery): {
-    path: string;
-    reason: string;
-}[];
-/**
- * Discover and load. `package.json#<name>` is not a file here — the engine reads the
- * owning package.json itself and treats the field as its own layer, below config.
- */
-export declare function discover(d: Discovery): Promise<Loaded | undefined>;

package/dist/config.js

@@ -1,98 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { ConfigError } from './precedence.js';
-const EXTENSIONS = ['.json', '.mjs', '.js', '.cjs'];
-const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-export function deepMerge(base, over) {
-    const out = new Map(Object.entries(base));
-    for (const [k, v] of Object.entries(over)) {
-        const prev = out.get(k);
-        out.set(k, isObject(prev) && isObject(v) ? deepMerge(prev, v) : v);
-    }
-    return Object.fromEntries(out);
-}
-async function loadFile(path) {
-    if (path.endsWith('.json')) {
-        try {
-            const parsed = JSON.parse(readFileSync(path, 'utf8'));
-            if (!isObject(parsed))
-                throw new ConfigError(`${path} must contain an object`);
-            return parsed;
-        }
-        catch (cause) {
-            if (cause instanceof ConfigError)
-                throw cause;
-            throw new ConfigError(`${path} is not valid JSON`, cause instanceof Error ? cause.message : undefined);
-        }
-    }
-    const mod = (await import(pathToFileURL(path).href));
-    const value = typeof mod.default === 'function' ? await mod.default() : mod.default;
-    if (!isObject(value))
-        throw new ConfigError(`${path} must export an object (or a function returning one)`);
-    return value;
-}
-function resolveExtends(spec, from) {
-    if (spec.startsWith('.') || isAbsolute(spec))
-        return resolve(dirname(from), spec);
-    try {
-        return createRequire(from).resolve(spec);
-    }
-    catch {
-        throw new ConfigError(`${from} extends "${spec}", which cannot be resolved`, 'use a relative path or an installed package');
-    }
-}
-function extendsList(value) {
-    if (typeof value === 'string')
-        return [value];
-    return Array.isArray(value) ? value.map(String) : [];
-}
-export async function loadWithExtends(path, seen = []) {
-    if (seen.includes(path))
-        throw new ConfigError(`config extends itself: ${[...seen, path].join(' → ')}`);
-    const own = await loadFile(path);
-    const parents = own['extends'];
-    const specs = extendsList(parents);
-    let data = {};
-    const chain = [];
-    for (const spec of specs) {
-        const parent = await loadWithExtends(resolveExtends(spec, path), [...seen, path]);
-        data = deepMerge(data, parent.data);
-        chain.push(...parent.chain);
-    }
-    const { extends: _ignored, ...rest } = own;
-    return { path, data: deepMerge(data, rest), chain: [...chain, path] };
-}
-const userConfigDir = (env) => {
-    const base = env['XDG_CONFIG_HOME'] ?? (env['HOME'] === undefined ? undefined : join(env['HOME'], '.config'));
-    return base;
-};
-export function candidates(d) {
-    const out = [];
-    const fromEnv = d.env[`${d.name.toUpperCase().replaceAll('-', '_')}_CONFIG`];
-    if (fromEnv !== undefined)
-        out.push({ path: resolve(d.cwd, fromEnv), reason: `${d.name.toUpperCase().replaceAll('-', '_')}_CONFIG` });
-    for (const ext of EXTENSIONS)
-        out.push({ path: join(d.cwd, `${d.name}.config${ext}`), reason: 'current directory' });
-    const user = userConfigDir(d.env);
-    if (user !== undefined)
-        out.push({ path: join(user, d.name, 'config.json'), reason: 'user config directory' });
-    return out;
-}
-export async function discover(d) {
-    if (d.disabled === true)
-        return undefined;
-    if (d.explicit !== undefined) {
-        const path = resolve(d.cwd, d.explicit);
-        if (!existsSync(path))
-            throw new ConfigError(`config file not found: ${path}`, 'check --config, or drop it to use discovery');
-        return await loadWithExtends(path);
-    }
-    const found = candidates(d)
-        .map((c) => c.path)
-        .find((path) => existsSync(path));
-    if (found === undefined)
-        return undefined;
-    return await loadWithExtends(found);
-}

package/dist/precedence.d.ts

@@ -1,55 +0,0 @@
-/**
- * One precedence order, fixed and not configurable (commander-env V1–V3, V5):
- *
- *     flag > env > config file > package.json field > default
- *
- * `resolve` is pure — it takes the layers and returns the values with their provenance —
- * which is what makes `--explain` trustworthy and `meta.provenance` cheap. Env applies
- * only to the options the running command declares (yargs #873), never to a sibling's.
- */
-import { type OptionSpec } from './manifest.js';
-export type Source = 'flag' | 'env' | 'config' | 'package' | 'default';
-export interface Provenance {
-    source: Source;
-    /** The env name, the config file, or `package.json` — where a person would look. */
-    location?: string;
-}
-export interface Candidate {
-    source: Source;
-    location: string;
-    /** `undefined` when the layer had nothing for this option. */
-    value: unknown;
-}
-export interface Layer {
-    path: string;
-    data: Record<string, unknown>;
-}
-export interface Layers {
-    /** What the user typed: only options present on the command line. */
-    flags: Record<string, unknown>;
-    env: Record<string, string | undefined>;
-    /** With a prefix, an option without `env:` reads `PREFIX_OPTION_NAME` (R2). */
-    envPrefix?: string;
-    config?: Layer;
-    /** The `package.json` field named after the program, when present. */
-    pkg?: Layer;
-}
-export interface Resolution {
-    values: Record<string, unknown>;
-    provenance: Record<string, Provenance>;
-    candidates: Record<string, Candidate[]>;
-}
-/** A value that cannot be used as configured: exit CONFIG (3), never a stack (E1, E3). */
-export declare class ConfigError extends Error {
-    readonly hint?: string | undefined;
-    constructor(message: string, hint?: string | undefined);
-}
-/** `region` → `REGION`, `dryRun` → `DRY_RUN`, `log-level` → `LOG_LEVEL` (yargs #2005: never camel-cased back). */
-export declare function screaming(name: string): string;
-export declare function envName(name: string, spec: OptionSpec, prefix: string | undefined): string | undefined;
-/** Booleans from env accept one spelling each way (R7). */
-export declare function envBoolean(raw: string): boolean | undefined;
-/** Every declared option, resolved through the layers; a missing required one is left undefined for the caller to report. */
-export declare function resolve(specs: Record<string, OptionSpec>, layers: Layers): Resolution;
-/** `--explain <option>`: the winning source and every candidate it beat, or that was unset (V3). */
-export declare function explain(name: string, resolution: Resolution): string;

package/dist/precedence.js

@@ -1,100 +0,0 @@
-export class ConfigError extends Error {
-    hint;
-    constructor(message, hint) {
-        super(message);
-        this.hint = hint;
-    }
-}
-export function screaming(name) {
-    return name
-        .replaceAll(/([a-z0-9])([A-Z])/g, '$1_$2')
-        .replaceAll('-', '_')
-        .toUpperCase();
-}
-export function envName(name, spec, prefix) {
-    if (spec.env !== undefined)
-        return spec.env;
-    return prefix === undefined ? undefined : `${prefix}_${screaming(name)}`;
-}
-const TRUE = new Set(['1', 'true', 'yes']);
-const FALSE = new Set(['0', 'false', 'no']);
-export function envBoolean(raw) {
-    const v = raw.trim().toLowerCase();
-    if (TRUE.has(v))
-        return true;
-    if (FALSE.has(v))
-        return false;
-    return undefined;
-}
-function fromEnv(name, spec, layers) {
-    const variable = envName(name, spec, layers.envPrefix);
-    if (variable === undefined)
-        return undefined;
-    if (spec.type === 'boolean' && layers.envPrefix !== undefined) {
-        const negated = `${layers.envPrefix}_NO_${screaming(name)}`;
-        if (layers.env[negated] !== undefined) {
-            throw new ConfigError(`${negated} is not supported`, `set ${variable}=false instead`);
-        }
-    }
-    const raw = layers.env[variable];
-    if (raw === undefined)
-        return { source: 'env', location: variable, value: undefined };
-    if (spec.type !== 'boolean')
-        return { source: 'env', location: variable, value: raw };
-    const parsed = envBoolean(raw);
-    if (parsed === undefined)
-        throw new ConfigError(`${variable}="${raw}" is not a boolean`, `use ${variable}=true or ${variable}=false`);
-    return { source: 'env', location: variable, value: parsed };
-}
-function candidatesFor(name, spec, layers) {
-    const out = [{ source: 'flag', location: `--${name}`, value: layers.flags[name] }];
-    const env = fromEnv(name, spec, layers);
-    if (env !== undefined)
-        out.push(env);
-    if (layers.config !== undefined)
-        out.push({ source: 'config', location: layers.config.path, value: layers.config.data[name] });
-    if (layers.pkg !== undefined)
-        out.push({ source: 'package', location: layers.pkg.path, value: layers.pkg.data[name] });
-    out.push({ source: 'default', location: 'default', value: spec.default });
-    return out;
-}
-export function resolve(specs, layers) {
-    const values = new Map();
-    const provenance = new Map();
-    const candidates = new Map();
-    for (const [name, spec] of Object.entries(specs)) {
-        const list = candidatesFor(name, spec, layers);
-        candidates.set(name, list);
-        const winner = list.find((c) => c.value !== undefined);
-        if (winner === undefined)
-            continue;
-        values.set(name, winner.value);
-        provenance.set(name, winner.source === 'default' ? { source: 'default' } : { source: winner.source, location: winner.location });
-    }
-    return { values: Object.fromEntries(values), provenance: Object.fromEntries(provenance), candidates: Object.fromEntries(candidates) };
-}
-const describe = (c) => {
-    switch (c.source) {
-        case 'flag':
-            return `flag ${c.location}`;
-        case 'env':
-            return `env ${c.location}`;
-        case 'config':
-            return `config file ${c.location}`;
-        case 'package':
-            return `package.json field in ${c.location}`;
-        case 'default':
-            return 'default';
-    }
-};
-export function explain(name, resolution) {
-    const list = resolution.candidates[name];
-    if (list === undefined)
-        return `${name} is not an option of this command\n`;
-    const winner = list.find((c) => c.value !== undefined);
-    const head = winner === undefined ? `${name} is unset` : `${name} = ${JSON.stringify(winner.value)}   from ${describe(winner)}`;
-    const rest = list
-        .filter((c) => c !== winner)
-        .map((c) => `${describe(c)} ${c.value === undefined ? '(unset)' : JSON.stringify(c.value)}`);
-    return `${head}\n${rest.length === 0 ? '' : `         candidates: ${rest.join(', ')}\n`}`;
-}