@valancex/cli 0.12.0 → 0.14.0

package/dist/recording-guard.js

@@ -0,0 +1,28 @@
+// The three guards of a recording that holds user data (decision R16): the warning `vlx dev --record` gives when it starts, the flag a log must be given to be replayed or attached
+// (`--allow-user-data`), and the places a project keeps recordings out of its repository. A recording holds what a person typed and saw; a recorder that cannot keep a secret out says so every time.
+import { spawnSync } from "node:child_process";
+import { relative } from "node:path";
+/** True when `file` is in a git work tree of `root` and git does not ignore it. Nothing is said when `git` is not there or `root` is not a work tree. */
+const trackedByMistake = (root, file) => {
+    const inside = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, encoding: "utf8" });
+    if (inside.status !== 0) {
+        return false;
+    }
+    return spawnSync("git", ["check-ignore", "--quiet", file], { cwd: root }).status === 1;
+};
+/** The lines `vlx dev --record` prints before it records: where, what the log holds, what is redacted, and whether git would commit it. */
+export const recordingNotice = (root, file, config) => {
+    const redact = config.record.redact;
+    const shown = relative(root, file) || file;
+    const redacting = redact.scope.length > 0 || redact.commands.length > 0;
+    return [
+        `vlx dev --record: WARNING. This session is being written to ${shown}.`,
+        "  It holds what is typed and shown: names, passwords, anything on the page. It is for you, on this machine. Do not commit it, attach it to an issue or share it.",
+        redacting
+            ? `  Redacted (valance.json "record"): ${[...redact.scope.map((path) => path.join(".")), ...redact.commands].join(", ")}. Everything else is written as it is.`
+            : '  Nothing is redacted. Mark what must not be written in valance.json: { "record": { "redact": { "scope": [["password"]], "commands": ["login/type"] } } } (docs/use/replay.md).',
+        ...(trackedByMistake(root, file) ? [`  git does NOT ignore ${shown}: add it to .gitignore before you commit anything.`] : []),
+    ];
+};
+/** What `vlx replay` says when it is given a log that holds user data without being told it may read it. */
+export const userDataRefusal = (file) => `vlx replay: ${file} holds user data (its header says containsUserData). Replaying it prints what was typed and shown when a route differs; run it again with --allow-user-data when you mean to read it, and do not attach it anywhere.`;

package/dist/replay.d.ts

@@ -0,0 +1,15 @@
+import type { ReplaySetup } from "@valancex/valance/replay";
+/** Where `vlx dev --record` writes when it is not told: `.valance/sessions/<time>.jsonl`. */
+export declare const defaultRecording: (root: string, now?: Date) => string;
+/** The project's web program, compiled as `vlx build` would, with the hashes a log's header is checked against. */
+export declare const setupOf: (root: string) => Promise<ReplaySetup>;
+export interface ReplayRun {
+    readonly code: number;
+    readonly output: string;
+}
+/** Replays the log at `file` in the project at `root`. 0 when every route gave what the log recorded, 1 when one did not, 2 for a log or a route that cannot be read. */
+export declare const replayFile: (root: string, file: string, options?: {
+    readonly routes?: ReadonlyArray<string>;
+    readonly json?: boolean;
+    readonly allowUserData?: boolean;
+}) => Promise<ReplayRun>;

package/dist/replay.js

