@uniflowed/config 0.0.0-alpha.9 → 0.1.0

package/index.js

@@ -3,10 +3,21 @@
 // `@uniflowed/config`.
 
 export type {
+  BuilderSpec,
   CapabilityJsHost,
   CoverageThresholds,
+  DeployAdapter,
+  PackageManagerPreference,
+  PackageManagerSpec,
+  Permissions,
+  PluginEntry,
   RuleLevel,
+  RuntimeEngine,
+  RuntimeSpec,
+  SizeBudget,
+  TaskArgument,
   TaskDefinition,
+  TestRunnerSpec,
   UniflowedConfig,
 } from "./internal/schema.js";
 

package/internal/schema.js

@@ -2,9 +2,67 @@
 //
 // Owns the Flow shape of `uf.config.js`; `index.js` keeps the public package
 // entry point thin.
+//
+// # Every key uf reads, and nothing else
+//
+// The guide says a config file "is type-checked as Flow code", which is the
+// whole reason to write one in Flow. That makes an undeclared key worse than a
+// missing feature: `lint.files`, `lint.ignore` and `app.router.enabled` were
+// documented in the configuration reference, accepted by the runtime, and
+// absent from this type — so a project following the reference had to choose
+// between the documented key and a config that checks
+// (ubugeeei-prod/uf#481). They were not the only three.
+//
+// So the key *names* below are no longer a person's job to keep in step with
+// the loader. `crates/uf_config`'s `the_flow_schema_declares_every_key_uf_reads`
+// parses this file with uf's own Flow parser and compares the paths it declares
+// against the paths `uf_config::UniflowedConfig` serializes — in both
+// directions, because a key declared here and read by nothing is an option that
+// silently does nothing, which is the same defect wearing the other face.
+//
+// The value *types* are still this file's own judgement, and deliberately so.
+// A test over names cannot say whether `"biome" | "prettier" | "none"` is the
+// right set, and several keys below are narrower than what the loader will
+// parse — `orm.module` is `"@uniflowed/orm"` because there is one
+// implementation, where the loader takes any string. Where this package means
+// to be more opinionated than the parser, that is what these say.
+//
+// # What an editor shows
+//
+// `uf lsp` completes and explains `uf.config.js` from this file, compiled into
+// the binary. A key's completion shows the comment directly above the key and
+// the type as it is written here, and the members of a literal union are the
+// values it offers — so a comment above a key is written for somebody typing
+// that key. Either kind of comment counts above a key; above a type alias only
+// a `/** */` block does, because the `//` notes on the aliases are this file's
+// history rather than the key's meaning. `crates/uf_config/src/schema.rs` is
+// the reader, and says exactly what it takes.
 
 export type RuleLevel = "off" | "warn" | "error" | 0 | 1 | 2 | boolean;
 
+/**
+ * One argument a task takes, filled by `uf run <task>`.
+ *
+ * Given after the task's name, in the order declared, or as `--name value`; the
+ * values are appended to `command` in that order either way. At a terminal, a
+ * required argument that was not given is picked from `choices`, or typed; in
+ * CI and pipelines it is an error that names it.
+ */
+export type TaskArgument = {
+  // What `--name` and the picker call it: letters, digits, `-` and `_`.
+  readonly name: string,
+  // One line saying what it is for, shown in the picker.
+  readonly description?: string,
+  // The only values it may take. Anything else is refused, and at a terminal
+  // these are the list to pick from.
+  readonly choices?: $ReadOnlyArray<string>,
+  // Used when it is not given. An argument with a default is never asked for.
+  readonly default?: string,
+  // Whether leaving it out is an error. Defaults to `true` unless there is a
+  // `default`; an optional argument with no default must come last.
+  readonly required?: boolean,
+};
+
 export type TaskDefinition =
   | string
   | {
@@ -12,10 +70,260 @@ export type TaskDefinition =
       readonly cwd?: string,
       readonly dependsOn?: $ReadOnlyArray<string>,
       readonly env?: { readonly [string]: string },
+      // Everything the task reads, as paths or globs from the project root; a
+      // pattern beginning `!` excludes. This is the whole of the cache key, so
+      // a task that lists nothing is never cached and always runs.
+      readonly inputs?: $ReadOnlyArray<string>,
+      // Everything it writes. Checked rather than restored: a replayed result
+      // has to still have its files on disk, unchanged.
+      readonly outputs?: $ReadOnlyArray<string>,
+      // `false` keeps a task with declared inputs out of the cache.
+      readonly cache?: boolean,
+      // The arguments `uf run` fills, in the order they are appended to
+      // `command`.
+      readonly args?: $ReadOnlyArray<TaskArgument>,
     };
 
 export type CapabilityJsHost = "node" | "deno" | "bun";
 
