tether-ui 0.1.0

package/dist/report/server.js

@@ -0,0 +1,80 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { resolve, extname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { exists } from "../utils/config.js";
+const webRoot = fileURLToPath(new URL("../../report/out/", import.meta.url));
+export async function serveReport(directory, port, open) {
+    if (!(await exists(join(directory, "report.json"))))
+        throw new Error("No report found. Run tether init or tether check first.");
+    if (!(await exists(join(webRoot, "index.html"))))
+        throw new Error("The report has not been built. Run npm run build from the tether repository.");
+    const server = createServer(async (request, response) => {
+        if (!["GET", "HEAD"].includes(request.method ?? "")) {
+            response.writeHead(405).end();
+            return;
+        }
+        if (!/^(localhost|127\.0\.0\.1)(:\d+)?$/.test(request.headers.host ?? "")) {
+            response.writeHead(403).end();
+            return;
+        }
+        try {
+            const pathname = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname);
+            const data = pathname === "/report.json" || pathname.startsWith("/screenshots/");
+            const root = data ? resolve(directory) : resolve(webRoot);
+            let path = resolve(root, "." + pathname);
+            if (path !== root && !path.startsWith(root + sep)) {
+                response.writeHead(403).end();
+                return;
+            }
+            if ((await stat(path)).isDirectory())
+                path = join(path, "index.html");
+            const types = {
+                ".html": "text/html; charset=utf-8",
+                ".js": "application/javascript",
+                ".css": "text/css",
+                ".json": "application/json",
+                ".png": "image/png",
+                ".svg": "image/svg+xml",
+                ".txt": "text/plain",
+                ".ico": "image/x-icon",
+                ".woff2": "font/woff2",
+            };
+            const body = await readFile(path);
+            response.writeHead(200, {
+                "Content-Type": types[extname(path)] ?? "application/octet-stream",
+                "Cache-Control": "no-store",
+                "X-Content-Type-Options": "nosniff",
+                "Content-Security-Policy": "frame-ancestors 'none'",
+            });
+            response.end(request.method === "HEAD" ? undefined : body);
+        }
+        catch {
+            response.writeHead(404).end("Not found");
+        }
+    });
+    await new Promise((done, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", done);
+    }).catch(() => {
+        throw new Error(`Couldn't open report port ${port}. Try tether report --port ${port + 1}.`);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Missing report address");
+    const url = `http://localhost:${address.port}`;
+    console.log(`\ntether report → ${url}\n\nPress Ctrl+C to stop.\n`);
+    if (open) {
+        const command = process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+                ? "cmd"
+                : "xdg-open";
+        const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => console.log(`Open ${url} in your browser.`));
+        child.unref();
+    }
+    return server;
+}

package/dist/scanner/browser.d.ts

@@ -0,0 +1,2 @@
+/** An optional dedicated CDP browser lets restricted CI runners reuse a browser host. */
+export declare function openBrowser(): Promise<import("playwright").Browser>;

package/dist/scanner/browser.js

@@ -0,0 +1,22 @@
+import { chromium } from "playwright";
+/** An optional dedicated CDP browser lets restricted CI runners reuse a browser host. */
+export async function openBrowser() {
+    const endpoint = process.env.TETHER_BROWSER_ENDPOINT;
+    if (endpoint) {
+        try {
+            return await chromium.connectOverCDP(endpoint);
+        }
+        catch {
+            throw new Error(`Couldn't connect to the dedicated browser at ${endpoint}. Check TETHER_BROWSER_ENDPOINT and keep the browser running.`);
+        }
+    }
+    try {
+        return await chromium.launch();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "";
+        if (message.includes("Executable doesn't exist"))
+            throw new Error("Chromium is unavailable. Run npx playwright install chromium and try again.");
+        throw new Error("Chromium could not start. Check browser permissions and sandbox restrictions. A dedicated browser can be supplied with TETHER_BROWSER_ENDPOINT.");
+    }
+}

package/dist/scanner/collect.d.ts

@@ -0,0 +1,10 @@
+import type { ElementRecord, LayoutProblem } from "../types.js";
+/** Pure DOM reader, serialized by Playwright into the page. */
+export declare function collect({ maxElements, ignore, }: {
+    maxElements: number;
+    ignore: string[];
+}): {
+    elements: ElementRecord[];
+    layout: LayoutProblem[];
+    truncated: boolean;
+};

package/dist/scanner/collect.js

@@ -0,0 +1,171 @@
+/** Pure DOM reader, serialized by Playwright into the page. */
+export function collect({ maxElements, ignore, }) {
+    for (const selector of ignore) {
+        try {
+            document.querySelector(selector);
+        }
+        catch {
+            throw new Error(`Invalid ignore selector: ${selector}`);
+        }
+    }
+    const excluded = ignore.length ? ignore.join(",") : null;
+    function visible(el) {
+        if (excluded && el.closest(excluded))
+            return false;
+        if (el.closest("svg, script, style, noscript, template"))
+            return false;
+        if (el.namespaceURI !== "http://www.w3.org/1999/xhtml")
+            return false;
+        for (let node = el; node; node = node.parentElement) {
+            const style = getComputedStyle(node);
+            if (style.display === "none" ||
+                style.visibility === "hidden" ||
+                style.visibility === "collapse" ||
+                style.contentVisibility === "hidden" ||
+                Number(style.opacity) === 0)
+                return false;
+        }
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+    }
+    function escapeCss(value) {
+        return [...value]
+            .map((char, index) => /[a-zA-Z_-]/.test(char) || (index > 0 && /[0-9]/.test(char))
+            ? char
+            : `\\${char.codePointAt(0).toString(16)} `)
+            .join("");
+    }
+    function selectorFor(el) {
+        if (el.id && document.querySelectorAll(`#${escapeCss(el.id)}`).length === 1)
+            return `#${escapeCss(el.id)}`;
+        const testid = el.getAttribute("data-testid");
+        if (testid) {
+            const selector = `[data-testid="${escapeCss(testid)}"]`;
+            if (document.querySelectorAll(selector).length === 1)
+                return selector;
+        }
+        const classes = [...el.classList].filter((c) => /^[a-zA-Z][\w-]*$/.test(c));
+        for (const name of classes)
+            if (document.querySelectorAll(`.${escapeCss(name)}`).length === 1)
+                return `.${escapeCss(name)}`;
+        const parts = [];
+        let node = el;
+        while (node && node !== document.body) {
+            const parent = node.parentElement;
+            const siblings = parent
+                ? [...parent.children].filter((c) => c.tagName === node.tagName)
+                : [];
+            parts.unshift(`${node.tagName.toLowerCase()}${siblings.length > 1 ? `:nth-of-type(${siblings.indexOf(node) + 1})` : ""}`);
+            node = parent;
+        }
+        return parts.length ? `body > ${parts.join(" > ")}` : "body";
+    }
+    function scrollContainer(el) {
+        let p = el.parentElement;
+        while (p && p !== document.body && p !== document.documentElement) {
+            if (["auto", "scroll", "hidden", "clip"].includes(getComputedStyle(p).overflowX))
+                return true;
+            p = p.parentElement;
+        }
+        return false;
+    }
+    const elements = [];
+    const layout = [];
+    const candidates = document.body.querySelectorAll("*");
+    let visited = 0;
+    const offscreenParents = [];
+    const documentWidth = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth);
+    if (documentWidth > innerWidth + 2)
+        layout.push({
+            selector: "html",
+            kind: "overflow",
+            value: `${documentWidth - innerWidth}px horizontal overflow`,
+            severity: "high",
+        });
+    for (const el of candidates) {
+        if (++visited > maxElements)
+            break;
+        if (!visible(el))
+            continue;
+        const style = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        const selector = selectorFor(el);
+        const observations = [];
+        function add(category, property, value = style.getPropertyValue(property)) {
+            if (value &&
+                ![
+                    "normal",
+                    "none",
+                    "auto",
+                    "0px",
+                    "rgba(0, 0, 0, 0)",
+                    "transparent",
+                ].includes(value))
+                observations.push({ category, property, value });
+        }
+        const hasText = [...el.childNodes].some((n) => n.nodeType === 3 && !!n.textContent?.trim());
+        const control = el.matches("button, input:not([type=hidden]), select, textarea, [role=button], [role=switch]");
+        if (hasText || control) {
+            add("colors", "color");
+            add("fontFamilies", "font-family");
+            add("fontSizes", "font-size");
+            add("fontWeights", "font-weight");
+            add("lineHeights", "line-height");
+        }
+        add("colors", "background-color");
+        for (const side of ["top", "right", "bottom", "left"]) {
+            if (Number.parseFloat(style.getPropertyValue(`border-${side}-width`)) > 0 &&
+                style.getPropertyValue(`border-${side}-style`) !== "none") {
+                add("borders", "border", `${style.getPropertyValue(`border-${side}-width`)} ${style.getPropertyValue(`border-${side}-style`)} ${style.getPropertyValue(`border-${side}-color`)}`);
+                add("colors", "border-color", style.getPropertyValue(`border-${side}-color`));
+            }
+            add("spacing", `padding-${side}`);
+            // Browsers resolve auto margins to large layout-dependent pixel values.
+            // Keep the token scale focused on local spacing rather than centering offsets.
+            const margin = style.getPropertyValue(`margin-${side}`);
+            if (Math.abs(Number.parseFloat(margin)) <= 96)
+                add("spacing", `margin-${side}`, margin);
+        }
+        for (const corner of [
+            "top-left",
+            "top-right",
+            "bottom-right",
+            "bottom-left",
+        ])
+            add("radii", "border-radius", style.getPropertyValue(`border-${corner}-radius`));
+        if (["flex", "inline-flex", "grid", "inline-grid"].includes(style.display)) {
+            add("spacing", "row-gap");
+            add("spacing", "column-gap");
+        }
+        add("shadows", "box-shadow");
+        if (control)
+            add("elementHeights", "height", `${rect.height}px`);
+        elements.push({ selector, tag: el.tagName.toLowerCase(), observations });
+        const outside = Math.max(0, rect.right - innerWidth, -rect.left);
+        if (outside > 4 &&
+            !scrollContainer(el) &&
+            !offscreenParents.some((p) => p.contains(el))) {
+            layout.push({
+                selector,
+                kind: "offscreen",
+                value: `${Math.round(outside)}px outside ${innerWidth}px viewport`,
+                severity: outside > 24 ? "high" : "medium",
+            });
+            offscreenParents.push(el);
+        }
+        // Intentional ellipsis, line clamping and scrollable regions are not clipping errors.
+        if (hasText &&
+            style.textOverflow !== "ellipsis" &&
+            style.webkitLineClamp === "none" &&
+            ["hidden", "clip"].includes(style.overflowY) &&
+            el.scrollHeight > el.clientHeight + 4) {
+            layout.push({
+                selector,
+                kind: "clipped",
+                value: `${el.scrollHeight - el.clientHeight}px clipped content`,
+                severity: "medium",
+            });
+        }
+    }
+    return { elements, layout, truncated: candidates.length > maxElements };
+}