@@ -0,0 +1,59 @@
+// `vlx replay <log>`: plays a session log (recorded by `vlx dev --record`, or one of MESH's conformance logs) against the project's own templates, by the three routes of the equivalence law,
+// and says where the first differs from the log. It runs no command and reads no clock: a log is a bug report a machine can run. Development only.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { holdsUserData, parseLog, programHash, replay, ROUTES, sha256 } from "@valancex/valance/replay";
+import { userDataRefusal } from "./recording-guard.js";
+import { loadAuthor } from "./author.js";
+import { loadConfig } from "./config.js";
+import { generateContent, generateProgram, programFile } from "./emit.js";
+import { generated } from "./project.js";
+import { createLoader } from "./vite.js";
+/** Where `vlx dev --record` writes when it is not told: `.valance/sessions/<time>.jsonl`. */
+export const defaultRecording = (root, now = new Date()) => join(root, ".valance", "sessions", `${now.toISOString().replace(/[:.]/g, "-")}.jsonl`);
+/** The project's web program, compiled as `vlx build` would, with the hashes a log's header is checked against. */
+export const setupOf = async (root) => {
+    const config = await loadConfig(root);
+    await generateContent(root, config);
+    const server = await createLoader(root, config);
+    try {
+        await generateProgram(root, await loadAuthor(server, root), config, ["web"]);
+    }
+    finally {
+        await server.close();
+    }
+    const program = JSON.parse(readFileSync(generated(root, programFile(config, "web")), "utf8"));
+    const model = typeof program.model === "string" ? program.model : JSON.stringify(program.model);
+    return { program: { root: program.root, templates: program.templates }, model, hashes: { program: await programHash(program.templates), manifest: await sha256(model) } };
+};
+const describe = (result) => result.routes.map((route) => route.ok
+    ? `  ${route.route}: ${route.hashes.length} trees as recorded`
+    : `  ${route.route}: line ${route.divergence.line}, ${route.divergence.kind}: the log has ${JSON.stringify(route.divergence.expected)}, this gave ${JSON.stringify(route.divergence.actual)}`);
+/** Replays the log at `file` in the project at `root`. 0 when every route gave what the log recorded, 1 when one did not, 2 for a log or a route that cannot be read. */
+export const replayFile = async (root, file, options) => {
+    if (!existsSync(file)) {
+        return { code: 2, output: `vlx replay: ${file} is not a file` };
+    }
+    const routes = (options?.routes ?? ROUTES).filter((each) => ROUTES.includes(each));
+    if (routes.length === 0 || routes.length !== (options?.routes ?? ROUTES).length) {
+        return { code: 2, output: `vlx replay: --route is one or more of ${ROUTES.join(", ")}` };
+    }
+    let lines;
+    try {
+        lines = parseLog(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return { code: 2, output: `vlx replay: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (holdsUserData(lines) && options?.allowUserData !== true) {
+        return { code: 2, output: userDataRefusal(file) };
+    }
+    const result = await replay(lines, await setupOf(root), { routes });
+    if (options?.json === true) {
+        return { code: result.ok && result.agree ? 0 : 1, output: JSON.stringify({ file, ...result }) };
+    }
+    const header = `vlx replay: ${file}: ${lines.length} lines, ${result.trees} trees`;
+    return result.ok && result.agree
+        ? { code: 0, output: `${header}\n${describe(result).join("\n")}\nevery route gave the recorded trees${routes.length > 1 ? " and the routes agree" : ""}` }
+        : { code: 1, output: `${header}\n${describe(result).join("\n")}\n${result.ok ? "the routes gave different trees from one another" : "a route differs from the log"}` };
+};

package/dist/rules.d.ts

@@ -0,0 +1,23 @@
+import type { Template } from "@valancex/mesh-compiler";
+import type { WebVocabulary } from "@valancex/common/internal";
+import type { Diagnostic } from "./diagnostics.js";
+type Rules = NonNullable<WebVocabulary["rules"]>;
+/**
+ * The diagnostics for one template, written in `file`. `known` are the primitives' tags. `forwarded` is the prop its component declares as its name (`component(template, { name })`): the name of a
+ * control in it then arrives from whoever uses the component, so a control with none of its own is not reported, and the template must read the prop.
+ */
+export declare const checkTemplate: (file: string, source: string, template: Template, rules: Rules, known: ReadonlySet<string>, forwarded?: string) => ReadonlyArray<Diagnostic>;
+/** One template, as the reference check reads it: where it is written, its compiled form, and whether it is the package's own (a built-in view). */
+export interface Written {
+    readonly file: string;
+    readonly source: string;
+    readonly template: Template;
+    readonly builtIn: boolean;
+}
+/**
+ * `unknown-ref`: a `describedby` that is a literal names an `id` that nothing in the program has. The program is every template of the target, and the headings of the content (the built-in views
+ * give each its anchor as its `id`). An `id` that the author's own template computes could be any text, so the check says nothing then. It reads the program, not one template, because an id is
+ * global to the page: the layout may hold the control and a page the text it points at.
+ */
+export declare const checkReferences: (written: ReadonlyArray<Written>, anchors: ReadonlySet<string>) => ReadonlyArray<Diagnostic>;
+export {};

package/dist/rules.js

@@ -0,0 +1,123 @@
+import { diagnostic } from "./diagnostics.js";
+/** The program's own constructs (`mesh-if`, `mesh-each`): they draw their children where they stand, so they are not part of the structure the rules judge. */
+const transparent = (name) => name.startsWith("mesh-");
+const placeOf = (source, offset) => {
+    const before = source.slice(0, offset).split("\n");
+    return { line: before.length, column: (before.at(-1)?.length ?? 0) + 1 };
+};
+/** Whether an expression reads the name `name` from the scope. */
+const reads = (expression, name) => {
+    switch (expression.kind) {
+        case "scope":
+            return expression.name === name;
+        case "member":
+            return reads(expression.object, name);
+        case "unary":
+        case "has":
+            return reads(expression.operand, name);
+        case "binary":
+            return reads(expression.left, name) || reads(expression.right, name);
+        case "conditional":
+            return reads(expression.condition, name) || reads(expression.consequent, name) || reads(expression.alternate, name);
+        case "list":
+            return expression.elements.some((each) => reads(each, name));
+        case "record":
+            return expression.fields.some((each) => reads(each.value, name));
+        default:
+            return false;
+    }
+};
+const elementReads = (element, name) => element.props.some((each) => reads(each.value, name)) ||
+    element.events.some((each) => each.arguments.some((argument) => reads(argument, name))) ||
+    element.children.some((child) => (child.kind === "expression" ? reads(child.expression, name) : child.kind === "element" && elementReads(child.element, name)));
+/**
+ * The diagnostics for one template, written in `file`. `known` are the primitives' tags. `forwarded` is the prop its component declares as its name (`component(template, { name })`): the name of a
+ * control in it then arrives from whoever uses the component, so a control with none of its own is not reported, and the template must read the prop.
+ */
+export const checkTemplate = (file, source, template, rules, known, forwarded) => {
+    const found = [];
+    const report = (element, code, message) => {
+        const at = placeOf(source, element.span.start.utf16);
+        found.push(diagnostic(file, at.line, code, message, at.column));
+    };
+    const visit = (element, ancestors) => {
+        const tag = element.component;
+        const structural = ancestors.filter((each) => !transparent(each));
+        if (forwarded === undefined && rules.named.includes(tag) && !element.props.some((each) => each.prop === "label") && !structural.includes("label")) {
+            report(element, "unnamed-control", `<${tag}> has no accessible name: give it a \`label\`, or put it inside a <label> that says what it is for. In a component that takes its name from whoever uses it, declare the prop as the name (\`component(template, { props: { label: Schema.String }, name: "label" })\`) and write it here`);
+        }
+        // one modal layer at a time (decision I29)
+        const outer = rules.modal?.includes(tag) === true ? [...structural].reverse().find((each) => rules.modal?.includes(each) === true) : undefined;
+        if (outer !== undefined) {
+            report(element, "nested-modal", `<${tag}> is a modal layer inside <${outer}>, another modal layer: a dialog inside a dialog is not supported, so open one at a time or put them side by side`);
+        }
+        const parent = structural.at(-1);
+        const containers = rules.within[tag];
+        if (containers !== undefined && parent !== undefined && known.has(parent) && !containers.includes(parent) && !(parent === "label")) {
+            report(element, "outside-container", `<${tag}> belongs inside ${containers.map((each) => `<${each}>`).join(" or ")}, not <${parent}>`);
+        }
+        const only = rules.only[tag];
+        for (const child of element.children) {
+            if (only !== undefined) {
+                reportChild(element, child, only);
+            }
+            if (child.kind === "element") {
+                visit(child.element, [...ancestors, tag]);
+            }
+        }
+    };
+    const reportChild = (parent, child, only) => {
+        if (child.kind === "text" && child.value.trim() !== "") {
+            report(parent, "list-child", `<${parent.component}> holds only ${only.map((each) => `<${each}>`).join(" or ")}; it has the text "${child.value.trim().slice(0, 20)}"`);
+        }
+        else if (child.kind === "element" && known.has(child.element.component) && !transparent(child.element.component) && !only.includes(child.element.component)) {
+            report(child.element, "list-child", `<${parent.component}> holds only ${only.map((each) => `<${each}>`).join(" or ")}, not <${child.element.component}>`);
+        }
+    };
+    visit(template.root, []);
+    if (forwarded !== undefined && !elementReads(template.root, forwarded)) {
+        report(template.root, "name-unused", `the component declares \`${forwarded}\` as its name, but its template never reads \`${forwarded}\`: the name of whoever uses it would go nowhere`);
+    }
+    return found;
+};
+const literal = (expression) => (expression.kind === "literal" && typeof expression.value === "string" ? expression.value : undefined);
+const elementsOf = (element) => [
+    element,
+    ...element.children.flatMap((child) => (child.kind === "element" ? elementsOf(child.element) : [])),
+];
+/**
+ * `unknown-ref`: a `describedby` that is a literal names an `id` that nothing in the program has. The program is every template of the target, and the headings of the content (the built-in views
+ * give each its anchor as its `id`). An `id` that the author's own template computes could be any text, so the check says nothing then. It reads the program, not one template, because an id is
+ * global to the page: the layout may hold the control and a page the text it points at.
+ */
+export const checkReferences = (written, anchors) => {
+    const ids = new Set(anchors);
+    let computed = false;
+    const references = [];
+    for (const { file, source, template, builtIn } of written) {
+        for (const element of elementsOf(template.root)) {
+            for (const prop of element.props) {
+                const value = literal(prop.value);
+                if (prop.prop === "id") {
+                    if (value !== undefined) {
+                        ids.add(value);
+                    }
+                    else if (!builtIn) {
+                        computed = true;
+                    }
+                }
+                else if (prop.prop === "describedby" && value !== undefined) {
+                    references.push({ file, source, element, id: value });
+                }
+            }
+        }
+    }
+    return computed
+        ? []
+        : references
+            .filter((each) => !ids.has(each.id))
+            .map((each) => {
+            const at = placeOf(each.source, each.element.span.start.utf16);
+            return diagnostic(each.file, at.line, "unknown-ref", `<${each.element.component}> is described by "${each.id}", and no element in the program has that id`, at.column);
+        });
+};

