burgee 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofri Peretz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,35 @@
-# burgee
+<p align="center">
+  <a href="https://github.com/ofri-peretz/burgee" target="blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ofri-peretz/burgee/main/brand-assets/burgee-lockup.svg" />
+      <img src="https://raw.githubusercontent.com/ofri-peretz/burgee/main/brand-assets/burgee-lockup-light.svg" alt="burgee" width="360" />
+    </picture>
+  </a>
+</p>
 
-**Not yet released.** This version reserves the name; the first working release is
-wave 1 of the roadmap.
+<p align="center">
+  Everything a CLI needs that isn't your CLI. Written once, served to humans and agents alike.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/v/burgee?style=flat-square&color=0a6b47" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/dm/burgee?style=flat-square" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/runtime%20dependencies-0-0a6b47?style=flat-square" alt="Zero runtime dependencies" />
+  <img src="https://img.shields.io/badge/Node.js-24+-green.svg?style=flat-square" alt="Node.js 24+" />
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
+</p>
 
 A **burgee** is the small swallowtail flag a boat flies to say which club or fleet it
 belongs to — a flag of identity, not of instruction. That is what this framework does for
 a command-line program: a command declares itself once, and every surface is that
 declaration read by a different reader.
 
+## Start here
+
+```bash
+npm install burgee
+```
+
 ```js
 // cli.mjs — the whole CLI
 import { defineCommand, run } from 'burgee';
@@ -35,7 +57,9 @@ hint: pass --name <value>
 One file. No build step, no config file, no directory convention. A test enforces
 that on every commit.
 
-```
+## One declaration, every surface
+
+```text
 defineCommand()  ──▶  manifest  ──┬──▶  human help
                                   ├──▶  --json      one stable envelope
                                   ├──▶  --schema    versioned, JSON-Schema validated
@@ -45,18 +69,46 @@ defineCommand()  ──▶  manifest  ──┬──▶  human help
                                   └──▶  docs + llms.txt
 ```
 
+Nothing here needs keeping in sync, because nothing is written twice.
+
+## Already on commander?
+
 Drop-in compatible with both incumbents, graded by **their own test suites** — 1,215
 commander tests and 1,185 yargs tests — with the pass rate published and ratcheting:
 
