@cardanvil/frame-kit 0.2.0

package/dist/cli/frameIndex.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { CONTRACT_VERSION } from "../manifest/contract.js";
+/** Bumped only when the index's own shape changes, not the frame contract's. */
+export const FRAME_INDEX_FORMAT_VERSION = 1;
+export const FRAME_INDEX_FILENAME = "frame-index.json";
+const ArtifactSchema = z.object({
+    /** Filename as attached to the release. Always present. */
+    file: z.string(),
+    /** Absolute URL. Absent for a local build, which has no release to point at. */
+    url: z.url().optional(),
+    bytes: z.int().nonnegative(),
+    sha256: z.string(),
+});
+const PreviewSchema = ArtifactSchema.extend({
+    width: z.int().positive().optional(),
+    height: z.int().positive().optional(),
+});
+export const IndexedFrameSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    description: z.string(),
+    version: z.string(),
+    tags: z.array(z.string()),
+    /** Layout names the frame supports, so a browse UI can filter on them. */
+    layouts: z.array(z.string()),
+    canvas: z.object({ width: z.int(), height: z.int() }),
+    author: z.object({ name: z.string(), url: z.string().optional() }),
+    license: z.string(),
+    homepage: z.string().optional(),
+    /** Which frame contract the bundle targets — a client filters on this. */
+    contractVersion: z.string(),
+    assetCount: z.int().nonnegative(),
+    bundle: ArtifactSchema,
+    preview: PreviewSchema,
+});
+export const FrameIndexSchema = z.object({
+    /** Envelope discriminators, so a consumer handed the wrong JSON can say so. */
+    app: z.literal("card-anvil"),
+    kind: z.literal("frame-index"),
+    formatVersion: z.int().positive(),
+    generatedAt: z.string(),
+    generator: z.string().optional(),
+    /** The contract the generating frame-kit implements. */
+    contractVersion: z.string(),
+    /** The release version. One version covers every frame in the repository. */
+    version: z.string(),
+    /**
+     * Where this index came from. Omitted for a local build. An aggregator that
+     * merged many repositories keeps this so it can still re-fetch each one.
+     */
+    source: z
+        .object({
+        kind: z.literal("github-release"),
+        repository: z.string(),
+        tag: z.string(),
+        url: z.url(),
+        downloadBase: z.url(),
+        /** Always the newest release — what a marketplace polls. */
+        latestIndexUrl: z.url(),
+    })
+        .optional(),
+    frames: z.array(IndexedFrameSchema),
+});
+/** Where a release's assets are downloadable from. */
+export function downloadBase(source) {
+    return `https://github.com/${source.repository}/releases/download/${source.tag}/`;
+}
+/**
+ * The stable URL a marketplace polls: GitHub resolves `latest` to the newest
+ * published, non-prerelease release, so it needs no API call and no auth. This
+ * is the same convention Card Anvil's own updater relies on.
+ */
+export function latestIndexUrl(repository) {
+    return `https://github.com/${repository}/releases/latest/download/${FRAME_INDEX_FILENAME}`;
+}
+export function buildSource(source) {
+    return {
+        kind: "github-release",
+        repository: source.repository,
+        tag: source.tag,
+        url: `https://github.com/${source.repository}/releases/tag/${source.tag}`,
+        downloadBase: downloadBase(source),
+        latestIndexUrl: latestIndexUrl(source.repository),
+    };
+}
+export function buildIndex(options) {
+    return {
+        app: "card-anvil",
+        kind: "frame-index",
+        formatVersion: FRAME_INDEX_FORMAT_VERSION,
+        generatedAt: (options.generatedAt ?? new Date()).toISOString(),
+        ...(options.generator === undefined
+            ? {}
+            : { generator: options.generator }),
+        contractVersion: CONTRACT_VERSION,
+        version: options.version,
+        ...(options.source === undefined
+            ? {}
+            : { source: buildSource(options.source) }),
+        // Sorted by id so the index is stable and diffable across releases.
+        frames: [...options.frames].sort((a, b) => a.id.localeCompare(b.id)),
+    };
+}