package/dist/runtime-guard.d.ts

@@ -0,0 +1,11 @@
+export interface Copy {
+    /** The copy's directory, resolved through links. */
+    readonly dir: string;
+    readonly version: string;
+    /** The packages that resolve to it. */
+    readonly usedBy: ReadonlyArray<string>;
+}
+/** The copies of the runtime that the project's packages resolve, each with the packages that use it. */
+export declare const runtimeCopies: (root: string) => ReadonlyArray<Copy>;
+/** Throws `runtime-duplicate`, naming every copy and who uses it, when the build would bundle more than one. */
+export declare const assertOneRuntime: (root: string) => void;

package/dist/runtime-guard.js

@@ -0,0 +1,62 @@
+// A production build bundles the MESH runtime's WebAssembly module once for each copy of `@valancex/mesh-runtime` the packages resolve, and the browser fetches every one (decision W20: a plain
+// install of the published set resolved two, 0.12.0 through `@valancex/valance` and 0.11.0 through `@valancex/common`, and shipped 171 KB of brotli twice). `vlx build` therefore refuses to build
+// when more than one copy is in play, naming each. `vlx dev` does not look: development says nothing about size (decision W9).
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { AppError } from "./diagnostics.js";
+const RUNTIME = "@valancex/mesh-runtime";
+/** The packages whose code imports the runtime, or is imported by one that does. */
+const IMPORTERS = ["@valancex/common", "@valancex/valance", "@valancex/nexus", "@valancex/port-web", "@valancex/router"];
+/** The directory of `name` as Node would find it from `from`: the nearest `node_modules/<name>` going up, resolved through links. */
+const find = (from, name) => {
+    for (let dir = from;; dir = dirname(dir)) {
+        const candidate = join(dir, "node_modules", name);
+        if (existsSync(join(candidate, "package.json"))) {
+            return realpathSync(candidate);
+        }
+        if (dirname(dir) === dir) {
+            return undefined;
+        }
+    }
+};
+/** The copies of the runtime that the project's packages resolve, each with the packages that use it. */
+export const runtimeCopies = (root) => {
+    const copies = new Map();
+    for (const name of IMPORTERS) {
+        // From the project first; a package the project does not list directly is found through one it does (pnpm links only the direct ones).
+        const importer = find(root, name) ??
+            IMPORTERS.map((other) => find(root, other))
+                .flatMap((dir) => (dir === undefined ? [] : [find(dir, name)]))
+                .find((dir) => dir !== undefined);
+        const dir = importer === undefined ? undefined : find(importer, RUNTIME);
+        if (dir === undefined) {
+            continue;
+        }
+        const entry = copies.get(dir) ?? { version: JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version, usedBy: [] };
+        entry.usedBy.push(name);
+        copies.set(dir, entry);
+    }
+    return [...copies].map(([dir, { version, usedBy }]) => ({ dir, version, usedBy }));
+};
+/** Throws `runtime-duplicate`, naming every copy and who uses it, when the build would bundle more than one. */
+export const assertOneRuntime = (root) => {
+    const copies = runtimeCopies(root);
+    if (copies.length < 2) {
+        return;
+    }
+    const newest = copies
+        .map((copy) => copy.version)
+        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+        .at(-1);
+    const listed = copies.map((copy) => `${copy.version} at ${relative(root, copy.dir) || "."} (used by ${copy.usedBy.join(", ")})`).join("; ");
+    throw new AppError([
+        {
+            file: "package.json",
+            line: 0,
+            column: 0,
+            code: "runtime-duplicate",
+            message: `${copies.length} copies of ${RUNTIME} would be built into the site, and the browser would fetch the WebAssembly runtime ${copies.length} times: ${listed}. ` +
+                `Make them one version: add "overrides": { "${RUNTIME}": "${newest}" } to package.json (npm; pnpm.overrides with pnpm, resolutions with yarn) and install again`,
+        },
+    ]);
+};