-```js
+```diff
 - import { Command } from 'commander';
 + import { Command } from 'burgee/commander';
 ```
 
-It stays a library you import in one file: no build step, no config, no directory
-convention, no scaffold. A test enforces that.
+Your code and your tests are unchanged. A façade is never called "compatible" until its
+host's own suite passes 100%; below that the rate is published instead of claimed.
+
+## What is in the box
+
+| Import | Gives you |
+| :-- | :-- |
+| `burgee` | `defineCommand()`, `run()`, the exit-code contract and the JSON envelope. |
+| `burgee/commander` | The commander API, graded by commander's suite. |
+| `burgee/testing` | Run a command in-process and assert on its result — no spawning. |
+| `burgee/brand` | One brand declaration → flag, favicon, OG card, cover, lockup. The logo above is its own output. |
+
+## Status
 
-Roadmap, architecture and the 79-requirement floor:
+`burgee` is published and working: the engine, the exit-code contract, the JSON envelope,
+help from the manifest, plugins with hook filters, and a `burgee/commander` façade that
+runs a real commander program. The dev loop, prompts, lazy commands and groups are not
+here yet.
+
+Roadmap, architecture and the 101-requirement floor:
 <https://github.com/ofri-peretz/burgee>
 
-MIT © Interlace
+---
+
+Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on burgee declares
+what it is, [roundel](https://www.npmjs.com/package/roundel) carries its colours,
+[flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and
+[caique](https://www.npmjs.com/package/caique) answers back. Each is an independent package;
+none requires the others.
+
+MIT © Ofri Peretz — see [LICENSE](./LICENSE).

package/dist/brand.d.ts

@@ -83,6 +83,58 @@ export interface BurgeeBrand {
      * time on a file you wrote, not on anything a user supplies at runtime.
      */
     charge?: string;
+    /**
+     * Your own silhouette instead of the swallowtail: SVG path data in the same
+     * `0 0 100 100` box, filled with the field and carrying the charge exactly as
+     * the flag does. For a sibling brand whose name is not a flag — a roundel is
+     * rings, a parrot is a parrot — the shape is the whole point, and drawing it
+     * here keeps every other projection (favicon, lockup, OG, cover) intact.
+     *
+     * Filled `evenodd`, so a subpath drawn inside another cuts a hole through it:
+     * that is how a ring gets its centre and an eye gets its white. Subpaths that
+     * are meant to read as one solid body must not overlap.
+     *
+     * Emitted verbatim, like {@link BurgeeBrand.charge}: a build-time value you
+     * wrote, never anything a user supplies at runtime.
+     */
+    shape?: string;
+    /**
+     * A sheen: a soft highlight laid across the field, `0` to `1`, where the
+     * number is how bright its brightest point is. Depth, not decoration — a flat
+     * gradient reads as printed ink, and one light source makes the same shape
+     * read as an object with a front.
+     *
+     * It is drawn INSIDE the silhouette (clipped to it), so it never softens the
+     * outline the mark is recognised by, and it sits under the charge, so it never
+     * touches the contrast the charge was measured at.
+     *
+     * The same layer is what moves in {@link Burgee.alive}.
+     */
+    sheen?: number;
+    /**
+     * A bevel: how strongly the mark's own edge catches the light, `0` to `1`.
+     *
+     * The whole of the third dimension a logo can afford. Two copies of the
+     * silhouette stroked and clipped to itself — light offset up toward the light
+     * source, dark offset away — so the edge lifts and the face stays flat. No
+     * extrusion, no renderer, and nothing that stops it being a 16px favicon: the
+     * bevel is sub-pixel there and simply disappears, which is the correct
+     * behaviour rather than a compromise.
+     */
+    bevel?: number;
+    /**
+     * Markings: SVG markup in the same `0 0 100 100` box as {@link BurgeeBrand.shape},
+     * drawn over the field and under the charge.
+     *
+     * One path can hold one fill, and some marks are not one colour — a roundel is
+     * concentric rings, a caique has a black cap over an orange throat over a white
+     * belly. Those are markings ON the body, not the body, and they are declared
+     * here rather than by stacking whole brands on top of each other.
+     *
+     * Emitted verbatim, like {@link BurgeeBrand.charge}: a build-time value you
+     * wrote, never anything a user supplies at runtime.
+     */
+    markings?: 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.
@@ -139,7 +191,7 @@ 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 declare function burgeeBody(brand: BurgeeBrand, id?: string, moving?: boolean): string;
 export interface CardOptions {
     width?: number;
     height?: number;
@@ -156,6 +208,15 @@ export interface CardOptions {
 export interface Burgee {
     /** The flag alone, square, at any size. */
     flag(size?: number): string;
+    /**
+     * The same mark with its sheen sweeping across it, for a page that can afford
+     * motion — a site header, a docs hero. Identical to {@link Burgee.flag} when
+     * no `sheen` is declared, and parked still under `prefers-reduced-motion`.
+     *
+     * Not the favicon and not the README: a tab icon that shimmers is a tab icon
+     * that distracts.
+     */
+    alive(size?: number): string;
     /** Favicon master. One file serves both themes — the flag carries its own field. */
     favicon(size?: number): string;
     /** Social card, 1200×630. */

package/dist/brand.js

@@ -47,7 +47,9 @@ 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]);
+    const base = [brand.field, brand.mark, brand.bordure, brand.charge];
+    const extra = [brand.shape, brand.sheen, brand.bevel, brand.markings].filter((v) => v !== undefined);
+    const source = JSON.stringify(extra.length === 0 ? base : [...base, ...extra]);
     let h = HASH_SEED;
     for (let i = 0; i < source.length; i++) {
         h = ((h << HASH_SHIFT) + h + (source.codePointAt(i) ?? 0)) >>> 0;
@@ -89,7 +91,7 @@ function bordureBands(brand) {
     if (bands.length === 0)
         return '';
     let total = bands.reduce((sum, band) => sum + band.width, 0);
-    const path = burgeeFlagPath();
+    const path = silhouette(brand);
     const drawn = [];
     for (const band of bands) {
         drawn.push(`<path d="${path}" fill="none" stroke="${band.color}"` +
@@ -98,10 +100,70 @@ function bordureBands(brand) {
     }
     return drawn.join('');
 }
-export function burgeeBody(brand, id = fieldId(brand)) {
+const SHEEN_START = -50;
+const SHEEN_LEAN = -14;
+const SHEEN = {
+    width: 34,
+    still: 8,
+    from: SHEEN_START,
+    to: 140,
+    seconds: 7,
+    lean: SHEEN_LEAN,
+};
+const SHEEN_LIGHT = '#ffffff';
+const SHEEN_PEAK = 0.5;
+function silhouette(brand) {
+    return brand.shape ?? burgeeFlagPath();
+}
+function sheenStop(offset, opacity) {
+    return (`<stop offset="${round(offset)}" stop-color="${SHEEN_LIGHT}"` +
+        ` stop-opacity="${round(opacity)}"/>`);
+}
+function clip(brand, id) {
+    if (brand.sheen === undefined && brand.bevel === undefined && brand.markings === undefined) {
+        return '';
+    }
+    return `<clipPath id="${id}-c"><path d="${silhouette(brand)}"/></clipPath>`;
+}
+function sheenBand(brand, id, moving) {
+    if (brand.sheen === undefined)
+        return '';
+    return (`<linearGradient id="${id}-s" gradientUnits="objectBoundingBox" x1="0" y1="0" x2="1" y2="0">` +
+        `${sheenStop(0, 0)}${sheenStop(SHEEN_PEAK, brand.sheen)}${sheenStop(1, 0)}</linearGradient>` +
+        `<g clip-path="url(#${id}-c)"><g transform="skewX(${SHEEN.lean})">` +
+        `<rect x="${moving ? SHEEN.from : SHEEN.still}" y="-20" width="${SHEEN.width}" height="140"` +
+        `${moving ? ` class="${id}-sweep"` : ''} fill="url(#${id}-s)"/></g></g>`);
+}
+function sheenStyle(id) {
+    return (`<style>` +
+        `@keyframes ${id}-sweep{from{transform:translateX(0)}` +
+        `to{transform:translateX(${SHEEN.to - SHEEN.from}px)}}` +
+        `.${id}-sweep{animation:${id}-sweep ${SHEEN.seconds}s ease-in-out infinite}` +
+        `@media (prefers-reduced-motion:reduce){.${id}-sweep{animation:none;` +
+        `transform:translateX(${SHEEN.still - SHEEN.from}px)}}` +
+        `</style>`);
+}
+const BEVEL = { offset: 0.55, width: 1.5, dark: 0.45 };
+const BEVEL_DARK = '#000000';
+function bevelEdges(brand, id) {
+    if (brand.bevel === undefined)
+        return '';
+    const shape = silhouette(brand);
+    const edge = (dx, dy, color, opacity) => `<path d="${shape}" fill="none" stroke="${color}" stroke-opacity="${round(opacity)}"` +
+        ` stroke-width="${BEVEL.width}" stroke-linejoin="round"` +
+        ` transform="translate(${round(dx)} ${round(dy)})"/>`;
+    const lit = edge(-BEVEL.offset, -BEVEL.offset, SHEEN_LIGHT, brand.bevel);
+    const shaded = edge(BEVEL.offset, BEVEL.offset, BEVEL_DARK, brand.bevel * BEVEL.dark);
+    return `<g clip-path="url(#${id}-c)">${lit}${shaded}</g>`;
+}
+export function burgeeBody(brand, id = fieldId(brand), moving = false) {
     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 field = brand.shape === undefined
+        ? `<path d="${burgeeFlagPath()}" fill="url(#${id})"/>`
+        : `<path d="${brand.shape}" fill="url(#${id})" fill-rule="evenodd"/>`;
+    const markings = brand.markings === undefined ? '' : `<g clip-path="url(#${id}-c)">${brand.markings}</g>`;
+    return (`${gradient(brand, id)}${bordureBands(brand)}${field}${clip(brand, id)}` +
+        `${markings}${sheenBand(brand, id, moving)}${bevelEdges(brand, id)}${charge}`);
 }
 const FONT = 'ui-monospace, SFMono-Regular, Menlo, monospace';
 const TRACKING_TIGHTEN = 0.03;
@@ -211,18 +273,22 @@ function renderCard(brand, options, size) {
     parts.push('</svg>');
     return parts.join('\n');
 }
-function renderFlag(brand, size) {
+function renderFlag(brand, size, moving = false) {
     const label = brand.name ? ` role="img" aria-label="${escape(brand.name)}"` : ' aria-hidden="true"';
+    const id = fieldId(brand);
+    const alive = moving && brand.sheen !== undefined;
     return [
         `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${MARK.SPAN} ${MARK.SPAN}"` +
             ` width="${size}" height="${size}"${label}>`,