package/dist/cli/hash.d.ts

@@ -0,0 +1,14 @@
+/**
+ * sha256 of a file, streamed.
+ *
+ * Streamed rather than read whole because frame art runs to hundreds of
+ * megabytes across a frame, and every asset is hashed on every build.
+ */
+export declare function hashFile(file: string): Promise<string>;
+/**
+ * Runs `worker` over every item, at most `limit` at a time.
+ *
+ * Hashing is IO-bound; unbounded concurrency over a few hundred files just
+ * exhausts file handles.
+ */
+export declare function mapWithConcurrency<T>(items: readonly T[], limit: number, worker: (item: T) => Promise<void>): Promise<void>;

package/dist/cli/hash.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+/**
+ * sha256 of a file, streamed.
+ *
+ * Streamed rather than read whole because frame art runs to hundreds of
+ * megabytes across a frame, and every asset is hashed on every build.
+ */
+export async function hashFile(file) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(file), hash);
+    return hash.digest("hex");
+}
+/**
+ * Runs `worker` over every item, at most `limit` at a time.
+ *
+ * Hashing is IO-bound; unbounded concurrency over a few hundred files just
+ * exhausts file handles.
+ */
+export async function mapWithConcurrency(items, limit, worker) {
+    let next = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const item = items[next++];
+            if (item !== undefined) {
+                await worker(item);
+            }
+        }
+    });
+    await Promise.all(runners);
+}

package/dist/cli/imageSize.d.ts

@@ -0,0 +1,13 @@
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/**
+ * Reads the pixel dimensions of a PNG or JPEG from its header.
+ *
+ * Hand-rolled rather than pulled from a dependency because it is a few dozen
+ * bytes of well-specified header and this runs in every author's CI. Returns
+ * `undefined` for anything it does not understand — dimensions are a nicety
+ * for a browse UI, never a reason to fail a build.
+ */
+export declare function readImageSize(file: string): Promise<ImageSize | undefined>;

package/dist/cli/imageSize.js