package/dist/security.d.ts

@@ -1,4 +1,6 @@
 import type { Config } from "./config.js";
+/** The CSP source that allows the early-input shell (the same bytes in every page) and nothing else inline: a hash, not `'unsafe-inline'`. */
+export declare const earlyShellSource: () => string;
 export declare const contentSecurityPolicy: (config: Config) => string;
 /** The header lines, for every path under the site's base. */
 export declare const headersFile: (config: Config) => string;

package/dist/security.js

@@ -1,3 +1,10 @@
+// The security headers a built site should be served with, written beside it as `_headers` (the format Netlify and Cloudflare Pages read; other hosts take the same lines). The VALANCE
+// browser runtime is WebAssembly, so a strict Content-Security-Policy needs `'wasm-unsafe-eval'` in `script-src` and nothing more permissive: no `'unsafe-inline'`, no `'unsafe-eval'`. Without it
+// the page's server HTML stays and the application never starts (measured in Chromium). Everything the build writes is a same-origin file, so every other source is `'self'`.
+import { createHash } from "node:crypto";
+import { earlyShell } from "@valancex/common/internal";
+/** The CSP source that allows the early-input shell (the same bytes in every page) and nothing else inline: a hash, not `'unsafe-inline'`. */
+export const earlyShellSource = () => `'sha256-${createHash("sha256").update(earlyShell).digest("base64")}'`;
 /** The origin of the backend when `api.base` is an absolute address (the page may connect to it), else nothing: a path is the page's own origin. */
 const apiOrigin = (config) => {
     try {
@@ -11,7 +18,7 @@ export const contentSecurityPolicy = (config) => {
     const origin = apiOrigin(config);
     return [
         "default-src 'self'",
-        "script-src 'self' 'wasm-unsafe-eval'",
+        `script-src 'self' 'wasm-unsafe-eval' ${earlyShellSource()}`,
         "style-src 'self'",
         "img-src 'self' data:",
         `connect-src 'self'${origin === undefined ? "" : ` ${origin}`}`,

package/dist/size.d.ts

@@ -0,0 +1,54 @@
+import { AppError } from "./diagnostics.js";
+export type FileKind = "javascript" | "css" | "wasm" | "other";
+export interface SizedFile {
+    readonly file: string;
+    readonly kind: FileKind;
+    readonly raw: number;
+    readonly brotli: number;
+}
+export interface SetReport {
+    readonly files: ReadonlyArray<SizedFile>;
+    readonly brotli: number;
+}
+export interface SizeReport {
+    readonly startup: SetReport;
+    readonly afterStart: SetReport;
+}
+/** What the Vite manifest says about one output file. */
+export interface ManifestEntry {
+    readonly file: string;
+    readonly isEntry?: boolean;
+    readonly imports?: ReadonlyArray<string>;
+    readonly dynamicImports?: ReadonlyArray<string>;
+    readonly css?: ReadonlyArray<string>;
+    readonly assets?: ReadonlyArray<string>;
+}
+/** Splits the build in `dist` into the start-up and after-start sets, from the bundler's manifest. The WebAssembly runtime is in the start-up set whenever the entry names it. */
+export declare const measure: (dist: string, manifest: Readonly<Record<string, ManifestEntry>>, wasm?: string) => SizeReport;
+/** What a budget measures. */
+export type BudgetType = "initial" | "runtime" | "startup" | "afterStart" | "anyChunk";
+/** A budget in the shape Angular's are: a type and a warning and an error threshold, each in bytes (`500000`, `"500kB"`, `"1MB"`; 1 kB is 1,000 bytes). */
+export interface Budget {
+    readonly type: BudgetType;
+    readonly warning?: string | number;
+    readonly error?: string | number;
+}
+export interface BudgetResult {
+    readonly type: BudgetType;
+    readonly measured: number;
+    readonly warning?: number;
+    readonly error?: number;
+    readonly status: "ok" | "warning" | "error";
+}
+export declare const BUDGET_TYPES: ReadonlyArray<BudgetType>;
+export declare const DEFAULT_BUDGETS: ReadonlyArray<Budget>;
+/** `"500kB"` or `500000` as bytes, or `undefined` if it is neither. */
+export declare const bytesOf: (value: string | number) => number | undefined;
+/** Holds `report` to `budgets` (a project's, else the framework's). A threshold that is not a size is a mistake in the settings, said with the file. */
+export declare const check: (report: SizeReport, budgets: ReadonlyArray<Budget>) => ReadonlyArray<BudgetResult>;
+/** The settings problems of a project's `budgets`: a type that is not one, a threshold that is not a size, a warning above its error. */
+export declare const budgetProblems: (value: unknown) => string | undefined;
+/** The size report a production build prints: both sets with each file, then each budget. */
+export declare const lines: (report: SizeReport, results: ReadonlyArray<BudgetResult>) => ReadonlyArray<string>;
+/** The failure of a build whose measured size is over an error threshold. */
+export declare const failure: (results: ReadonlyArray<BudgetResult>) => AppError | undefined;

package/dist/size.js

@@ -0,0 +1,153 @@
+// What `vlx build` ships, measured, and the budgets it is held to (Bet 3; decisions W9, W10, W14). A production build prints this; `vlx dev` never does (W9: development is quiet and fast).
+//
+// A build's files fall in two sets (W11, W12): the **start-up set** is what the page cannot start without (the entry chunk, the chunks it statically imports, their styles, and the WebAssembly runtime),
+// and the **after-start set** is every chunk only a dynamic `import()` reaches (loaded once the application has started, at low priority). The server's HTML and the styles the document names paint
+// first and are in the start-up set's styles. Sizes are brotli bytes, which is what travels (W2); the raw size is shown beside them.
+import { brotliCompressSync } from "node:zlib";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AppError, diagnostic } from "./diagnostics.js";
+const kindOf = (file) => file.endsWith(".js") || file.endsWith(".mjs") ? "javascript" : file.endsWith(".css") ? "css" : file.endsWith(".wasm") ? "wasm" : "other";
+const sized = (dist, file) => {
+    const bytes = readFileSync(join(dist, file));
+    return { file, kind: kindOf(file), raw: bytes.length, brotli: brotliCompressSync(bytes).length };
+};
+/** The files reachable from `starts` by the manifest's static `imports` (and their styles), or by `dynamicImports` only. */
+const reach = (manifest, starts) => {
+    const seen = new Set();
+    const files = new Set();
+    const visit = (key) => {
+        const entry = manifest[key];
+        if (entry === undefined || seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        files.add(entry.file);
+        entry.css?.forEach((file) => files.add(file));
+        entry.assets?.forEach((file) => files.add(file));
+        entry.imports?.forEach(visit);
+    };
+    starts.forEach(visit);
+    return [...files];
+};
+/** Splits the build in `dist` into the start-up and after-start sets, from the bundler's manifest. The WebAssembly runtime is in the start-up set whenever the entry names it. */
+export const measure = (dist, manifest, wasm) => {
+    const entries = Object.entries(manifest).filter(([, entry]) => entry.isEntry === true);
+    const startup = new Set(reach(manifest, entries.map(([key]) => key)));
+    if (wasm !== undefined) {
+        startup.add(wasm);
+    }
+    const dynamic = new Set();
+    for (const [, entry] of Object.entries(manifest)) {
+        if (startup.has(entry.file) || entry.isEntry === true) {
+            entry.dynamicImports?.forEach((key) => reach(manifest, [key]).forEach((file) => dynamic.add(file)));
+        }
+    }
+    for (const file of startup) {
+        dynamic.delete(file);
+    }
+    const set = (files) => {
+        const list = [...files].sort().map((file) => sized(dist, file));
+        return { files: list, brotli: list.reduce((sum, each) => sum + each.brotli, 0) };
+    };
+    return { startup: set(startup), afterStart: set(dynamic) };
+};
+export const BUDGET_TYPES = ["initial", "runtime", "startup", "afterStart", "anyChunk"];
+/** The framework's own start-up budgets (decision W14): what a project gets when it sets none. They are data (`budgets.json`, beside this file, copied next to the compiled code by `scripts/copy-data.mjs`), so a gate can read the same numbers. */
+const defaults = JSON.parse(readFileSync(new URL("./budgets.json", import.meta.url), "utf8"));
+export const DEFAULT_BUDGETS = defaults.project.budgets;
+/** `"500kB"` or `500000` as bytes, or `undefined` if it is neither. */
+export const bytesOf = (value) => {
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+    const match = /^(\d+(?:\.\d+)?)\s*(B|kB|KB|MB)?$/.exec(value.trim());
+    return match === null ? undefined : Math.round(Number(match[1]) * ({ B: 1, kB: 1000, KB: 1000, MB: 1_000_000 }[match[2] ?? "B"] ?? 1));
+};
+const measuredFor = (type, report) => {
+    const startup = report.startup.files;
+    const sum = (files, kinds) => files.filter((each) => kinds.includes(each.kind)).reduce((total, each) => total + each.brotli, 0);
+    switch (type) {
+        case "initial":
+            return sum(startup, ["javascript", "css"]);
+        case "runtime":
+            return sum(startup, ["wasm"]);
+        case "startup":
+            return report.startup.brotli;
+        case "afterStart":
+            return report.afterStart.brotli;
+        case "anyChunk":
+            return Math.max(0, ...[...startup, ...report.afterStart.files].filter((each) => each.kind === "javascript").map((each) => each.brotli));
+    }
+};
+/** Holds `report` to `budgets` (a project's, else the framework's). A threshold that is not a size is a mistake in the settings, said with the file. */
+export const check = (report, budgets) => budgets.map((budget) => {
+    const warning = budget.warning === undefined ? undefined : bytesOf(budget.warning);
+    const error = budget.error === undefined ? undefined : bytesOf(budget.error);
+    const measured = measuredFor(budget.type, report);
+    return {
+        type: budget.type,
+        measured,
+        ...(warning === undefined ? {} : { warning }),
+        ...(error === undefined ? {} : { error }),
+        status: error !== undefined && measured > error ? "error" : warning !== undefined && measured > warning ? "warning" : "ok",
+    };
+});
+/** The settings problems of a project's `budgets`: a type that is not one, a threshold that is not a size, a warning above its error. */
+export const budgetProblems = (value) => {
+    if (!Array.isArray(value)) {
+        return 'must be a list such as [{ "type": "initial", "warning": "200kB", "error": "400kB" }]';
+    }
+    for (const [index, each] of value.entries()) {
+        const budget = each;
+        if (typeof budget !== "object" || budget === null || !BUDGET_TYPES.includes(budget.type)) {
+            return `[${index}] needs a "type" of ${BUDGET_TYPES.join(", ")}`;
+        }
+        const extra = Object.keys(budget).filter((key) => !["type", "warning", "error"].includes(key));
+        if (extra.length > 0) {
+            return `[${index}] has unknown settings ${extra.map((key) => `"${key}"`).join(", ")} (known: type, warning, error)`;
+        }
+        for (const key of ["warning", "error"]) {
+            const given = budget[key];
+            if (given !== undefined && (typeof given !== "string" && typeof given !== "number" ? true : bytesOf(given) === undefined)) {
+                return `[${index}] "${key}" must be a size such as 500000, "500kB" or "1MB"`;
+            }
+        }
+        const warning = budget.warning === undefined ? undefined : bytesOf(budget.warning);
+        const error = budget.error === undefined ? undefined : bytesOf(budget.error);
+        if (warning !== undefined && error !== undefined && warning > error) {
+            return `[${index}] the warning (${warning}) is above the error (${error})`;
+        }
+    }
+    return undefined;
+};
+const label = {
+    initial: "start-up JavaScript and CSS",
+    runtime: "WebAssembly runtime",
+    startup: "start-up set",
+    afterStart: "after-start set",
+    anyChunk: "largest JavaScript chunk",
+};
+const kB = (bytes) => `${(bytes / 1000).toFixed(1)} kB`;
+/** The size report a production build prints: both sets with each file, then each budget. */
+export const lines = (report, results) => {
+    const set = (name, each) => [
+        `  ${name}: ${kB(each.brotli)} brotli`,
+        ...each.files.map((file) => `    ${file.file}  ${kB(file.raw)} raw, ${kB(file.brotli)} brotli`),
+    ];
+    return [
+        "Size report (brotli, what travels):",
+        ...set("start-up (what the page cannot start without)", report.startup),
+        ...(report.afterStart.files.length === 0
+            ? ["  after-start: nothing (no chunk is loaded after the application has started)"]
+            : set("after-start (loaded once the application is running)", report.afterStart)),
+        ...results.map((each) => `  ${each.status === "ok" ? "ok     " : each.status === "warning" ? "WARNING" : "ERROR  "} ${label[each.type]}: ${kB(each.measured)}${each.error === undefined ? "" : ` (error above ${kB(each.error)})`}${each.warning === undefined ? "" : ` (warning above ${kB(each.warning)})`}`),
+    ];
+};
+/** The failure of a build whose measured size is over an error threshold. */
+export const failure = (results) => {
+    const over = results.filter((each) => each.status === "error");
+    return over.length === 0
+        ? undefined
+        : new AppError(over.map((each) => diagnostic("valance.json", 0, "budget-exceeded", `the ${label[each.type]} is ${kB(each.measured)}, over the error budget of ${kB(each.error)}. Make it smaller, or raise the "budgets" in valance.json for this project.`)));
+};

package/dist/targets.d.ts

@@ -1,12 +1,17 @@
 import type { Vocabulary } from "@valancex/common/internal";
 export interface Target {
     /** The flag (`--web`) and the name in `valance.<id>.json`. */
-    readonly id: "web";
+    readonly id: "web" | "desktop";
     readonly label: string;
     readonly hint: string;
     /** The tags its templates may write. A project builds against its target's vocabulary. */
     readonly vocabulary: Vocabulary;
+    /** Where the framework's own templates for this target are (the layout and the views that draw a page's blocks): a project's own `layout` and `override`s replace them by name. */
+    readonly views: string;
 }
 export declare const TARGETS: ReadonlyArray<Target>;
+export declare const targetOf: (id: TargetId) => Target;
 export type TargetId = Target["id"];
 export declare const isTarget: (name: string) => name is TargetId;
+/** What `--yes` makes: the web alone is the one that needs nothing else installed. */
+export declare const DEFAULT_TARGETS: ReadonlyArray<TargetId>;

package/dist/targets.js

@@ -1,7 +1,29 @@
-// The targets an application can be developed for. Today there is one, the web; the wizard, `vlx init` and the flags are written against this list, so a target that arrives later is one more entry
-// here (and its template under `templates/`), not a change to them.
-import { webVocabulary } from "@valancex/common/internal";
+// The targets an application can be developed for: the web, and a desktop window. The wizard, `vlx init` and the flags are written against this list, so a target that arrives later is one more
+// entry here (and its template under `templates/`, its built-in views, its vocabulary), not a change to them.
+import { fromManifests, webVocabulary } from "@valancex/common/internal";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { BUILT_IN, BUILT_IN_DESKTOP } from "./compile.js";
+/**
+ * The Desktop PORT's vocabulary: its components as data (`vocabulary.json`: columns, rows, text, a button, a checkbox, a text field; `content.json`: what Markdown produces), read from the
+ * PORT's own package (`@valancex/port-desktop-vocabulary`), not from a copy kept here.
+ */
+const desktopVocabulary = () => {
+    const need = createRequire(import.meta.url);
+    const read = (name) => JSON.parse(readFileSync(need.resolve(`@valancex/port-desktop-vocabulary/${name}`), "utf8"));
+    return fromManifests("desktop", read("vocabulary.json"), read("content.json"));
+};
 export const TARGETS = [
-    { id: "web", label: "Web", hint: "a website: Markdown pages and templates, built to a static site (settings in valance.web.json)", vocabulary: webVocabulary },
+    { id: "web", label: "Web", hint: "a website: Markdown pages and templates, built to a static site (settings in valance.web.json)", vocabulary: webVocabulary, views: BUILT_IN },
+    {
+        id: "desktop",
+        label: "Desktop",
+        hint: "a native window on Linux and Windows: Markdown pages and templates, drawn by the Desktop PORT (settings in valance.desktop.json)",
+        vocabulary: desktopVocabulary(),
+        views: BUILT_IN_DESKTOP,
+    },
 ];
+export const targetOf = (id) => TARGETS.find((each) => each.id === id);
 export const isTarget = (name) => TARGETS.some((each) => each.id === name);
+/** What `--yes` makes: the web alone is the one that needs nothing else installed. */
+export const DEFAULT_TARGETS = ["web"];