-        `  ${burgeeBody(brand)}`,
+        ...(alive ? [`  ${sheenStyle(id)}`] : []),
+        `  ${burgeeBody(brand, id, alive)}`,
         '</svg>',
     ].join('\n');
 }
 export function defineBurgee(brand) {
     return {
         flag: (size = MARK.SPAN) => renderFlag(brand, size),
+        alive: (size = MARK.SPAN) => renderFlag(brand, size, true),
         favicon: (size = SIZES.FAVICON) => renderFlag(brand, size),
         og: (options = {}) => renderCard(brand, options, SIZES.OG),
         cover: (options = {}) => renderCard(brand, options, SIZES.COVER),

package/dist/cli.d.ts

@@ -48,4 +48,15 @@ export declare const brandCommand: import("./execute.js").Command<{
         readonly description: "emit anyway when a contrast check fails. Says so in the output";
     };
 }>;
+/**
+ * `burgee dev <entry>` — watch the entry, reload it on change, serve it as MCP on stdio
+ * and print every surface on each save (dev-loop). Loaded only when asked for, so the
+ * CLI's own weight and the framework's stay what they were (W4).
+ */
+export declare const devCommand: import("./execute.js").Command<{
+    readonly 'no-watch': {
+        readonly type: "boolean";
+        readonly description: "load once and serve; do not watch for changes";
+    };
+}>;
 export declare const program: import("./manifest.js").Manifest;

package/dist/cli.js

@@ -97,9 +97,25 @@ export const brandCommand = defineCommand({
         return { out: options.out, files: written.map((s) => s.file), contrast };
     },
 });
