busybar-kit 0.2.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viirtualp1
+
+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,148 +1,148 @@
-# busybar-kit
-
-> [!IMPORTANT]
-> **Unofficial community project.** Built and maintained by [@viirtualp1](https://github.com/viirtualp1), **not** an official Flipper Devices / BUSY product, and not affiliated with, endorsed by, or supported by them. "BUSY Bar" remains their trademark. For the real hardware and official apps, visit **[busy.app](https://busy.app/)**.
-
-Shared building blocks for [BUSY Bar](https://busy.bar) apps. Everything here is
-app-agnostic: screen geometry, the palette neutrals, formatters, ticker text,
-the Bar's error taxonomy, the connection half of a config, and an offline PNG
-renderer that draws the same elements the device does.
-
-It is the common half of [busybar-dota](https://github.com/viirtualp1/busybar-dota),
-[busybar-mydota](https://github.com/viirtualp1/busybar-mydota) and
-[busybar-livesplit](https://github.com/viirtualp1/busybar-livesplit).
-
-```bash
-npm install busybar-kit
-```
-
-`@busy-app/busy-lib` is a peer dependency — the app owns that version.
-
-## What is in it
-
-| Import                                                                    | What it gives you                                                                                              |
-| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `busybar-kit/device`                                                      | `FRONT` / `BACK` screen sizes, `FONT_WIDTH`, `textWidth`, `clipToWidth`, `fittingChars`, `rowY`, `backRowGrid` |
-| `busybar-kit/colors`                                                      | `BASE_COLORS` — neutrals, chrome, and the transparent value that hides an element                              |
-| `busybar-kit/format`                                                      | `formatClock`, `formatGold`, `formatCountdown`, `formatStartTime`, `formatKda`, `formatPercent`, …             |
-| `busybar-kit/elements`                                                    | `AnyElement`, `band()`, `fillWidth()`                                                                          |
-| `busybar-kit/ticker`                                                      | `paginate` / `pageAt` / `scrollAt` / `tickerLine`, and `EventTicker`                                           |
-| `busybar-kit/errors`                                                      | `BarApiError`, `toBarError`, `isLowPriority`, `isClientError`, `isForbidden`                                   |
-| `busybar-kit/config`                                                      | `loadEnvFile`, `envReader`, `loadBarConfig`                                                                    |
-| `busybar-kit/image`                                                       | `ditherToPanel` — a picture, in the back panel's 16 greys                                                      |
-| `busybar-kit/preview`                                                     | `renderFront` / `renderBack` / `Bitmap` — device-accurate PNGs with no hardware                                |
-| `busybar-kit/tsconfig.json`, `busybar-kit/eslint`, `busybar-kit/prettier` | the shared toolchain                                                                                           |
-| `busybar-fix-esm` (bin)                                                   | rewrites relative imports in `dist/` to carry `.js`, for Node ESM                                              |
-
-## Geometry is hardware, not layout
-
-`FRONT` (72×16) and `BACK` (160×80, with its header rows and 12px grid) are
-facts about the device. An app spreads its own named slots on top:
-
-```ts
-import { FRONT as DEVICE, BACK as DEVICE_BACK } from 'busybar-kit/device';
-
-export const FRONT = {
-  ...DEVICE,
-  topY: 0,
-  bottomY: 11,
-  clockWidth: 24,
-} as const;
-```
-
-An app whose header is a different height lays out its own row grid, and reads
-rows off that instead of the default:
-
-```ts
-import { backRowGrid, rowY as gridRowY } from 'busybar-kit/device';
-
-export const BACK = { ...DEVICE_BACK, ...backRowGrid(16), nameX: 8 } as const;
-
-export const rowY = (index: number) => gridRowY(index, BACK);
-```
-
-`clipToWidth` takes the truncation mark as a fourth argument (`'.'` by
-default, `'..'` where names are cut often enough to want the emphasis).
-
-Colours work the same way — `BASE_COLORS` holds what every app needs, and the
-app adds its own semantics:
-
-```ts
-import { BASE_COLORS } from 'busybar-kit/colors';
-
-export const COLORS = {
-  ...BASE_COLORS,
-  radiant: '#3FBF5FFF',
-  dire: '#E14B3AFF',
-} as const;
-```
-
-## Config
-
-`loadBarConfig` resolves which Bar to talk to and over which transport, and
-warns about credentials that transport will ignore. That is all it covers —
-render cadence and request timeouts are the app's own tempo (a speedrun timer
-wants 60ms frames where a match ticker is happy at 200), so they stay in the
-app's config with `DEFAULTS` / `LIMITS` as the values worth starting from.
-
-It hands back the same env reader, so an app's own settings collect their
-warnings into one list:
-
-```ts
-import { loadBarConfig, loadEnvFile } from 'busybar-kit/config';
-
-loadEnvFile();
-
-export function loadConfig(env = process.env) {
-  const warnings: string[] = [];
-  const { bar, env: read } = loadBarConfig(env, warnings);
-
-  return {
-    warnings,
-    config: {
-      ...bar,
-      gsiPort: read.number('GSI_PORT', 3080, { min: 1024, max: 65_535 }),
-    },
-  };
-}
-```
-
-## Pictures
-
-The back panel has 16 greys and quantises whatever you upload to them, so a
-photo sent as-is comes back in bands. `ditherToPanel` does the quantising here,
-with error diffusion, which leaves every pixel already sitting on a level:
-
-```ts
-import { ditherToPanel } from 'busybar-kit/image';
-
-const cover = ditherToPanel(decodedRgba); // 80x80 Bitmap, panel-ready
-await bar.AssetsUpload({ application_name: 'app', file: 'art.png', data: cover.toPng() });
-```
-
-It takes pixels, not files. Which image decoder to pay for is the app's
-choice — the kit stays dependency-free.
-
-`Bitmap.fromRgba` wraps pixels from anywhere, and `bitmap.blit(other, x, y)`
-draws one into another: the raster below cannot follow an image element's path,
-so a preview composites the picture itself.
-
-## Preview
-
-`renderFront` / `renderBack` rasterise the very element list you send to the
-device — a 3×5 pixel font, the same anchoring rules, and the back panel
-flattened to the 16 greys the real OLED shows. Useful for screenshots in a
-README and for asserting a layout in tests without a Bar on the desk.
-
-```ts
-import { renderFront } from 'busybar-kit/preview';
-
-writeFileSync('front.png', renderFront(frontElements(frame)).scale(8).toPng());
-```
-
-## Scripts
-
-```bash
-npm run check   # lint + typecheck + test
-npm run build   # tsc + .js extension fixup
-```
+# busybar-kit
+
+> [!IMPORTANT]
+> **Unofficial community project.** Built and maintained by [@viirtualp1](https://github.com/viirtualp1), **not** an official Flipper Devices / BUSY product, and not affiliated with, endorsed by, or supported by them. "BUSY Bar" remains their trademark. For the real hardware and official apps, visit **[busy.app](https://busy.app/)**.
+
+Shared building blocks for [BUSY Bar](https://busy.bar) apps. Everything here is
+app-agnostic: screen geometry, the palette neutrals, formatters, ticker text,
+the Bar's error taxonomy, the connection half of a config, and an offline PNG
+renderer that draws the same elements the device does.
+
+It is the common half of [busybar-dota](https://github.com/viirtualp1/busybar-dota),
+[busybar-mydota](https://github.com/viirtualp1/busybar-mydota) and
+[busybar-livesplit](https://github.com/viirtualp1/busybar-livesplit).
+
+```bash
+npm install busybar-kit
+```
+
+`@busy-app/busy-lib` is a peer dependency — the app owns that version.
+
+## What is in it
+
+| Import                                                                    | What it gives you                                                                                              |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `busybar-kit/device`                                                      | `FRONT` / `BACK` screen sizes, `FONT_WIDTH`, `textWidth`, `clipToWidth`, `fittingChars`, `rowY`, `backRowGrid` |
+| `busybar-kit/colors`                                                      | `BASE_COLORS` — neutrals, chrome, and the transparent value that hides an element                              |
+| `busybar-kit/format`                                                      | `formatClock`, `formatGold`, `formatCountdown`, `formatStartTime`, `formatKda`, `formatPercent`, …             |
+| `busybar-kit/elements`                                                    | `AnyElement`, `band()`, `fillWidth()`                                                                          |
+| `busybar-kit/ticker`                                                      | `paginate` / `pageAt` / `scrollAt` / `tickerLine`, and `EventTicker`                                           |
+| `busybar-kit/errors`                                                      | `BarApiError`, `toBarError`, `isLowPriority`, `isClientError`, `isForbidden`                                   |
+| `busybar-kit/config`                                                      | `loadEnvFile`, `envReader`, `loadBarConfig`                                                                    |
+| `busybar-kit/image`                                                       | `ditherToPanel` — a picture, in the back panel's 16 greys                                                      |
+| `busybar-kit/preview`                                                     | `renderFront` / `renderBack` / `Bitmap` — device-accurate PNGs with no hardware                                |
+| `busybar-kit/tsconfig.json`, `busybar-kit/eslint`, `busybar-kit/prettier` | the shared toolchain                                                                                           |
+| `busybar-fix-esm` (bin)                                                   | rewrites relative imports in `dist/` to carry `.js`, for Node ESM                                              |
+
+## Geometry is hardware, not layout
+
+`FRONT` (72×16) and `BACK` (160×80, with its header rows and 12px grid) are
+facts about the device. An app spreads its own named slots on top:
+
+```ts
+import { FRONT as DEVICE, BACK as DEVICE_BACK } from 'busybar-kit/device';
+
+export const FRONT = {
+  ...DEVICE,
+  topY: 0,
+  bottomY: 11,
+  clockWidth: 24,
+} as const;
+```
+
+An app whose header is a different height lays out its own row grid, and reads
+rows off that instead of the default:
+
+```ts
+import { backRowGrid, rowY as gridRowY } from 'busybar-kit/device';
+
+export const BACK = { ...DEVICE_BACK, ...backRowGrid(16), nameX: 8 } as const;
+
+export const rowY = (index: number) => gridRowY(index, BACK);
+```
+
+`clipToWidth` takes the truncation mark as a fourth argument (`'.'` by
+default, `'..'` where names are cut often enough to want the emphasis).
+
+Colours work the same way — `BASE_COLORS` holds what every app needs, and the
+app adds its own semantics:
+
+```ts
+import { BASE_COLORS } from 'busybar-kit/colors';
+
+export const COLORS = {
+  ...BASE_COLORS,
+  radiant: '#3FBF5FFF',
+  dire: '#E14B3AFF',
+} as const;
+```
+
+## Config
+
+`loadBarConfig` resolves which Bar to talk to and over which transport, and
+warns about credentials that transport will ignore. That is all it covers —
+render cadence and request timeouts are the app's own tempo (a speedrun timer
+wants 60ms frames where a match ticker is happy at 200), so they stay in the
+app's config with `DEFAULTS` / `LIMITS` as the values worth starting from.
+
+It hands back the same env reader, so an app's own settings collect their
+warnings into one list:
+
+```ts
+import { loadBarConfig, loadEnvFile } from 'busybar-kit/config';
+
+loadEnvFile();
+
+export function loadConfig(env = process.env) {
+  const warnings: string[] = [];
+  const { bar, env: read } = loadBarConfig(env, warnings);
+
+  return {
+    warnings,
+    config: {
+      ...bar,
+      gsiPort: read.number('GSI_PORT', 3080, { min: 1024, max: 65_535 }),
+    },
+  };
+}
+```
+
+## Pictures
+
+The back panel has 16 greys and quantises whatever you upload to them, so a
+photo sent as-is comes back in bands. `ditherToPanel` does the quantising here,
+with error diffusion, which leaves every pixel already sitting on a level:
+
+```ts
+import { ditherToPanel } from 'busybar-kit/image';
+
+const cover = ditherToPanel(decodedRgba); // 80x80 Bitmap, panel-ready
+await bar.AssetsUpload({ application_name: 'app', file: 'art.png', data: cover.toPng() });
+```
+
+It takes pixels, not files. Which image decoder to pay for is the app's
+choice — the kit stays dependency-free.
+
+`Bitmap.fromRgba` wraps pixels from anywhere, and `bitmap.blit(other, x, y)`
+draws one into another: the raster below cannot follow an image element's path,
+so a preview composites the picture itself.
+
+## Preview
+
+`renderFront` / `renderBack` rasterise the very element list you send to the
+device — a 3×5 pixel font, the same anchoring rules, and the back panel
+flattened to the 16 greys the real OLED shows. Useful for screenshots in a
+README and for asserting a layout in tests without a Bar on the desk.
+
+```ts
+import { renderFront } from 'busybar-kit/preview';
+
+writeFileSync('front.png', renderFront(frontElements(frame)).scale(8).toPng());
+```
+
+## Scripts
+
+```bash
+npm run check   # lint + typecheck + test
+npm run build   # tsc + .js extension fixup
+```

package/dist/config-spec.d.ts

@@ -0,0 +1,81 @@
+/**
+ * How an app describes its own settings, so something else can ask about them.
+ *
+ * The point is that the app owns the description. `busybar-flights` knows that
+ * a route reads `SVO-JFK` and that a departure is a local time without a zone;
+ * an editor that had to know those things for every app would need editing
+ * every time a new app appeared. With a spec, installing a package is enough.
+ *
+ * Specs are modules rather than JSON because the useful parts — how one entry
+ * reads in a picker, whether a value is acceptable — are functions. An app
+ * points at its own with a `busybar.config` field in package.json:
+ *
+ *     "busybar": { "config": "./dist/config-spec.js" }
+ */
+export type FieldType = 'text' | 'secret' | 'number' | 'boolean' | 'select' | 'datetime' | 'path';
+export type FieldOption = {
+    value: string;
+    label: string;
+    hint?: string;
+};
+export type ConfigField = {
+    /** The env variable, or the key inside a record. */
+    key: string;
+    label: string;
+    type: FieldType;
+    /** One line under the question. */
+    hint?: string;
+    placeholder?: string;
+    /** Empty is not an answer. */
+    required?: boolean;
+    /** Kept behind "more settings": tuning nobody changes on a normal day. */
+    advanced?: boolean;
+    /** For `select`. */
+    options?: readonly FieldOption[];
+    /** What the app itself would do with the setting left out. */
+    fallback?: string;
+    /** A message when the answer will not do, or nothing when it will. */
+    validate?: (value: string) => string | undefined;
+};
+/** A file of records you add to, edit and remove — flights, fixtures. */
+export type ListSection = {
+    kind: 'list';
+    /** Relative to the app's own config directory. */
+    file: string;
+    title: string;
+    /**
+     * The key holding the array, when the file is an object wrapped around one —
+     * dota's `schedule.json` keeps its matches under `matches`, beside settings
+     * that apply to the whole file. Left out, the file is the array itself.
+     */
+    at?: string;
+    /** Settings that live beside the array in the same file, not in `.env`. */
+    header?: ConfigField[];
+    /** What one entry looks like in the picker. */
+    summary: (entry: Record<string, string>) => string;
+    fields: ConfigField[];
+    /** Shown instead of the picker when the file has nothing in it yet. */
+    empty?: string;
+};
+/** Plain settings, one key to a line. */
+export type EnvSection = {
+    kind: 'env';
+    file: string;
+    title: string;
+    fields: ConfigField[];
+};
+export type ConfigSection = ListSection | EnvSection;
+export type AppConfigSpec = {
+    /** The `application_name` the app draws with — the join with everything else. */
+    name: string;
+    /** One line about what the app is, for the app picker. */
+    summary?: string;
+    sections: ConfigSection[];
+};
+/** Identity, for the types. Specs are data; this only saves the annotation. */
+export declare function defineConfigSpec(spec: AppConfigSpec): AppConfigSpec;
+export declare function required(label: string): (value: string) => string | undefined;
+export declare function integerIn(min: number, max: number): (value: string) => string | undefined;
+export declare function matching(pattern: RegExp, message: string): (value: string) => string | undefined;
+export declare function localDateTime(value: string): "YYYY-MM-DD HH:MM" | "that is not a real date" | undefined;
+//# sourceMappingURL=config-spec.d.ts.map

package/dist/config-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-spec.d.ts","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,SAAS,GACnB,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5E,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,MAAM,MAAM,WAAW,GAAG;IACxB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oBAAoB;IACpB,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAClD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,+CAA+C;IAC/C,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;IACnD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAC1B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAEnE;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,IAC5B,OAAO,MAAM,wBACtB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,IACxC,OAAO,MAAM,wBAWtB;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAC/C,OAAO,MAAM,wBAEtB;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,8DAW1C"}

package/dist/config-spec.js

@@ -0,0 +1,54 @@
+/**
+ * How an app describes its own settings, so something else can ask about them.
+ *
+ * The point is that the app owns the description. `busybar-flights` knows that
+ * a route reads `SVO-JFK` and that a departure is a local time without a zone;
+ * an editor that had to know those things for every app would need editing
+ * every time a new app appeared. With a spec, installing a package is enough.
+ *
+ * Specs are modules rather than JSON because the useful parts — how one entry
+ * reads in a picker, whether a value is acceptable — are functions. An app
+ * points at its own with a `busybar.config` field in package.json:
+ *
+ *     "busybar": { "config": "./dist/config-spec.js" }
+ */
+/** Identity, for the types. Specs are data; this only saves the annotation. */
+export function defineConfigSpec(spec) {
+    return spec;
+}
+// --- Validators the apps kept writing for themselves -------------------------
+export function required(label) {
+    return (value) => (value.trim() ? undefined : `${label} is needed`);
+}
+export function integerIn(min, max) {
+    return (value) => {
+        if (!value.trim()) {
+            return undefined;
+        }
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+            return 'a whole number, please';
+        }
+        return parsed < min || parsed > max ? `between ${min} and ${max}` : undefined;
+    };
+}
+export function matching(pattern, message) {
+    return (value) => !value.trim() || pattern.test(value.trim()) ? undefined : message;
+}
+/**
+ * `2026-09-08 19:30` — a local time at the airport, with no zone on it, which
+ * is how departure boards and boarding passes are written.
+ */
+const LOCAL_DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{1,2}:\d{2}$/;
+export function localDateTime(value) {
+    if (!value.trim()) {
+        return undefined;
+    }
+    if (!LOCAL_DATETIME.test(value.trim())) {
+        return 'YYYY-MM-DD HH:MM';
+    }
+    return Number.isNaN(Date.parse(value.trim().replace(' ', 'T')))
+        ? 'that is not a real date'
+        : undefined;
+}
+//# sourceMappingURL=config-spec.js.map

package/dist/config-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-spec.js","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkEH,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,IAAmB;IAClD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAEhF,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,GAAW;IAChD,OAAO,CAAC,KAAa,EAAE,EAAE;QACvB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAClB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,OAAO,wBAAwB,CAAC;QAClC,CAAC;QAED,OAAO,MAAM,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,OAAe;IACvD,OAAO,CAAC,KAAa,EAAE,EAAE,CACvB,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,cAAc,GAAG,sCAAsC,CAAC;AAE9D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACvC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC,yBAAyB;QAC3B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export * from './colors.js';
 export * from './config/index.js';
+export * from './config-spec.js';
 export * from './device.js';
 export * from './elements.js';
 export * from './errors.js';
 export * from './format.js';
 export * from './image/index.js';
 export * from './preview/index.js';
+export * from './profile.js';
 export * from './ticker/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,10 +1,12 @@
 export * from './colors.js';
 export * from './config/index.js';
+export * from './config-spec.js';
 export * from './device.js';
 export * from './elements.js';
 export * from './errors.js';
 export * from './format.js';
 export * from './image/index.js';
 export * from './preview/index.js';
+export * from './profile.js';
 export * from './ticker/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}

package/dist/profile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A profile is one directory that holds a whole BUSY Bar setup: the manifest,
+ * the apps themselves as installed packages, and a folder per app for its own
+ * `.env` and data files.
+ *
+ * ```
+ * ~/.busybar/
+ *   wm.config.json
+ *   node_modules/          the app packages, production dependencies only
+ *   mydota/.env
+ *   dota/.env  dota/schedule.json
+ * ```
+ *
+ * Every app already reads its `.env` from its working directory, so pointing
+ * each one at its own folder here means a packaged app finds its settings in
+ * exactly the place a checked-out one always did — no change inside the apps.
+ */
+export type ProfileResolver = {
+    /** The directory itself. */
+    dir: string;
+    /** Where an app keeps its `.env` and data files. */
+    cwdFor: (name: string) => string;
+    /** The bin an app package installed into this profile, if it is there. */
+    binFor: (name: string) => string | undefined;
+};
+export type ProfileOptions = {
+    /** Injected by the tests, which have no profile on disk. */
+    exists?: (path: string) => boolean;
+    platform?: NodeJS.Platform;
+};
+export declare function profileAt(dir: string, options?: ProfileOptions): ProfileResolver;
+/**
+ * Makes sure every app has somewhere to keep its `.env`. Creating the folder
+ * up front is what lets a fresh profile be filled in by hand without having to
+ * guess the layout first.
+ */
+export declare function ensureAppDirs(profile: ProfileResolver, names: readonly string[]): string[];
+//# sourceMappingURL=profile.d.ts.map

package/dist/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,0EAA0E;IAC1E,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAEF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,eAAe,CAqBpF;AAWD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,YAW/E"}

package/dist/profile.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export function profileAt(dir, options = {}) {
+    const exists = options.exists ?? existsSync;
+    const platform = options.platform ?? process.platform;
+    // npm writes a `.cmd` shim on Windows; the supervisor already knows to run
+    // those through a shell, which is why the extension is kept here.
+    const suffix = platform === 'win32' ? '.cmd' : '';
+    return {
+        dir,
+        cwdFor: (name) => join(dir, name),
+        binFor: (name) => {
+            for (const candidate of binNames(name)) {
+                const bin = join(dir, 'node_modules', '.bin', `${candidate}${suffix}`);
+                if (exists(bin)) {
+                    return bin;
+                }
+            }
+            return undefined;
+        },
+    };
+}
+/**
+ * An app's manifest name is its `application_name` — `mydota`, `flights` — but
+ * it ships as `busybar-mydota` and installs a bin by that name. Trying both is
+ * what lets a manifest entry be nothing more than the name on its own draws.
+ */
+function binNames(name) {
+    return name.startsWith('busybar-') ? [name] : [name, `busybar-${name}`];
+}
+/**
+ * Makes sure every app has somewhere to keep its `.env`. Creating the folder
+ * up front is what lets a fresh profile be filled in by hand without having to
+ * guess the layout first.
+ */
+export function ensureAppDirs(profile, names) {
+    const created = [];
+    for (const name of names) {
+        const dir = profile.cwdFor(name);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+            created.push(dir);
+        }
+    }
+    return created;
+}
+//# sourceMappingURL=profile.js.map

package/dist/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAkCjC,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,UAA0B,EAAE;IACjE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC;IAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACtD,2EAA2E;IAC3E,kEAAkE;IAClE,MAAM,MAAM,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAElD,OAAO;QACL,GAAG;QACH,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC;QACjC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACf,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAAC,CAAC;gBACvE,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;oBAChB,OAAO,GAAG,CAAC;gBACb,CAAC;YACH,CAAC;YAED,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAwB,EAAE,KAAwB;IAC9E,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "busybar-kit",
-  "version": "0.2.1",
+  "version": "1.1.0",
   "description": "Shared building blocks for BUSY Bar apps: device geometry, colours, formatters, ticker text, error taxonomy and an offline PNG preview renderer",
   "author": "viirtualp1",
   "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/viirtualp1/busybar-kit/issues"
+  },
+  "homepage": "https://github.com/viirtualp1/busybar-kit#readme",
   "type": "module",
   "repository": {
     "type": "git",
@@ -15,12 +19,14 @@
     ".": "./dist/index.js",
     "./colors": "./dist/colors.js",
     "./config": "./dist/config/index.js",
+    "./config-spec": "./dist/config-spec.js",
     "./device": "./dist/device.js",
     "./elements": "./dist/elements.js",
     "./errors": "./dist/errors.js",
     "./format": "./dist/format.js",
     "./image": "./dist/image/index.js",
     "./preview": "./dist/preview/index.js",
+    "./profile": "./dist/profile.js",
     "./ticker": "./dist/ticker/index.js",
     "./tsconfig.json": "./configs/tsconfig.base.json",
     "./eslint": "./configs/eslint.config.js",
@@ -34,7 +40,8 @@
     "dist",
     "configs",
     "scripts",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "busy-bar",

package/scripts/fix-esm-extensions.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-
-// Node's ESM loader wants a real file name; tsc leaves extensionless specifiers.
-const argument = process.argv[2] ?? 'dist';
-const dist = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
-const EXTENSIONS = /\.(?:js|json|mjs|cjs|node)$/;
-
-function walk(dir) {
-  for (const name of readdirSync(dir)) {
-    const path = join(dir, name);
-    if (statSync(path).isDirectory()) {
-      walk(path);
-      continue;
-    }
-    if (!/\.(?:js|d\.ts)$/.test(name)) {
-      continue;
-    }
-
-    const source = readFileSync(path, 'utf8');
-    const next = source.replace(
-      /(from\s+|import\s*\()(['"])(\.[^'"]+)\2/g,
-      (match, prefix, quote, spec) =>
-        EXTENSIONS.test(spec) ? match : `${prefix}${quote}${spec}.js${quote}`,
-    );
-    if (next !== source) {
-      writeFileSync(path, next);
-    }
-  }
-}
-
-walk(dist);
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+// Node's ESM loader wants a real file name; tsc leaves extensionless specifiers.
+const argument = process.argv[2] ?? 'dist';
+const dist = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
+const EXTENSIONS = /\.(?:js|json|mjs|cjs|node)$/;
+
+function walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      walk(path);
+      continue;
+    }
+    if (!/\.(?:js|d\.ts)$/.test(name)) {
+      continue;
+    }
+
+    const source = readFileSync(path, 'utf8');
+    const next = source.replace(
+      /(from\s+|import\s*\()(['"])(\.[^'"]+)\2/g,
+      (match, prefix, quote, spec) =>
+        EXTENSIONS.test(spec) ? match : `${prefix}${quote}${spec}.js${quote}`,
+    );
+    if (next !== source) {
+      writeFileSync(path, next);
+    }
+  }
+}
+
+walk(dist);