@@ -0,0 +1,72 @@
+import { open } from "node:fs/promises";
+/** Enough for a PNG header and for the SOF marker of any sane JPEG. */
+const HEADER_BYTES = 64 * 1024;
+const PNG_SIGNATURE = Buffer.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+/**
+ * Reads the pixel dimensions of a PNG or JPEG from its header.
+ *
+ * Hand-rolled rather than pulled from a dependency because it is a few dozen
+ * bytes of well-specified header and this runs in every author's CI. Returns
+ * `undefined` for anything it does not understand — dimensions are a nicety
+ * for a browse UI, never a reason to fail a build.
+ */
+export async function readImageSize(file) {
+    let handle;
+    try {
+        handle = await open(file, "r");
+        const buffer = Buffer.alloc(HEADER_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, HEADER_BYTES, 0);
+        const header = buffer.subarray(0, bytesRead);
+        return readPng(header) ?? readJpeg(header);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/** IHDR is always the first chunk: signature (8) + length (4) + type (4). */
+function readPng(header) {
+    if (header.length < 24 || !header.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        return undefined;
+    }
+    if (header.subarray(12, 16).toString("latin1") !== "IHDR") {
+        return undefined;
+    }
+    return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
+}
+/**
+ * Walks the JPEG marker chain to the start-of-frame, which carries the size.
+ * Every other marker is a length-prefixed segment to skip over.
+ */
+function readJpeg(header) {
+    if (header.length < 4 || header.readUInt16BE(0) !== 0xffd8) {
+        return undefined;
+    }
+    let offset = 2;
+    while (offset + 9 < header.length) {
+        if (header[offset] !== 0xff) {
+            return undefined; // out of sync with the marker chain
+        }
+        const marker = header[offset + 1];
+        if (marker === undefined) {
+            return undefined;
+        }
+        // SOF0-SOF15 carry the frame header; C4, C8 and CC are other things.
+        if (marker >= 0xc0 &&
+            marker <= 0xcf &&
+            marker !== 0xc4 &&
+            marker !== 0xc8 &&
+            marker !== 0xcc) {
+            return {
+                height: header.readUInt16BE(offset + 5),
+                width: header.readUInt16BE(offset + 7),
+            };
+        }
+        offset += 2 + header.readUInt16BE(offset + 2);
+    }
+    return undefined;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Packaging: turning authored frames into distributable bundles.
+ *
+ * Separate from the main entry point because it needs Node and Vite, neither of
+ * which a browser or Card Anvil's bundle has. Importing this pulls in the
+ * packaging machinery; importing `@cardanvil/frame-kit` does not.
+ */
+export { type LoadOptions, type LoadedFrame, type ValidateResult, loadFrames, validateFrames, } from "./api.js";
+export { type BuildOptions, type BuildResult, type BuiltFrame, buildFrames, } from "./build.js";
+export { describeBytes } from "./bundle.js";
+export { type DiscoveredFrame, discoverFrames, relativePosix, } from "./discover.js";
+export { devUrlToFile } from "./devUrl.js";
+export { PackagingError } from "./errors.js";
+export { FRAME_INDEX_FILENAME, FRAME_INDEX_FORMAT_VERSION, type FrameIndex, FrameIndexSchema, type IndexedFrame, IndexedFrameSchema, type ReleaseSource, buildIndex, downloadBase, latestIndexUrl, } from "./frameIndex.js";
+export { type FrameServer, loadFrameExport, startFrameServer, } from "./loadFrame.js";
+export { type Problem, Reporter, type Severity, formatProblem, inGitHubActions, } from "./report.js";
+export { SCHEMA_NAMES, SHIPPED_SCHEMAS, type SchemaName, schemaFilename, toJsonSchema, } from "./schema.js";
+export { stableStringify } from "./stableJson.js";

package/dist/cli/index.js

@@ -0,0 +1,18 @@
+/**
+ * Packaging: turning authored frames into distributable bundles.
+ *
+ * Separate from the main entry point because it needs Node and Vite, neither of
+ * which a browser or Card Anvil's bundle has. Importing this pulls in the
+ * packaging machinery; importing `@cardanvil/frame-kit` does not.
+ */
+export { loadFrames, validateFrames, } from "./api.js";
+export { buildFrames, } from "./build.js";
+export { describeBytes } from "./bundle.js";
+export { discoverFrames, relativePosix, } from "./discover.js";
+export { devUrlToFile } from "./devUrl.js";
+export { PackagingError } from "./errors.js";
+export { FRAME_INDEX_FILENAME, FRAME_INDEX_FORMAT_VERSION, FrameIndexSchema, IndexedFrameSchema, buildIndex, downloadBase, latestIndexUrl, } from "./frameIndex.js";
+export { loadFrameExport, startFrameServer, } from "./loadFrame.js";
+export { Reporter, formatProblem, inGitHubActions, } from "./report.js";
+export { SCHEMA_NAMES, SHIPPED_SCHEMAS, schemaFilename, toJsonSchema, } from "./schema.js";
+export { stableStringify } from "./stableJson.js";

package/dist/cli/loadFrame.d.ts

@@ -0,0 +1,24 @@
+import type { ViteDevServer } from "vite";
+export interface FrameServer {
+    readonly server: ViteDevServer;
+    /** Absolute project root every asset URL is relative to. */
+    readonly root: string;
+    /** Vite's dev base, the prefix on every asset URL. */
+    readonly base: string;
+    close(): Promise<void>;
+}
+/**
+ * Starts one Vite server for a whole packaging run.
+ *
+ * Starting it is the expensive part, and frames that extend one another share
+ * the module graph, so it is deliberately not per-frame.
+ */
+export declare function startFrameServer(root: string): Promise<FrameServer>;
+/**
+ * Loads one frame's module and returns the named export, unvalidated.
+ *
+ * Returns `unknown` rather than trusting `ssrLoadModule`'s `Record<string, any>`
+ * — the caller parses it against `FrameSchema`, which is the only thing that
+ * decides whether it is a frame.
+ */
+export declare function loadFrameExport(frameServer: FrameServer, entryFile: string, exportName: string): Promise<unknown>;

package/dist/cli/loadFrame.js

@@ -0,0 +1,90 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { PackagingError } from "./errors.js";
+/**
+ * Vite is what turns `import w from "./w.png"` into a URL, so a frame cannot be
+ * packaged without it.
+ *
+ * It is an *optional* peer, imported dynamically: frame-kit's schemas and
+ * manifest helpers have to keep working under plain Node, in a browser, and
+ * inside Card Anvil's bundle, none of which have Vite. Nothing on those paths
+ * ever reaches this module.
+ */
+async function importVite() {
+    try {
+        return await import("vite");
+    }
+    catch {
+        throw new PackagingError("Vite is not installed.\n\n" +
+            'Frames import their art directly (`import w from "./w.png"`), and only\n' +
+            "a bundler can turn those imports into files. Install it:\n\n" +
+            "  pnpm add -D vite\n");
+    }
+}
+/**
+ * Starts one Vite server for a whole packaging run.
+ *
+ * Starting it is the expensive part, and frames that extend one another share
+ * the module graph, so it is deliberately not per-frame.
+ */
+export async function startFrameServer(root) {
+    const vite = await importVite();
+    const cacheDir = await mkdtemp(path.join(tmpdir(), "frame-kit-"));
+    const server = await vite.createServer({
+        // Never inherit the author's config. Its `base`, plugins and asset rules
+        // would change the URLs we get back, and a frame that only packages
+        // correctly under one app's config is not distributable.
+        configFile: false,
+        root,
+        appType: "custom",
+        logLevel: "warn",
+        // Nothing is ever served over HTTP; the module runner is the whole point.
+        server: { middlewareMode: true, hmr: false, watch: null },
+        build: {
+            // Vite inlines small assets as data URLs in serve mode too, not just at
+            // build time. A data URL has no file to package, so an SVG mask under
+            // the default 4 KB limit would silently vanish from the bundle.
+            assetsInlineLimit: 0,
+        },
+        optimizeDeps: { noDiscovery: true },
+        // Keep the dep cache out of the author's node_modules.
+        cacheDir,
+        resolve: { dedupe: ["zod"] },
+    });
+    return {
+        server,
+        root: path.resolve(root),
+        base: server.config.base,
+        async close() {
+            await server.close();
+            await rm(cacheDir, { recursive: true, force: true });
+        },
+    };
+}
+/**
+ * Loads one frame's module and returns the named export, unvalidated.
+ *
+ * Returns `unknown` rather than trusting `ssrLoadModule`'s `Record<string, any>`
+ * — the caller parses it against `FrameSchema`, which is the only thing that
+ * decides whether it is a frame.
+ */
+export async function loadFrameExport(frameServer, entryFile, exportName) {
+    let namespace;
+    try {
+        namespace = (await frameServer.server.ssrLoadModule(entryFile));
+    }
+    catch (cause) {
+        throw new PackagingError(`could not load ${entryFile}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (!(exportName in namespace)) {
+        const available = Object.keys(namespace)
+            .filter((key) => key !== "default" || "default" in namespace)
+            .sort()
+            .join(", ");
+        throw new PackagingError(`${entryFile} has no export named "${exportName}". ` +
+            (available ? `It exports: ${available}.` : "It exports nothing.") +
+            ` Set "export" in frame.meta.json to the one that is the frame.`);
+    }
+    return namespace[exportName];
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { validateFrames } from "./api.js";
+import { buildFrames } from "./build.js";
+import { describeBytes } from "./bundle.js";
+import { PackagingError } from "./errors.js";
+import { Reporter, inGitHubActions } from "./report.js";
+import { SCHEMA_NAMES, toJsonSchema } from "./schema.js";
+import { stableStringify } from "./stableJson.js";
+const USAGE = `frame-kit — package Card Anvil frames
+
+Usage:
+  frame-kit validate [options]           check every frame, write nothing
+  frame-kit build --out <dir> [options]  check every frame, then pack each one
+  frame-kit schema <name> [--out <file>] print a format as JSON Schema
+                                         (${SCHEMA_NAMES.join(" | ")})
+  frame-kit --help
+  frame-kit --version
+
+Options:
+  --root <dir>          where to look for frames (default: the current directory)
+  --frame <slug>        only this frame; repeatable
+  --summary-md <file>   append a Markdown summary (use "$GITHUB_STEP_SUMMARY")
+  --json                machine-readable output
+
+build only:
+  --out <dir>           where bundles are written (required)
+  --version <x.y.z>     version stamped into every frame
+                        (default: the version in the repository's package.json)
+  --repository <o/n>    the GitHub repository the release belongs to
+  --tag <vX.Y.Z>        the release tag; with --repository, puts download URLs
+                        in the index
+
+A frame is any directory containing a frame.meta.json.
+`;
+/** 0 clean · 1 one or more frames failed · 2 the command was used wrongly. */
+const EXIT = { ok: 0, failed: 1, usage: 2 };
+async function packageVersion() {
+    const manifest = JSON.parse(await readFile(path.join(import.meta.dirname, "../../package.json"), "utf8"));
+    const version = manifest.version;
+    return typeof version === "string" ? version : "0.0.0";
+}
+/** The single version every frame in a repository is released under. */
+async function repositoryVersion(root) {
+    try {
+        const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+        const version = manifest.version;
+        if (typeof version === "string") {
+            return version;
+        }
+    }
+    catch {
+        // No package.json, or an unreadable one — the message below covers both.
+    }
+    throw new PackagingError("no version to stamp into the frames. Pass --version, or set one in the " +
+        "repository's package.json.");
+}
+async function emit(reporter, summaryFile) {
+    if (reporter.problems.length > 0) {
+        console.error(inGitHubActions() ? reporter.toAnnotations() : reporter.toText());
+    }
+    if (summaryFile) {
+        const body = reporter.ok
+            ? "### Frames\n\nEvery frame is valid.\n"
+            : `### Frames\n\n${reporter.toMarkdown()}\n`;
+        await appendFile(summaryFile, body, "utf8");
+    }
+}
+function summarise(reporter, frames) {
+    const { length: errors } = reporter.errors;
+    const { length: warnings } = reporter.warnings;
+    console.log([
+        `${String(frames)} frame${frames === 1 ? "" : "s"}`,
+        errors > 0
+            ? `${String(errors)} error${errors === 1 ? "" : "s"}`
+            : undefined,
+        warnings > 0
+            ? `${String(warnings)} warning${warnings === 1 ? "" : "s"}`
+            : undefined,
+    ]
+        .filter(Boolean)
+        .join(", "));
+}
+async function runValidate(root, only, values) {
+    const { reporter, frames } = await validateFrames({ root, only });
+    if (values.json) {
+        console.log(JSON.stringify({ ok: reporter.ok, frames: frames.length, problems: reporter.problems }, null, 2));
+    }
+    else {
+        await emit(reporter, values["summary-md"]);
+        summarise(reporter, frames.length);
+    }
+    return reporter.ok ? EXIT.ok : EXIT.failed;
+}
+async function runBuild(root, only, values) {
+    if (values.out === undefined) {
+        console.error(`build needs --out <dir>.\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const version = values.version ?? (await repositoryVersion(root));
+    const reporter = new Reporter();
+    const { frames: built } = await buildFrames({
+        root,
+        only,
+        outDir: values.out,
+        version,
+        generator: `@cardanvil/frame-kit@${await packageVersion()}`,
+        // Both or neither: a download URL needs the repository and the tag.
+        ...(values.repository !== undefined && values.tag !== undefined
+            ? { source: { repository: values.repository, tag: values.tag } }
+            : {}),
+    }, reporter);
+    if (values.json) {
+        console.log(JSON.stringify({
+            ok: reporter.ok,
+            version,
+            frames: built.map((frame) => ({
+                id: frame.manifest.id,
+                slug: frame.loaded.discovered.slug,
+                bundle: frame.bundleName,
+                bytes: frame.bytes,
+            })),
+            problems: reporter.problems,
+        }, null, 2));
+    }
+    else {
+        await emit(reporter, values["summary-md"]);
+        for (const frame of built) {
+            console.log(`${frame.bundleName}  ${describeBytes(frame.bytes)}`);
+        }
+        summarise(reporter, built.length);
+    }
+    return reporter.ok ? EXIT.ok : EXIT.failed;
+}
+function isSchemaName(name) {
+    return SCHEMA_NAMES.includes(name);
+}
+async function runSchema(argv) {
+    const name = argv[0];
+    if (name === undefined || !isSchemaName(name)) {
+        console.error(`schema needs one of: ${SCHEMA_NAMES.join(", ")}.
+
+${USAGE}`);
+        return EXIT.usage;
+    }
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv.slice(1),
+            options: { out: { type: "string" } },
+            strict: true,
+        }));
+    }
+    catch (cause) {
+        console.error(`${cause instanceof Error ? cause.message : String(cause)}
+
+${USAGE}`);
+        return EXIT.usage;
+    }
+    const json = stableStringify(toJsonSchema(name));
+    if (values.out === undefined) {
+        process.stdout.write(json);
+    }
+    else {
+        await writeFile(values.out, json, "utf8");
+    }
+    return EXIT.ok;
+}
+async function main(argv) {
+    const command = argv[0];
+    if (command === undefined || command === "--help" || command === "-h") {
+        console.log(USAGE);
+        return command === undefined ? EXIT.usage : EXIT.ok;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(await packageVersion());
+        return EXIT.ok;
+    }
+    if (command === "schema") {
+        return await runSchema(argv.slice(1));
+    }
+    if (command !== "validate" && command !== "build") {
+        console.error(`Unknown command "${command}".\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv.slice(1),
+            options: {
+                root: { type: "string" },
+                frame: { type: "string", multiple: true },
+                "summary-md": { type: "string" },
+                json: { type: "boolean" },
+                out: { type: "string" },
+                version: { type: "string" },
+                repository: { type: "string" },
+                tag: { type: "string" },
+            },
+            strict: true,
+        }));
+    }
+    catch (cause) {
+        console.error(`${cause instanceof Error ? cause.message : String(cause)}\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const root = path.resolve(values.root ?? process.cwd());
+    const only = values.frame ?? [];
+    return command === "build"
+        ? await runBuild(root, only, values)
+        : await runValidate(root, only, values);
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (cause) {
+    // A PackagingError is something the author can act on; anything else is a bug
+    // in this tool and deserves its stack.
+    if (cause instanceof PackagingError) {
+        console.error(cause.message);
+    }
+    else {
+        console.error(cause);
+    }
+    process.exitCode = EXIT.failed;
+}

package/dist/cli/report.d.ts

@@ -0,0 +1,35 @@
+export type Severity = "error" | "warning";
+/**
+ * One thing wrong with one frame.
+ *
+ * Problems are collected rather than thrown so a single run tells an author
+ * everything that needs fixing, not just whatever failed first.
+ */
+export interface Problem {
+    severity: Severity;
+    /** Frame slug, when the problem belongs to a particular frame. */
+    frame?: string;
+    /** Path relative to the run root, POSIX separators. */
+    file?: string;
+    /** Property path inside the frame, e.g. `config.layouts.normal.boxes.art`. */
+    path?: string;
+    message: string;
+}
+/** Renders a problem as one line: `frame › path — message`. */
+export declare function formatProblem(problem: Problem): string;
+export declare class Reporter {
+    readonly problems: Problem[];
+    add(problem: Problem): void;
+    error(problem: Omit<Problem, "severity">): void;
+    warn(problem: Omit<Problem, "severity">): void;
+    get errors(): Problem[];
+    get warnings(): Problem[];
+    get ok(): boolean;
+    /** Human-readable lines for a terminal. */
+    toText(): string;
+    /** Workflow commands, one per problem. Empty outside GitHub Actions. */
+    toAnnotations(): string;
+    toMarkdown(): string;
+}
+/** True when running inside GitHub Actions, where annotations are understood. */
+export declare function inGitHubActions(): boolean;