+/**
+ * The package manager uf drives, overriding what it infers from the project.
+ *
+ * `"auto"` reads the project itself: an explicit `"packageManager"` field, then
+ * a lockfile, then the nearest workspace root, then uf's own resolver.
+ */
+// The eight below are the *names a project may pin*, not commands this module
+// runs: `@uniflowed/config` declares a type and executes nothing at all.
+// `uniflowed/no-npm-script-invocation` is a line scanner, and a string whose
+// entire contents is `pnpm` reads exactly like the `spawn("pnpm", […])` the
+// rule exists to catch — `crates/uf_lint/src/scan/search.rs` says so in its own
+// documentation and calls what is left "rare and suppressible". This is that
+// residue, and there is no spelling of these values that is not one of them.
+// uf-lint-disable uniflowed/no-npm-script-invocation
+export type PackageManagerPreference =
+  | "auto"
+  | "uf"
+  | "npm"
+  | "pnpm"
+  | "yarn"
+  | "yarn-classic"
+  | "yarn-berry"
+  | "bun";
+// uf-lint-enable uniflowed/no-npm-script-invocation
+
+// The runtimes a project may say it is written for, which are the runtimes uf
+// has a host for. It read `"uf" | ... | "edge" | "serverless" | "container"`,
+// and those four are rows `uf_runtime::HOSTS` grades planned with no Flow
+// loader — so a project that named one could not import its own first file
+// there, and every command went on running on Node anyway. uf refuses them at
+// the key that named them now; this type is where a reader finds that out
+// before `uf check` does. See docs/hosts.md and ubugeeei-prod/uf#246.
+//
+// A deployment target is `DeployAdapter`, on `app.runtime.deploy`, and is a
+// different question with a longer list.
+export type RuntimeEngine = "node" | "deno" | "bun";
+
+export type DeployAdapter =
+  | "node"
+  | "bun"
+  | "deno"
+  | "edge"
+  | "serverless"
+  | "static"
+  | "container";
+
+// # Tools, declared where they are used
+//
+// The four aliases below are strings to Flow and a grammar to uf, which reads
+// every one of them where the config is read and refuses what it cannot run —
+// naming the key, what was written, and what to write instead. They are
+// aliases rather than bare `string` so the grammar has one place to be written
+// down, and so an editor can find a tool-spec key by its type — which is what
+// completion in `uf.config.js` keys on (ubugeeei-prod/uf#941). Rename one and
+// that stops working without a type error anywhere.
+//
+// A spec is `name[@version]`, and what follows the `@` is one of three things:
+//
+//   * nothing — `"node"` — the `node` on `PATH`, which is what every project
+//     got before it could say anything else;
+//   * a numeric prefix — `"node@26"`, `"bun@1.4"` — the newest release that
+//     starts with it, resolved once against the publisher's index and locked in
+//     `uf.lock`, so every machine runs the same release until somebody moves it;
+//   * a full version — `"pnpm@12.0.0"` — exactly that release.
+//
+// A range — `"node@^26"`, `"node@>=24"`, `"node@24.x"` — is refused: a range is
+// not an environment, because it can resolve to a different release tomorrow.
+// So is a tag such as `"node@lts"`, for the same reason. ubugeeei-prod/uf#940.
+
+/**
+ * A JavaScript runtime, and optionally which release of it: `"node"`,
+ * `"node@26"`, `"bun@1.3.5"`.
+ *
+ * The names are `node`, `bun` and `deno`. No version is the one on `PATH`; a
+ * prefix is the newest release that starts with it, locked in `uf.lock`; a full
+ * version is exactly that release. A range or a tag is refused.
+ *
+ * The type of `runtime`, `build.runtime` and `test.runtime`.
+ */
+export type RuntimeSpec = string;
+
+/**
+ * A package manager, and optionally which release of it: `"pnpm"`,
+ * `"pnpm@10"`, `"pnpm@12.0.0"`.
+ *
+ * The names are `npm`, `pnpm`, `yarn` and `bun`. Yarn's edition is its major
+ * version — `"yarn@1"` is Classic. No version is the one on `PATH`; a prefix is
+ * the newest release that starts with it, locked in `uf.lock`; a full version
+ * is exactly that release. A range or a tag is refused.
+ *
+ * The type of `packageManager`.
+ */
+export type PackageManagerSpec = string;
+
+/**
+ * What runs the test suite: `"uf"` or `"bun[@version]"`.
+ *
+ * `"uf"` is the runner built into uf, and the default; it takes no version,
+ * because it is the binary that is running. `"bun"` is `bun test`, on the Bun
+ * it names — so it also decides the test runtime when `test.runtime` is
+ * absent, and a `test.runtime` naming anything else is an error. The version
+ * follows the same grammar as a runtime's. Under a Bun runner `uf test` hands
+ * the files its discovery found to `bun test`, with uf's Flow preload, and
+ * `@uniflowed/test` resolves to `bun:test`; what Bun has no equivalent for
+ * raises `UnsupportedError` by name. See guide/testing, "Choosing a runner".
+ *
+ * The type of `test.runner`.
+ */
+export type TestRunnerSpec = string;
+
+/**
+ * Which builder `uf dev`, `uf build`, `uf preview` and `uf start` drive:
+ * `"vite"`, or a module specifier.
+ *
+ * `"vite"` is `@uniflowed/vite`, the builder uf ships and the default. Any other
+ * string is a module specifier — a package found up `node_modules`, or a path
+ * starting with `.` or `/` that must stay inside the project — whose driver
+ * satisfies the contract in docs/architecture.md.
+ *
+ * The type of `build.builder`.
+ */
+export type BuilderSpec = string;
+
+/**
+ * One entry of `plugins: [...]`.
+ *
+ * A bare name takes the default band and applies to every pipeline; the long
+ * form says otherwise. Declaration order decides within a band, so the
+ * resolved pipeline is a function of this file alone.
+ */
+export type PluginEntry =
+  | string
+  | {
+      readonly name: string,
+      readonly order?: "pre" | "normal" | "post",
+      readonly apply?: "build" | "serve" | "always",
+    };
+
+// # `app.router`'s three lists
+//
+// Next.js's `redirects`, `rewrites` and `headers`, written as data rather than
+// as async functions, because this file is read without being run. A `source`
+// is a path in the route table's own grammar — a literal segment, `:name` for
+// one segment, and a trailing `:name*` for the rest — and each rule is an exact
+// object, so a misspelled field is an error here and where `uf` reads the file.
+
+/**
+ * One redirect: a request for `source` is answered with a redirect to
+ * `destination`, before anything else answers — a file included.
+ *
+ * `destination` is a path of this application or an absolute `http(s)` URL,
+ * and may use the `:name` and `:name*` segments `source` declared. The
+ * request's query is passed through. `permanent: true` is a `308`, `false` a
+ * `307`; both keep the method.
+ */
+export type RouteRedirect = {
+  readonly source: string,
+  readonly destination: string,
+  readonly permanent: boolean,
+};
+
+/**
+ * One rewrite: a request for `source` is answered by the route at
+ * `destination`, and the address bar keeps `source`.
+ *
+ * `destination` is a path of this application — never another origin, which
+ * is a route handler that fetches — and may use `source`'s segments. Applied
+ * after the build's own files and before middleware, so the middleware that
+ * runs is the destination's.
+ */
+export type RouteRewrite = {
+  readonly source: string,
+  readonly destination: string,
+};
+
+/**
+ * Response headers for every request whose path matches `source`, files
+ * included. Every matching rule applies, in order, and a later one setting the
+ * same name wins — over the response's own header of that name, too.
+ */
+export type RouteHeaders = {
+  readonly source: string,
+  readonly headers: { readonly [name: string]: string },
+};
+
+/**
+ * Which spelling of a path is the page.
+ *
+ * `"never"` answers `/about/` with a `308` to `/about` and writes the page as
+ * `about.html`; `"always"` answers `/about` with a `308` to `/about/` and
+ * writes `about/index.html`; `"ignore"`, the default, answers both and writes
+ * `about/index.html`. `next.config.js`'s `trailingSlash: false`, `true` and
+ * `skipTrailingSlashRedirect: true`.
+ */
+export type RouterTrailingSlash = "never" | "always" | "ignore";
+
+/**
+ * A ceiling `uf build` fails over, and what it is measured on.
+ *
+ * `max` accepts a byte count or a size a person would write — `"180kb"` —
+ * because a budget is written by hand and read back by a report.
+ */
+export type SizeBudget = {
+  readonly max: number | string,
+  readonly metric?: "raw" | "gzip" | "brotli",
+};
+
+/**
+ * What the project's own code may reach.
+ *
+ * Absent from `uf.config.js` means no permission model: the toolchain starts
+ * its host the way it always has. Present means **deny by default** — the
+ * project's code gets what is listed and nothing else — and `permissions: {}`
+ * is a legitimate thing to write, meaning "nothing beyond what uf itself needs
+ * to load and transform the project". There is deliberately no way to spell
+ * "everything"; a project that wants everything does not declare a set.
+ *
+ * Every field is a list of literal strings, because `uf.config.js` is read as
+ * text and parsed as JSON5 rather than executed: a computed path or a
+ * `process.env` read here would not parse.
+ *
+ * The set is uf's, not a runtime's. Node.js enforces `read` and `write`, Deno
+ * enforces all five, and Bun has no permission model at all — a host that
+ * cannot enforce what is declared **refuses the run** rather than applying part
+ * of it. `docs/hosts.md` is the table.
+ *
+ * The declared paths are *added to* the ones uf needs to run the project, so
+ * what a set denies is the rest of the machine — `~/.ssh`, the network, the
+ * environment — and not the project's own files.
+ */
+export type Permissions = {
+  readonly read?: $ReadOnlyArray<string>,
+  readonly write?: $ReadOnlyArray<string>,
+  readonly net?: $ReadOnlyArray<string>,
+  readonly env?: $ReadOnlyArray<string>,
+  readonly run?: $ReadOnlyArray<string>,
+};
+
 /**
  * Percentages a coverage gate requires, as whole numbers between 0 and 100.
  *
@@ -30,7 +338,52 @@ export type CoverageThresholds = {
 };
 
 export type UniflowedConfig = {
+  /**
+   * The runtime accessibility audit: `expect(el).toHaveNoAxeViolations()` in a
+   * test, and the page `uf dev` is serving.
+   *
+   * One block for both on purpose. A rule a project has decided cannot be
+   * judged here — `color-contrast` against a DOM with no layout is the
+   * standing example — has to be the same rule in CI and in the loop somebody
+   * is working in, or the audit that finds a violation while the component is
+   * being written disagrees with the one that blocks the pull request.
+   *
+   * Inert without axe-core, which uf does not install: add it and both halves
+   * start working.
+   *
+   * Not the same thing as `lint.rules`' `a11y/*`, which read JSX that was
+   * never rendered.
+   */
+  readonly accessibility?: {
+    readonly devAudit?: boolean,
+    readonly axe?: {
+      // Run only rules carrying one of these axe tags; every rule when absent.
+      readonly tags?: $ReadOnlyArray<string>,
+      readonly disabledRules?: $ReadOnlyArray<string>,
+      readonly minImpact?: "minor" | "moderate" | "serious" | "critical",
+    },
+  },
   readonly app?: {
+    // Whether a component with no directive is rendered on the server or
+    // shipped to the browser.
+    readonly componentDefault?: "server" | "client",
+    readonly framework?: "uniflowed" | "react" | "react-native",
+    readonly react?: {
+      // React 19's Strict Mode, on by default in `uf dev`: it double-invokes
+      // render and effects so an impurity shows up in development rather
+      // than in production. Off has to be a choice a project makes.
+      readonly strictMode?: boolean,
+      readonly version?: string,
+      readonly asyncReact?: boolean,
+      readonly suspense?: boolean,
+      readonly useHook?: boolean,
+    },
+    // Whether the project builds React Server Components at all, and whether
+    // a `"use server"` export is wired to an endpoint.
+    readonly rsc?: boolean,
+    readonly serverActions?: boolean,
+    // The runtimes the build must satisfy.
+    readonly targets?: $ReadOnlyArray<"web" | "react-native" | "server" | "hermes">,
     readonly orm?: {
       readonly enabled?: boolean,
       readonly module?: "@uniflowed/orm",
@@ -39,11 +392,18 @@ export type UniflowedConfig = {
       readonly preparedByDefault?: true,
     },
     readonly builtins?: {
+      readonly data?: "uniflowed-query",
+      readonly effect?: "uniflowed-effect",
       readonly fetch?: {
         readonly module?: "@uniflowed/fetch",
         readonly overrideGlobalFetch?: false,
       },
       readonly cell?: boolean,
+      readonly frameworkLints?: boolean,
+      readonly nativeTestRunner?: boolean,
+      readonly reactTestingLibrary?: boolean,
+      readonly relay?: boolean,
+      readonly style?: "style-x",
       readonly reactCompiler?: {
         readonly enabled?: boolean,
         readonly implementation?: "official-rust",
@@ -66,6 +426,19 @@ export type UniflowedConfig = {
           readonly extensions?: $ReadOnlyArray<".mdx">,
           readonly jsxImportSource?: "@uniflowed/jsx-runtime",
           readonly pipelinePlugin?: "built-in",
+          // Colours are computed during the build and written into the HTML,
+          // so nothing ships to the browser to do it. Both themes are emitted
+          // together as CSS variables, because a build cannot know which the
+          // reader prefers.
+          readonly highlight?: {
+            readonly enabled?: boolean,
+            readonly themes?: {
+              readonly light?: string,
+              readonly dark?: string,
+            },
+            // Grammars beyond the ones a uf project uses by default.
+            readonly langs?: $ReadOnlyArray<string>,
+          },
         },
         readonly cache?: "opt-in",
       },
@@ -76,6 +449,34 @@ export type UniflowedConfig = {
         readonly widths?: $ReadOnlyArray<number>,
         readonly quality?: number,
         readonly placeholder?: boolean,
+        // The remote images `/__uf/image` may fetch, resize and re-encode —
+        // Next.js's `images.remotePatterns`, with its four keys and its
+        // wildcards. Empty, the default, means there is no endpoint at all. A
+        // redirect is followed only to a URL that matches too. See
+        // docs/app/guide/assets.
+        readonly remotePatterns?: $ReadOnlyArray<{
+          // `"https"` when absent; `"http"` has to be said.
+          readonly protocol?: "https" | "http",
+          // A name, or one under a leading `*.` (one more label) or `**.`
+          // (any number). A bare `*` is refused: it is not an allow-list.
+          readonly hostname: string,
+          // The protocol's default port when absent, and no other.
+          readonly port?: string,
+          // `*` is one segment and `**` any number. Any path when absent.
+          readonly pathname?: string,
+        }>,
+        // Qualities the endpoint answers besides `quality`. Each one is one
+        // more encode of every remote image a stranger can ask for, so the
+        // endpoint takes the listed ones and no others.
+        readonly qualities?: $ReadOnlyArray<number>,
+        // Fetch from loopback, private and link-local addresses too. For a
+        // test that serves its own images; never for a deployment.
+        readonly dangerouslyAllowPrivateAddresses?: boolean,
+        // A module exporting `createImageTransformer`, for a deploy target
+        // with no encoder of its own: `--adapter node`, `bun`, `deno`,
+        // `container` and `serverless`. `uf start` and `uf preview` encode
+        // with uf, and `--adapter edge` with Cloudflare's image binding.
+        readonly transformer?: string,
       },
       readonly fonts?: {
         readonly enabled?: boolean,
@@ -84,6 +485,27 @@ export type UniflowedConfig = {
         // faces `uf_assets::font::LOCAL_FACES` knows the metrics of, because
         // the scaling is a ratio against real numbers rather than a guess.
         readonly fallback?: string,
+        // How an imported family is cut down. `"none"` is the default and the
+        // argued position: subsetting is lossy, and a build cannot see the
+        // text a server will render or a user will type. `"ranges"` splits the
+        // font's own coverage into script buckets with exact `unicode-range`
+        // values and loses nothing.
+        readonly subset?: "none" | "ranges",
+        // Whether `Font` preloads the primary face. Exactly one file is ever
+        // preloaded, however many buckets a split produced.
+        readonly preload?: boolean,
+      },
+      readonly icons?: {
+        readonly enabled?: boolean,
+        // Where `uf:icon/<name>` looks for `<name>.svg`, from the project
+        // root. A directory rather than a claim on `.svg`, which stays Vite's.
+        readonly dir?: string,
+      },
+      readonly og?: {
+        readonly enabled?: boolean,
+        // The typeface every `*.og.json` is drawn with unless it names its
+        // own. uf embeds none, so a project that draws cards points at one.
+        readonly font?: string | null,
       },
       readonly motion?: {
         readonly module?: "@uniflowed/motion",
@@ -118,10 +540,8 @@ export type UniflowedConfig = {
       },
     },
     readonly runtime?: {
-      readonly default?: "node" | "deno" | "bun" | "uf",
-      readonly compatibility?: $ReadOnlyArray<
-        "node" | "bun" | "deno" | "edge" | "serverless" | "container",
-      >,
+      readonly default?: RuntimeEngine,
+      readonly compatibility?: $ReadOnlyArray<RuntimeEngine>,
       readonly capabilityJsHost?: {
         readonly default?: CapabilityJsHost,
         readonly hosts?: $ReadOnlyArray<CapabilityJsHost>,
@@ -129,36 +549,199 @@ export type UniflowedConfig = {
       },
       readonly deploy?: {
         readonly enabled?: boolean,
-        readonly adapters?: $ReadOnlyArray<
-          "node" | "bun" | "deno" | "edge" | "serverless" | "static" | "container",
-        >,
+        // The target `uf build` writes an artefact for when none is named on
+        // the command line; `--adapter` beats it.
+        readonly adapter?: DeployAdapter,
+        readonly adapters?: $ReadOnlyArray<DeployAdapter>,
       },
     },
     readonly router?: {
+      // `false` says this project is not a uf application, and is the only way
+      // to say it: a library has no routes to scan for.
+      readonly enabled?: boolean,
       readonly entry?: string,
       readonly root?: string,
       readonly manifest?: string,
+      readonly convention?: "file-system",
+      // Turning the file-system router off is what makes a project a
+      // **library** rather than an application, and `uf build` reads it: see
+      // `build.lib` below and docs/app/reference/config.
+      readonly enabled?: boolean,
+      /**
+       * Redirects answered before anything else, in order; the first whose
+       * `source` matches wins. `next.config.js`'s `redirects()`. See
+       * `RouteRedirect` and docs/app/guide/routing.
+       */
+      readonly redirects?: $ReadOnlyArray<RouteRedirect>,
+      /**
+       * Routes served at another path, in order; the first whose `source`
+       * matches wins. `next.config.js`'s `rewrites()`, without proxying. See
+       * `RouteRewrite` and docs/app/guide/routing.
+       */
+      readonly rewrites?: $ReadOnlyArray<RouteRewrite>,
+      /**
+       * Response headers by path; every matching rule applies.
+       * `next.config.js`'s `headers()`. See `RouteHeaders` and
+       * docs/app/guide/routing.
+       */
+      readonly headers?: $ReadOnlyArray<RouteHeaders>,
+      /**
+       * The path the whole application is served under — `"/docs"` — with no
+       * trailing slash. Every link, redirect, asset URL, payload URL and
+       * sitemap entry carries it, and a request outside it is a `404`. The
+       * sources of the three lists above are written without it.
+       * `next.config.js`'s `basePath`.
+       */
+      readonly basePath?: string,
+      /**
+       * Which spelling of a path is the page; see `RouterTrailingSlash`.
+       * `"ignore"` when absent.
+       */
+      readonly trailingSlash?: RouterTrailingSlash,
+      /** HTTPS links explicitly claimed by the iOS and Android applications. */
+      readonly nativeLinks?: {|
+        readonly origins: $ReadOnlyArray<string>,
+        readonly routes: $ReadOnlyArray<string>,
+        readonly iosAppIds: $ReadOnlyArray<string>,
+        readonly androidPackage: string,
+        readonly androidSha256: $ReadOnlyArray<string>,
+      |},
     },
     readonly rendering?: {
-      readonly modes?: $ReadOnlyArray<"ppr" | "ssr" | "ssg" | "isr">,
+      // `"csr"` is the one value that cannot share the list: it renders every
+      // route in the browser from one shell, where the others write a document
+      // per route, so there is no per-route choice left for the list to hold.
+      // `["csr"]` is a single-page application; see docs/app/guide/rendering.
+      readonly modes?: $ReadOnlyArray<"ppr" | "ssr" | "ssg" | "isr" | "csr">,
+      // What the browser does when a visitor follows a link, which is a
+      // different question from `modes` rather than a fifth value in it:
+      // `modes` says where a document comes from, per route, and this says
+      // what happens once the browser has one. `"document"` is a full document
+      // request — the client router is not installed and `Link` renders an
+      // ordinary anchor. See docs/app/guide/routing/navigation.
+      readonly navigation?: "client" | "document",
+      // How long, in whole seconds, the client router shows a route it already
+      // fetched or prefetched without asking the server again: a click on a
+      // prefetched link, a second visit and the back button all read it. `0`,
+      // the default, keeps nothing. `router.refresh()` and every server action
+      // clear it. See docs/app/guide/routing and docs/app/guide/cache.
+      readonly staleTime?: number,
       readonly cache?: {
         readonly actions?: boolean,
         readonly data?: boolean,
         readonly fetch?: boolean,
         readonly route?: boolean,
+        // Where cache entries live, and the only thing here that is a *name*
+        // rather than a switch: `"memory"` (the default) is one process,
+        // `"filesystem"` is uf's built-in durable provider, and anything else
+        // is a module specifier exporting `createCacheProvider` — the same
+        // shape `builder.module` has, and for the same red line. Turning this
+        // on caches nothing new: a route still has to state a lifetime.
+        readonly store?: string,
+        // Where `"filesystem"` keeps them. Defaults to `.uf/cache/route` under
+        // the project. A deployment that has one writable directory — `/tmp` on
+        // a Lambda, a mounted volume in a container — names it here.
+        readonly storeDir?: string,
       },
     },
   },
   readonly build?: {
+    // Size ceilings that fail the build. Unset by default: failing a build
+    // nobody asked uf to police is worse than reporting the size.
+    readonly budgets?: {
+      readonly total?: SizeBudget,
+      readonly initialJs?: SizeBudget,
+      readonly perRoute?: SizeBudget,
+      readonly perAsset?: SizeBudget,
+    },
     readonly entries?: $ReadOnlyArray<string>,
+    // Commands to run around the build, in the same shape as `tasks`.
+    readonly hooks?: { readonly [string]: TaskDefinition },
     readonly outDir?: string,
+    // Prerender every route and leave no server bundle behind. Read together
+    // with `app.rendering.modes`; see docs/app/reference/config.
     readonly staticBuild?: boolean,
     readonly sourcemap?: boolean,
+    /**
+     * What a **library** build writes, for a project whose
+     * `app.router.enabled` is false.
+     *
+     * Never the switch. `app.router.enabled` decides which of the two builds
+     * `uf build` runs, and declaring this key in a project whose router is on
+     * is refused where the config is read rather than resolved by precedence.
+     * Every field has a default that builds what `uf new --lib` scaffolds, so
+     * a library ordinarily writes none of this.
+     *
+     * `"umd"` and `"iife"` are deliberately absent from `formats`: each needs
+     * a global name per entry, and what a Flow library's global should be is
+     * not a decision uf has made.
+     */
+    readonly lib?: {
+      // The modules to build, relative to the project root. Each names its own
+      // output by its path — `internal/parse.js` is written to
+      // `dist/internal/parse.js` — so two entries cannot collide.
+      readonly entries?: $ReadOnlyArray<string>,
+      readonly formats?: $ReadOnlyArray<"es" | "cjs">,
+      // Package names to leave as imports *beyond* the ones the manifest
+      // declares. A library build already externalises `dependencies`,
+      // `peerDependencies`, `optionalDependencies` and the host's built-in
+      // modules; this is for what a manifest cannot say.
+      readonly external?: $ReadOnlyArray<string>,
+      /**
+       * Write a TypeScript declaration file beside each entry. On by
+       * default.
+       *
+       * Most people who install a Flow library write TypeScript, and to them
+       * a package with no `.d.ts` is `any`. Every Flow construct that has no
+       * TypeScript meaning is named in the build report rather than silently
+       * widened, so turning this off is for a library that would rather ship
+       * no declarations than ones with gaps in them — not for one that wants
+       * to stop hearing about the gaps.
+       */
+      readonly declarations?: boolean,
+    },
+    /**
+     * What `uf dev`, `uf build` and `uf preview` run on, when it is not the
+     * top-level `runtime`: `"node@26"`.
+     *
+     * Read before `runtime`, so a project that builds on Node and tests on Bun
+     * can say so. See `RuntimeSpec` for the grammar.
+     */
+    readonly runtime?: RuntimeSpec,
+    /**
+     * Which builder `uf dev`, `uf build`, `uf preview` and `uf start` drive:
+     * `"vite"`, or a module specifier.
+     *
+     * Vite is the default, not a dependency: any module satisfying the
+     * contract in docs/architecture.md can be named here. See `BuilderSpec`.
+     */
+    readonly builder?: BuilderSpec,
+  },
+  readonly builder?: {
+    /**
+     * The old spelling of `build.builder`.
+     *
+     * **Deprecated**, and read only when `build.builder` is absent; the two
+     * naming different builders is an error. `"@uniflowed/vite"` here is
+     * `builder: "vite"` there, and any other specifier moves as it is.
+     */
+    readonly module?: string,
   },
   readonly dev?: {
     readonly host?: string,
     readonly port?: number,
     readonly strictPort?: boolean,
+    // Which files the dev server may serve. `deny` is evaluated on the
+    // canonical path and beats `allow`; see docs/security.md.
+    readonly fs?: {
+      readonly allow?: $ReadOnlyArray<string>,
+      readonly deny?: $ReadOnlyArray<string>,
+    },
+    // `--host` refuses to bind a routable address while this is empty: a dev
+    // server reachable from the network with no host allow-list is a file
+    // server for your source tree.
+    readonly allowedHosts?: $ReadOnlyArray<string>,
+    readonly allowedOrigins?: $ReadOnlyArray<string>,
   },
   readonly docs?: {
     readonly enabled?: boolean,
@@ -168,13 +751,27 @@ export type UniflowedConfig = {
     readonly staticBuild?: boolean,
     readonly deploy?: "void",
   },
-  readonly lint?: {
-    readonly engine?: "rust",
-    readonly flow?: {
-      readonly builtins?: "mixed",
-      readonly parser?: "official-flow-rust",
-    },
-    readonly rules?: { readonly [string]: RuleLevel },
+  /**
+   * The `.env` cascade and the mode it is read for.
+   *
+   * `active` empty means the command decides — `development` for `uf dev`,
+   * `production` for a build, `test` for `uf test`. `files` empty selects the
+   * conventional cascade rather than no files at all.
+   */
+  readonly env?: {
+    readonly active?: string,
+    readonly files?: $ReadOnlyArray<string>,
+    /**
+     * Runtimes and package managers by exact version — `{ node: "24.14.0" }`.
+     *
+     * **Deprecated.** It says which tools a project has and not what each is
+     * for, so a project that builds on Node and tests on Bun could not write
+     * that down. Declare each tool where it is used instead — `runtime`,
+     * `build.runtime`, `test.runtime` and `packageManager` — as
+     * `name@version`. It keeps working for `uf env install` and `uf env exec`,
+     * and a pin here that disagrees with one of those keys is an error.
+     */
+    readonly toolchain?: { readonly [string]: string },
   },
   readonly fmt?: {
     readonly indentWidth?: number,
@@ -186,10 +783,57 @@ export type UniflowedConfig = {
     },
     readonly nonFlow?: {
       readonly formatter?: "biome" | "prettier" | "none",
+      /**
+       * Extra arguments, passed to that formatter verbatim.
+       *
+       * Strings rather than a shape, so that reaching one of biome's or
+       * prettier's own options never waits for a uf release — a Tailwind 4
+       * project writes `["--css-parse-tailwind-directives=true"]` and needs no
+       * second configuration file. An argument that would turn `uf fmt
+       * --check` into a write is refused where the config is read.
+       */
+      readonly arguments?: $ReadOnlyArray<string>,
     },
     readonly quotes?: "single" | "double",
     readonly semicolons?: boolean,
   },
+  /**
+   * Paths no command walks into.
+   *
+   * Top level because every command that walks the project reads it: `uf fmt`,
+   * `uf lint`, `uf check`, `uf test` and `uf doc`. A bare name — `dist` — names
+   * a kind of directory and matches at any depth; a path — `src/generated` —
+   * names one place. `.uf` and `.git` are uf's and git's and are not a
+   * project's to opt back into.
+   *
+   * Absent takes uf's own list, `["node_modules", "dist", "target"]`. An empty
+   * list is a different instruction: it is a project that has looked at that
+   * list and wants none of it.
+   */
+  readonly ignore?: $ReadOnlyArray<string>,
+  readonly lint?: {
+    readonly engine?: "rust",
+    // Globs to lint.
+    readonly files?: $ReadOnlyArray<string>,
+    /**
+     * The old spelling of the top-level `ignore`.
+     *
+     * **Deprecated**, and read only when `ignore` is absent. It was never
+     * `uf lint`'s alone: `uf fmt`, `uf check`, `uf test` and `uf doc` walk the
+     * project through the same code and have always obeyed it, so the key was
+     * named after one of the five commands that read it. It keeps working for
+     * as long as alpha lasts, and every one of those commands says so once.
+     * See ubugeeei-prod/uf#575.
+     */
+    readonly ignore?: $ReadOnlyArray<string>,
+    readonly flow?: {
+      readonly builtins?: "mixed",
+      readonly parser?: "official-flow-rust",
+    },
+    // Changes to uf's rule table, not the whole of it: a rule you did not
+    // mention keeps the level uf ships. Say `"off"` to switch one off.
+    readonly rules?: { readonly [string]: RuleLevel },
+  },
   readonly package?: {
     readonly generator?: "napi-rs",
     readonly targets?: $ReadOnlyArray<
@@ -197,12 +841,73 @@ export type UniflowedConfig = {
     >,
     readonly typescriptDeclarationsToFlow?: true,
   },
+  /**
+   * The package manager `uf install`, `uf add`, `uf update` and the rest drive,
+   * and optionally which release of it: `"pnpm@12.0.0"`.
+   *
+   * Read before `pm.packageManager` — its deprecated spelling — and before
+   * `package.json#packageManager` and the lockfile. See `PackageManagerSpec`.
+   */
+  readonly packageManager?: PackageManagerSpec,
+  readonly permissions?: Permissions,
+  // Plugins the project adds, appended to uf's own and resolved in the order
+  // they are written. A name that names a file is code to run, so `uf_plugin`
+  // refuses any that reaches outside the project root.
+  readonly plugins?: $ReadOnlyArray<PluginEntry>,
   readonly pm?: {
     readonly module?: "@uniflowed/pm",
     readonly resolver?: "uf-native",
     readonly lockfile?: "uf.lock",
     readonly storeDir?: string,
     readonly allowLifecycleScripts?: false,
+    /**
+     * The package manager uf drives, in the spelling that came before the
+     * top-level `packageManager`.
+     *
+     * **Deprecated** for the managers `packageManager` can name — write
+     * `packageManager: "pnpm"` rather than `pm: { packageManager: "pnpm" }`,
+     * and `"yarn@1"` for `"yarn-classic"` — and read only when that key is
+     * absent. The two naming different managers is an error. `"uf"`, uf's own
+     * resolver, has no other spelling and is not deprecated.
+     */
+    readonly packageManager?: PackageManagerPreference,
+    /**
+     * The registry uf *reads* from: packuments, provenance attestations, and
+     * the versions `uf update` reports against.
+     *
+     * Unset means `publish.registry`, which is where this lived until it
+     * turned out to be answering two questions with one value. A project that
+     * publishes to a company registry and installs through a read-through
+     * mirror sets both; one that has only ever set `publish.registry` keeps
+     * working and is told, once, which key to move to.
+     */
+    readonly registry?: string,
+    /**
+     * Which registry answers for which scope: `{ "@company": "https://…" }`.
+     *
+     * A scope named here resolves from that registry **and nowhere else**.
+     * There is no fallback to the public registry, deliberately: publishing
+     * `@company/internal-thing` to npmjs and waiting for a resolver to fall
+     * back to it is the dependency-confusion attack, so the fallback is the
+     * vulnerability rather than a recovery from it. A name the bound registry
+     * does not have is an error that names the scope and the registry.
+     *
+     * uf refuses an install whose lockfile resolves a bound scope from
+     * somewhere else. It does not rewrite the project's `.npmrc`: the manager
+     * that resolves is the manager that has to be told, in its own
+     * configuration.
+     */
+    readonly scopes?: { readonly [scope: string]: string },
+    /**
+     * How hard `uf install` looks at npm provenance attestations.
+     *
+     * `"report"`, the default, reads the attestation of every package the
+     * install brought in or moved: an attestation that is not about the
+     * tarball being installed stops the install, and a package with none is a
+     * line in the summary. `"off"` reads none, for a machine with no route to
+     * a registry.
+     */
+    readonly provenance?: "report" | "off",
   },
   readonly rm?: {
     readonly module?: "@uniflowed/rm",
@@ -213,6 +918,17 @@ export type UniflowedConfig = {
     readonly apply?: "config-and-host",
     readonly doctor?: boolean,
   },
+  /**
+   * The runtime every command runs on unless a section names its own, and
+   * optionally which release of it: `"node@26"`.
+   *
+   * `uf start`, `uf run` and `uf exec` read it directly. `uf dev`, `uf build`
+   * and `uf preview` read `build.runtime` first; `uf test` reads `test.runtime`
+   * and the runtime its runner brings first. Absent, a command starts
+   * `app.runtime.capabilityJsHost` from `PATH`, as it always has. See
+   * `RuntimeSpec`.
+   */
+  readonly runtime?: RuntimeSpec,
   readonly server?: {
     readonly engine?: "native-rust",
     readonly native?: {
@@ -223,6 +939,19 @@ export type UniflowedConfig = {
       >,
     },
   },
+  // Where the built site is served from, and what `uf build` may therefore
+  // write for a crawler. `url` is the switch: without it no `sitemap.xml` and
+  // no `robots.txt` are written at all, because a build cannot guess the host
+  // it will be deployed to and a wrong `<loc>` is worse than a missing one.
+  readonly site?: {
+    readonly url?: string,
+    readonly sitemap?: boolean,
+    readonly robots?: {
+      readonly enabled?: boolean,
+      readonly allow?: $ReadOnlyArray<string>,
+      readonly disallow?: $ReadOnlyArray<string>,
+    },
+  },
   readonly std?: {
     readonly module?: "@uniflowed/std",
     readonly wintertcAligned?: true,
@@ -311,13 +1040,42 @@ export type UniflowedConfig = {
   },
   readonly test?: {
     readonly module?: "@uniflowed/test",
-    readonly runner?: {
-      readonly runtime?: "capability-js-host" | "uf-self-hosted",
-      readonly jsHosts?: $ReadOnlyArray<CapabilityJsHost>,
-      readonly scheduler?: "native-work-stealing",
-      readonly performanceTarget?: "faster-than-bun",
-      readonly officialFlowParser?: true,
-    },
+    /**
+     * What `uf test` runs on, when it is neither the runtime the runner brings
+     * nor the top-level `runtime`: `"node@26"`.
+     *
+     * A runner that brings its own — `runner: "bun@1.4"` — decides this when it
+     * is absent, and a `runtime` here naming anything else is an error. See
+     * `RuntimeSpec`.
+     */
+    readonly runtime?: RuntimeSpec,
+    /**
+     * Which application host `uf test` targets.
+     *
+     * `"auto"` follows `app.framework`: React Native projects target
+     * `"react-native"`, and every other project targets `"web"`. Write
+     * `"web"` in a React Native project only for tests that intentionally
+     * target a document.
+     */
+    readonly target?: "auto" | "web" | "react-native",
+    /**
+     * What runs the suite: `"uf"`, the default, or `"bun[@version]"`. See
+     * `TestRunnerSpec`.
+     *
+     * The object is the old description of uf's own runner, field by field,
+     * and is **deprecated**: it still parses, and `applicationTarget` in it is
+     * still read when `target` is absent.
+     */
+    readonly runner?:
+      | TestRunnerSpec
+      | {
+          readonly applicationTarget?: "auto" | "web" | "react-native",
+          readonly runtime?: "vite-task" | "capability-js-host" | "uf-self-hosted",
+          readonly jsHosts?: $ReadOnlyArray<CapabilityJsHost>,
+          readonly scheduler?: "vite-task-cache" | "native-work-stealing",
+          readonly performanceTarget?: "vite-task" | "faster-than-bun",
+          readonly officialFlowParser?: true,
+        },
     readonly reactTestingLibraryNative?: true,
     /**
      * What `uf test --coverage` measures, writes and fails on.
@@ -338,6 +1096,38 @@ export type UniflowedConfig = {
     },
   },
   readonly tasks?: { readonly [string]: TaskDefinition },
+  /**
+   * Tasks `uf prepare` runs before a commit, keyed by a glob over the staged
+   * files.
+   *
+   * A glob with no `/` matches a file's name wherever it is; one with a `/`
+   * matches its path from the project root. Each task named runs once, with
+   * every staged file its glob matches appended to its command, over what is
+   * staged rather than what is on disk. A fix to a fully staged file is staged
+   * with it; a fix to a half-staged one is not kept, and stops the commit.
+   */
+  readonly staged?: { readonly [string]: string | $ReadOnlyArray<string> },
+  /**
+   * Where `uf ui add` writes the components a project owns, and where
+   * `uf ui list` and `uf ui diff` look for them.
+   *
+   * `directory` is relative to the project root, and `app/components/ui` when
+   * absent. Every component goes in the one directory, because each imports
+   * the ones it builds on as siblings (`./button.js`). A path that leaves the
+   * project is refused before anything is written.
+   */
+  readonly ui?: {
+    readonly directory?: string,
+  },
+  /**
+   * Vite's own configuration, merged over the one uf generates.
+   *
+   * uf reads none of it, which is the point: an option Vite adds tomorrow
+   * works in a uf project tomorrow rather than after a uf release that names
+   * it. Deliberately unshaped for the same reason — a Flow type over Vite's
+   * options would be the re-declaration this key exists to avoid.
+   */
+  readonly vite?: { readonly [string]: mixed },
   readonly vrt?: {
     readonly enabled?: boolean,
     readonly module?: "@uniflowed/vrt",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/config",
-  "version": "0.0.0-alpha.9",
+  "version": "0.1.0",
   "description": "Flow declarations for @uniflowed/config, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -15,6 +15,7 @@
   },
   "files": [
     "index.js",
-    "internal"
+    "internal",
+    "!*.test.js"
   ]
 }