package/dist/scanner/scan.d.ts

@@ -0,0 +1,2 @@
+import type { Config, Scan } from "../types.js";
+export declare function scan(config: Config, directory: string, phase: string): Promise<Scan>;

package/dist/scanner/scan.js

@@ -0,0 +1,82 @@
+import { openBrowser } from "./browser.js";
+import { collect } from "./collect.js";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { normalizeValue } from "../utils/normalize.js";
+import { targetUrl } from "../utils/config.js";
+export async function scan(config, directory, phase) {
+    await mkdir(join(directory, "screenshots", phase), { recursive: true });
+    const browser = await openBrowser();
+    const result = {
+        version: 1,
+        createdAt: new Date().toISOString(),
+        url: config.url,
+        snapshots: [],
+    };
+    try {
+        for (const route of config.routes)
+            for (const viewport of config.viewports) {
+                const context = await browser.newContext({
+                    viewport: { width: viewport.width, height: viewport.height },
+                    deviceScaleFactor: 1,
+                    colorScheme: "light",
+                    reducedMotion: "reduce",
+                });
+                const page = await context.newPage();
+                const url = targetUrl(config.url, route);
+                try {
+                    const response = await page.goto(url, {
+                        waitUntil: "load",
+                        timeout: 30000,
+                    });
+                    if (response && response.status() >= 400)
+                        throw new Error(`HTTP ${response.status()}`);
+                }
+                catch {
+                    throw new Error(`tether couldn't reach ${url}.\nStart your application, check the route, and try again.`);
+                }
+                await page.addStyleTag({
+                    content: "*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; }",
+                });
+                await page.evaluate(() => Promise.race([
+                    document.fonts.ready,
+                    new Promise((resolve) => setTimeout(resolve, 5000)),
+                ]));
+                await page.waitForTimeout(config.settleMs);
+                const collected = await page.evaluate(collect, {
+                    maxElements: config.maxElements,
+                    ignore: config.ignore,
+                });
+                if (!collected.elements.length)
+                    throw new Error(`No visible elements found at ${url} (${viewport.name}). Check your route and ignore selectors.`);
+                for (const element of collected.elements) {
+                    element.observations = [
+                        ...new Map(element.observations.map((o) => {
+                            const normalized = {
+                                ...o,
+                                value: normalizeValue(o.property, o.value),
+                            };
+                            return [
+                                `${o.category}\0${o.property}\0${normalized.value}`,
+                                normalized,
+                            ];
+                        })).values(),
+                    ].filter((o) => o.value !== "transparent" && o.value !== "0px");
+                }
+                const filename = `${createHash("sha256").update(route).digest("hex").slice(0, 12)}-${viewport.name}.png`;
+                const screenshot = `screenshots/${phase}/${filename}`;
+                await page.screenshot({
+                    path: join(directory, screenshot),
+                    fullPage: false,
+                    animations: "disabled",
+                });
+                result.snapshots.push({ route, viewport, ...collected, screenshot });
+                await context.close();
+            }
+        return result;
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export declare const categories: readonly ["colors", "fontFamilies", "fontSizes", "fontWeights", "lineHeights", "spacing", "radii", "shadows", "borders", "elementHeights"];
+export type Category = (typeof categories)[number];
+export type Severity = "low" | "medium" | "high";
+export interface Viewport {
+    name: string;
+    width: number;
+    height: number;
+}
+export interface Config {
+    url: string;
+    routes: string[];
+    viewports: Viewport[];
+    minOccurrences: number;
+    maxElements: number;
+    settleMs: number;
+    ignore: string[];
+}
+export interface Observation {
+    category: Category;
+    property: string;
+    value: string;
+}
+export interface ElementRecord {
+    selector: string;
+    tag: string;
+    observations: Observation[];
+}
+export interface LayoutProblem {
+    selector: string;
+    kind: "overflow" | "offscreen" | "clipped";
+    value: string;
+    severity: Severity;
+}
+export interface Snapshot {
+    route: string;
+    viewport: Viewport;
+    elements: ElementRecord[];
+    layout: LayoutProblem[];
+    screenshot: string;
+    truncated: boolean;
+}
+export interface Scan {
+    version: 1;
+    createdAt: string;
+    url: string;
+    snapshots: Snapshot[];
+}
+export interface Token {
+    value: string;
+    count: number;
+}
+export type Contract = {
+    version: 1;
+    createdAt: string;
+    minOccurrences: number;
+} & Record<Category, Token[]>;
+export interface Issue {
+    id: string;
+    category: Category | "layout";
+    severity: Severity;
+    title: string;
+    selector: string;
+    property: string;
+    current: string;
+    expected: string[];
+    route: string;
+    viewports: string[];
+}
+export interface Report {
+    version: 1;
+    baselineAt: string;
+    scan: Scan;
+    contract: Contract;
+    issues: Issue[];
+    score: number;
+    elementCount: number;
+    agentMarkdown: string;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+export const categories = [
+    "colors",
+    "fontFamilies",
+    "fontSizes",
+    "fontWeights",
+    "lineHeights",
+    "spacing",
+    "radii",
+    "shadows",
+    "borders",
+    "elementHeights",
+];

package/dist/utils/config.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from "../types.js";
+export declare const defaults: Config;
+export declare function exists(path: string): Promise<boolean>;
+export declare function loadConfig(cwd: string, url?: string, file?: string): Promise<Config>;
+export declare function targetUrl(base: string, route: string): string;

package/dist/utils/config.js

@@ -0,0 +1,85 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createJiti } from "jiti";
+export const defaults = {
+    url: "http://localhost:3000",
+    routes: ["/"],
+    viewports: [
+        { name: "desktop", width: 1440, height: 1000 },
+        { name: "laptop", width: 1024, height: 900 },
+        { name: "tablet", width: 768, height: 900 },
+        { name: "mobile", width: 390, height: 844 },
+    ],
+    minOccurrences: 2,
+    maxElements: 5000,
+    settleMs: 250,
+    ignore: ["[data-tether-ignore]"],
+};
+export async function exists(path) {
+    return access(path).then(() => true, () => false);
+}
+export async function loadConfig(cwd, url, file) {
+    const path = resolve(cwd, file ?? "tether.config.ts");
+    let input = {};
+    if (file && !(await exists(path)))
+        throw new Error(`Configuration not found: ${path}`);
+    if (await exists(path)) {
+        try {
+            input = await createJiti(import.meta.url).import(path, { default: true });
+        }
+        catch {
+            throw new Error("Could not load tether.config.ts. Check its syntax and default export.");
+        }
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Configuration must export an object.");
+    const config = { ...defaults, ...input, ...(url ? { url } : {}) };
+    try {
+        if (!["http:", "https:"].includes(new URL(config.url).protocol))
+            throw 0;
+    }
+    catch {
+        throw new Error("Config url must be an http:// or https:// URL.");
+    }
+    if (!Array.isArray(config.routes) ||
+        !config.routes.length ||
+        config.routes.some((r) => typeof r !== "string" || !r.startsWith("/") || r.startsWith("//")))
+        throw new Error('Config routes must contain local paths beginning with /, such as ["/", "/settings"].');
+    if (!Array.isArray(config.viewports) ||
+        !config.viewports.length ||
+        config.viewports.some((v) => !v ||
+            !/^[a-zA-Z0-9_-]+$/.test(v.name) ||
+            !Number.isInteger(v.width) ||
+            !Number.isInteger(v.height) ||
+            v.width < 200 ||
+            v.width > 7680 ||
+            v.height < 200 ||
+            v.height > 7680))
+        throw new Error("Viewports need unique names and integer dimensions between 200 and 7680.");
+    if (new Set(config.viewports.map((v) => v.name)).size !==
+        config.viewports.length)
+        throw new Error("Viewport names must be unique.");
+    for (const [key, min, max] of [
+        ["minOccurrences", 1, 1000],
+        ["maxElements", 1, 50000],
+        ["settleMs", 0, 30000],
+    ]) {
+        if (!Number.isInteger(config[key]) ||
+            config[key] < min ||
+            config[key] > max)
+            throw new Error(`Config ${key} must be an integer between ${min} and ${max}.`);
+    }
+    if (!Array.isArray(config.ignore) ||
+        config.ignore.some((s) => typeof s !== "string" || !s.trim()))
+        throw new Error("Config ignore must be a list of CSS selectors.");
+    config.routes = [...new Set(config.routes)];
+    return config;
+}
+export function targetUrl(base, route) {
+    const result = new URL(route, base);
+    const original = new URL(base);
+    for (const [key, value] of original.searchParams)
+        if (!result.searchParams.has(key))
+            result.searchParams.append(key, value);
+    return result.toString();
+}

package/dist/utils/normalize.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizeNumber(value: number): number;
+export declare function normalizeColor(input: string): string;
+export declare function normalizeValue(property: string, input: string): string;
+export declare function colorDistance(a: string, b: string): number;

package/dist/utils/normalize.js

@@ -0,0 +1,66 @@
+export function normalizeNumber(value) {
+    const integer = Math.round(value);
+    return Math.abs(value - integer) <= 0.05
+        ? integer
+        : Math.round(value * 10) / 10;
+}
+export function normalizeColor(input) {
+    const value = input.trim().toLowerCase();
+    if (value === "transparent")
+        return "transparent";
+    let channels;
+    if (/^#[\da-f]{3,8}$/.test(value)) {
+        let hex = value.slice(1);
+        if (hex.length === 3 || hex.length === 4)
+            hex = [...hex].map((c) => c + c).join("");
+        if (hex.length === 6 || hex.length === 8)
+            channels = [0, 2, 4]
+                .map((i) => parseInt(hex.slice(i, i + 2), 16))
+                .concat(hex.length === 8 ? parseInt(hex.slice(6), 16) / 255 : 1);
+    }
+    else if (/^rgba?\(/.test(value)) {
+        const parts = value
+            .slice(value.indexOf("(") + 1, -1)
+            .split(/[\s,/]+/)
+            .filter(Boolean);
+        channels = parts
+            .slice(0, 3)
+            .map((p) => parseFloat(p) * (p.endsWith("%") ? 2.55 : 1));
+        channels.push(parts[3] ? parseFloat(parts[3]) / (parts[3].endsWith("%") ? 100 : 1) : 1);
+    }
+    if (!channels ||
+        channels.length !== 4 ||
+        channels.some((n) => !Number.isFinite(n)))
+        return value;
+    const [r, g, b, a] = channels;
+    if (a <= 0.001)
+        return "transparent";
+    const hex = "#" +
+        [r, g, b]
+            .map((n) => Math.min(255, Math.max(0, Math.round(n)))
+            .toString(16)
+            .padStart(2, "0"))
+            .join("")
+            .toUpperCase();
+    return a >= 0.999
+        ? hex
+        : `${hex}${Math.round(Math.max(0, Math.min(1, a)) * 255)
+            .toString(16)
+            .padStart(2, "0")
+            .toUpperCase()}`;
+}
+export function normalizeValue(property, input) {
+    let value = input.trim().replace(/\s+/g, " ");
+    if (property === "font-weight")
+        return ({ normal: "400", bold: "700" }[value] ?? value);
+    value = value.replace(/rgba?\([^)]*\)|#[\da-fA-F]{3,8}\b/g, normalizeColor);
+    value = value.replace(/(-?\d*\.?\d+)px/g, (_, n) => `${normalizeNumber(Number(n))}px`);
+    if (value.toLowerCase() === "transparent")
+        return "transparent";
+    return value.replace(/,\s*/g, ", ").replace(/\s*\/\s*/g, " / ");
+}
+export function colorDistance(a, b) {
+    if (!/^#[\dA-F]{6}$/.test(a) || !/^#[\dA-F]{6}$/.test(b))
+        return a === b ? 0 : Infinity;
+    return Math.max(...[1, 3, 5].map((i) => Math.abs(parseInt(a.slice(i, i + 2), 16) - parseInt(b.slice(i, i + 2), 16))));
+}

package/dist/utils/storage.d.ts

@@ -0,0 +1,2 @@
+export declare function readJson<T>(path: string): Promise<T>;
+export declare function writeJson(path: string, data: unknown): Promise<void>;

package/dist/utils/storage.js

@@ -0,0 +1,17 @@
+import { readFile, writeFile, rename, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+export async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        throw new Error(`Could not read ${path}. Run tether init to create a valid baseline.`);
+    }
+}
+export async function writeJson(path, data) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify(data, null, 2) + "\n");
+    await rename(temporary, path);
+}