+export const devCommand = defineCommand({
+    name: 'dev',
+    description: 'Watch a CLI entry, reload it on change, and serve it as MCP on stdio while you write it',
+    arguments: [{ name: 'entry', description: 'the module that exports the program, as program or as its default export', required: true }],
+    options: {
+        'no-watch': { type: 'boolean', description: 'load once and serve; do not watch for changes' },
+    },
+    run: async ({ positionals, options }) => {
+        const [entry] = positionals;
+        if (entry === undefined)
+            throw new Error('an entry file is required');
+        const [{ dev }, { processRuntime }] = await Promise.all([import('./dev.js'), import('./runtime.js')]);
+        const handle = dev({ entry, input: processRuntime.stdin, output: processRuntime.stdout, log: processRuntime.stderr, watch: options['no-watch'] !== true });
+        await handle.done;
+    },
+});
 export const program = defineProgram({
     name: 'burgee',
     description: 'The agent-native CLI framework, and the tools that come with it',
-    commands: [brandCommand],
+    commands: [brandCommand, devCommand],
 });
 run(program);

package/dist/{commander-argument.js → commander/argument.js}

@@ -1,4 +1,4 @@
-import { InvalidArgumentError } from './commander-error.js';
+import { InvalidArgumentError } from './error.js';
 export class Argument {
     description;
     variadic = false;
@@ -8,6 +8,7 @@ export class Argument {
     argChoices = undefined;
     required;
     _name;
+    /** `<required>`, `[optional]`, bare = required; a trailing `...` makes it variadic. */
     constructor(name, description) {
         this.description = description || '';
         switch (name[0]) {
@@ -66,7 +67,9 @@ export class Argument {
         return this;
     }
 }
+/** `<name>` / `[name]` / `<name...>` for usage strings. */
 export function humanReadableArgName(arg) {
     const nameOutput = arg.name() + (arg.variadic ? '...' : '');
     return arg.required ? `<${nameOutput}>` : `[${nameOutput}]`;
 }
+//# sourceMappingURL=argument.js.map

package/dist/{commander-command.d.ts → commander/command.d.ts}

@@ -14,11 +14,11 @@
  */
 import childProcess from 'node:child_process';
 import { EventEmitter } from 'node:events';
-import { Argument, type ParseArg } from './commander-argument.js';
-import { CommanderError } from './commander-error.js';
-import { Help } from './commander-help.js';
-import { Option } from './commander-option.js';
-import { type Effects, Manifest, type OptionSpec, type Plugin } from './manifest.js';
+import { type Effects, Manifest, type OptionSpec, type Plugin } from '../manifest.js';
+import { Argument, type ParseArg } from './argument.js';
+import { CommanderError } from './error.js';
+import { Help } from './help.js';
+import { Option } from './option.js';
 export interface OutputConfiguration {
     writeOut: (str: string) => void;
     writeErr: (str: string) => void;
@@ -127,6 +127,9 @@ export declare class Command extends EventEmitter {
     _manifest: Manifest | undefined;
     /** burgee: what this command does to the world (N6); declaring it exposes the command as an MCP tool. */
     _effects: Effects | undefined;
+    /** burgee: `true`, or the replacement's name (M5). Shown in help, schema and a one-line warning on use. */
+    _deprecated: boolean | string | undefined;
+    _deprecationWarned: boolean;
     /** burgee: set for the duration of a parse that injected the streams or the exit. */
     _burgee: Burgee | undefined;
     constructor(name?: string);
@@ -313,6 +316,11 @@ export declare class Command extends EventEmitter {
     _optionSpecs(): Record<string, OptionSpec>;
     /** burgee: declare what the command does to the world (N6). This is what exposes it as an MCP tool (N2). */
     effects(value: Effects): this;
+    /**
+     * burgee: mark the command deprecated (M5). Help and `--schema` show it; running it prints
+     * `warning: 'old' is deprecated, use 'new'` on stderr once and goes on, exit unchanged.
+     */
+    deprecate(use?: string): this;
     /**
      * burgee: `--schema` and `--mcp` on a commander-syntax program, from its manifest (J2).
      * Only when the program declares neither option itself; `--mcp` runs commands through
@@ -331,6 +339,8 @@ export declare class Command extends EventEmitter {
     _takeJson(unknown: string[]): void;
     /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */
     _runAction(): unknown;
+    /** burgee (M5): once per process, on stderr; only for a command that asked, so commander's own output is untouched. */
+    _warnDeprecated(): void;
     /** burgee: where every option value came from, from commander's own value sources (V3). */
     _provenance(): Record<string, {
         source: string;