@grida/fx 0.0.0-stage → 0.1.0-alpha.2

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @grida/fx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Grida FX for JavaScript and TypeScript: the `grida-fx` command, and an SDK to write workflow
+files and to plan, price and run them. Grida FX is a workflow engine for generative asset
+pipelines: write a workflow file, and FX plans it, prices it before anything is spent, caches
+every paid call by its request, and records the run. It works with your own provider keys.
+
+This is a **preview** (`0.x` pre-releases under the npm tag `next`).
+
+```sh
+npm install @grida/fx@next     # or: npm install -g @grida/fx@next
+npx grida-fx --help
+```
+
+The engine is a native binary. npm installs it with this package, as an optional dependency for
+your machine:
+
+| Platform | Engine package |
+|---|---|
+| macOS on Apple silicon | `@grida/fx-darwin-arm64` |
+| macOS on Intel | `@grida/fx-darwin-x64` |
+| Linux on x64, glibc 2.28 or later | `@grida/fx-linux-x64-gnu` |
+| Linux on arm64, glibc 2.28 or later | `@grida/fx-linux-arm64-gnu` |
+
+**Windows is not in the preview**: the engine's runner uses Unix process groups and signals. Use
+WSL 2, which runs the Linux packages. Linux with musl (Alpine) is not supported either. Node 18 or
+later.
+
+`grida-fx` reports what is missing when it finds no engine. If you install with
+`--omit=optional`, or need a binary of your own, set `GRIDA_FX_BIN` to the path of a `grida-fx`
+binary: the command and the SDK use it first.
+
+Some steps run on Python in the preview (your own Python nodes, and the built-in local types such
+as `image.resize`): those projects also need `pip install --pre grida`, or `GRIDA_FX_PYTHON`
+pointing at a Python that has them. A project whose steps are all paid built-ins and `select`
+needs only this package. See [Getting started](https://github.com/gridaco/fx/blob/main/docs/guide/01-getting-started.md).
+
+## The SDK
+
+Every function drives the engine and reads the JSON it prints. Planning never spends; a run
+spends only with `live: true`, within a ceiling.
+
+```ts
+import { plan, run } from "@grida/fx";
+
+const planned = await plan("workflows/icon.yaml", { inputs: { name: "copper lantern" } });
+console.log(planned.ok, planned.estimate); // { lowUsd, highUsd, ceilingUsd }
+
+const result = await run(planned, { live: true }); // the plan's own target, inputs and ceiling
+console.log(result.ok, result.chargedUsd, result.failed);
+const icon = result.outputs.icon; // a RunFile: digest, kind, path, read()
+```
+
+- `plan(target, options)`: the expanded graph (`plan.graph`, fx-graph-v1) and its price
+  (`plan.price`), with `ok`, `problems`, `estimate` and `phases`.
+- `expand`, `identity`, `price`: the documents of `grida-fx expand`, `identity` and `price`.
+- `run(target | plan, options)`: plans first (a plan with problems rejects with `PlanRefused`),
+  runs, and reads the run back: `ok`, `incomplete`, `chargedUsd`, `failed`, `outputs`, `steps`.
+  A failed step does not reject.
+- `project(runDir)` and `inspect(runOrWorkflowId, { verify })`: a run's record and summary.
+- `binary()` and `engineVersion()`: the engine in use.
+
+A target is a workflow file, a workflow id, or a builder `file.py:function`. Options:
+`inputs` (values), `inputFiles`, `routes`, `args` (a builder's arguments), `maxUsd`, `cwd`,
+`env` (for example `GRIDA_FX_PYTHON`) and `signal` (an `AbortSignal`); `run` also takes `live`,
+`yesUpTo`, `runDir` and `deliver`. Relative paths start at `cwd`. The engine's errors reject with
+`FxError`, which carries its `exitCode` and `stderr`.
+
+## Writing workflows
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { expr, toYaml, workflow } from "@grida/fx";
+
+const icon = workflow({
+  id: "icon",
+  title: "One item icon",
+  inputs: { name: { type: "string", description: "What the item is" } },
+  steps: {
+    draw: {
+      uses: "fx/image.generate@1",
+      with: { prompt: `A single ${expr("inputs.name")} game icon`, background: "transparent" },
+    },
+  },
+  outputs: { icon: expr("steps.draw.outputs.image") },
+});
+await writeFile("workflows/icon.yaml", toYaml(icon));
+```
+
+`toYaml` writes the strict YAML subset the engine reads, as the engine writes it: every string
+that would read back as something else (`on`, `017`, `2026-10-05`, a digest) is quoted.
+
+The [guide](https://github.com/gridaco/fx/tree/main/docs/guide) covers workflow files, nodes,
+cost and cache, and running.

package/bin/grida-fx.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The grida-fx command: runs the engine for this machine (src/cli.ts).
+import { main } from "../dist/cli.js";
+
+main(process.argv.slice(2));

package/dist/api.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Planning and running from JavaScript, by driving the `grida-fx` binary: the engine is the only
+ * place with engine logic, and these functions read the documents it prints.
+ *
+ * - A target is what the command takes: a workflow file, a workflow id, or a builder
+ *   `file.py:function` (with `args`). `run` also takes a {@link Plan}: it runs it with the target
+ *   and options it was planned with.
+ * - Relative paths (`inputFiles`, `routes`, `runDir`, paths inside `inputs`) start at `cwd`, as on
+ *   the command line.
+ * - Planning never spends. A run spends only with `live: true`, within a ceiling.
+ * - The engine's errors (exit status 2), a run it refuses to start and an interrupted run reject
+ *   with {@link FxError}; a plan with problems that is asked to run rejects with
+ *   {@link PlanRefused}. A failed step does not reject: read `result.ok` and `result.failed`.
+ */
+import type { Encoded, FileRef, Graph, Identities, Inspection, Price, PricePhase, Problem, ProjectedInstance, Projection } from "./documents.js";
+import { type CallOptions, type Exit } from "./engine.js";
+import { FxError } from "./errors.js";
+import { type PlanOptions, type PlanRequest, type RunOptions } from "./request.js";
+import type { JsonValue } from "./workflow.js";
+/** A plan the engine made: the expanded graph and its price. */
+export declare class Plan {
+    /** The expanded graph (fx-graph-v1), as `grida-fx plan --json` prints it. */
+    readonly graph: Graph;
+    /** The price by phase, as `grida-fx price` prints it. */
+    readonly price: Price;
+    /** The target and options it was planned with; `run(plan)` uses them. */
+    readonly request: PlanRequest;
+    constructor(graph: Graph, price: Price, request: PlanRequest);
+    /** Whether the plan has no problems, so it may run. */
+    get ok(): boolean;
+    /** Why the plan is refused; empty when it is not. */
+    get problems(): Problem[];
+    /** What the run may spend on what is not cached, and its ceiling, in US dollars. */
+    get estimate(): {
+        lowUsd: number;
+        highUsd: number;
+        ceilingUsd: number | null;
+    };
+    /** The price by phase. */
+    get phases(): PricePhase[];
+    /** The workflow's id. */
+    get workflowId(): string;
+}
+/** A plan with problems was asked to run: `the plan is refused:` and one line per problem. */
+export declare class PlanRefused extends FxError {
+    /** The refused plan. */
+    readonly plan: Plan;
+    constructor(plan: Plan);
+}
+/** `grida-fx expand`: the expanded graph (fx-graph-v1), with `problems`. Never spends. */
+export declare function expand(target: string, options?: PlanOptions): Promise<Graph>;
+/** `grida-fx identity`: each live instance's identity (null while it waits on a result). */
+export declare function identity(target: string, options?: PlanOptions): Promise<Identities>;
+/** `grida-fx price`: the plan's price by phase. Never spends. */
+export declare function price(target: string, options?: PlanOptions): Promise<Price>;
+/** Expands, checks and prices `target` (`grida-fx plan --json` and `price`). Never spends;
+ * `plan.problems` says what is wrong. */
+export declare function plan(target: string, options?: PlanOptions): Promise<Plan>;
+/** A file a run made, by digest. */
+export declare class RunFile {
+    readonly digest: string;
+    /** The file kind (`image/png`, `json`, …). */
+    readonly kind: string;
+    readonly name: string;
+    readonly size: number;
+    /** A collection item's key, if it has one. */
+    readonly key: string | null;
+    /** Where the run placed it (an absolute path in the run folder), or null when no step of this
+     * run placed it (a workflow output that is one of its input files). Read it; never write it:
+     * it shares its bytes with the cache. */
+    readonly path: string | null;
+    constructor(ref: FileRef, path: string | null);
+    /** The file's bytes. */
+    read(): Promise<Buffer>;
+}
+/** A value of a run: a file, a keyed collection (in its order), a list, a plain value, or null. */
+export type RunValue = RunFile | Map<string, RunValue> | RunValue[] | JsonValue;
+/** A finished `run`: read from the engine's `project` and `inspect --json` of its folder. */
+export declare class RunResult {
+    #private;
+    /** The run folder, absolute. */
+    readonly runDir: string;
+    /** The engine's exit status: 0 when the run is ok (and every `deliver` found its output). */
+    readonly exitCode: number;
+    /** What `grida-fx run` printed: the plan and the run's summary. */
+    readonly stdout: string;
+    /** The run's record, projected (`grida-fx project`). */
+    readonly projection: Projection;
+    /** The run's summary (`grida-fx inspect --json`). */
+    readonly inspection: Inspection;
+    constructor(runDir: string, exit: Exit, projection: Projection, inspection: Inspection);
+    private get finished();
+    /** Whether every step that had to run succeeded and the run ended normally. */
+    get ok(): boolean;
+    /** Whether the run stopped before everything ran (running it again continues it). */
+    get incomplete(): boolean;
+    /** What the run folder has been charged, in US dollars, over every invocation. */
+    get chargedUsd(): number;
+    /** The ids of the instances that failed. */
+    get failed(): string[];
+    /** Why the run stopped early, if it did. */
+    get stopped(): string | null;
+    /** Each instance's state, by instance id. */
+    get steps(): Record<string, ProjectedInstance>;
+    /** Each declared output: a {@link RunFile}, a `Map` for a keyed collection, an array, a plain
+     * value, or null. */
+    get outputs(): Record<string, RunValue>;
+}
+/** A value of the run's record (fx-run-events-v1 `encoded`). */
+export declare function decode(encoded: Encoded, placed: ReadonlyMap<string, string>): RunValue;
+/**
+ * Runs `target`, or a plan, after planning it: a plan with problems rejects with
+ * {@link PlanRefused} before any folder exists. `live: true` admits paid calls, within a
+ * ceiling. Then reads the folder back through `grida-fx project` and `inspect --json`.
+ */
+export declare function run(target: string | Plan, options?: RunOptions): Promise<RunResult>;
+/** `grida-fx project <run>`: a run's record projected to its state. */
+export declare function project(runDir: string, options?: CallOptions): Promise<Projection>;
+/** Options of {@link inspect}. */
+export interface InspectOptions extends CallOptions {
+    /** Re-check every placed file against its record (`--verify`). */
+    readonly verify?: boolean;
+}
+/** `grida-fx inspect <run> --json`: a run's summary. `run` is a run folder, or a workflow id for
+ * its newest run. With `verify`, `verification` says whether every placed file still matches. */
+export declare function inspect(run: string, options?: InspectOptions): Promise<Inspection>;
+/** The engine's version (`grida-fx --version`), e.g. `0.1.0-alpha.1`. */
+export declare function engineVersion(options?: CallOptions): Promise<string>;

package/dist/api.js

@@ -0,0 +1,319 @@
+/**
+ * Planning and running from JavaScript, by driving the `grida-fx` binary: the engine is the only
+ * place with engine logic, and these functions read the documents it prints.
+ *
+ * - A target is what the command takes: a workflow file, a workflow id, or a builder
+ *   `file.py:function` (with `args`). `run` also takes a {@link Plan}: it runs it with the target
+ *   and options it was planned with.
+ * - Relative paths (`inputFiles`, `routes`, `runDir`, paths inside `inputs`) start at `cwd`, as on
+ *   the command line.
+ * - Planning never spends. A run spends only with `live: true`, within a ceiling.
+ * - The engine's errors (exit status 2), a run it refuses to start and an interrupted run reject
+ *   with {@link FxError}; a plan with problems that is asked to run rejects with
+ *   {@link PlanRefused}. A failed step does not reject: read `result.ok` and `result.failed`.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { call, document, failure, INTERRUPTED } from "./engine.js";
+import { FxError } from "./errors.js";
+import { makeRequest, planningArgs, runArgs, withInputsFile, } from "./request.js";
+/** The first line of a run's summary: `run` padded to 10 columns, then the folder as named. */
+const RUN_LINE = "run       ";
+/** How the engine says it would not start a run (on stdout, exit status 1). */
+const REFUSED = "refused: ";
+// ------------------------------------------------------------------------------------------------
+// Plans
+/** A plan the engine made: the expanded graph and its price. */
+export class Plan {
+    /** The expanded graph (fx-graph-v1), as `grida-fx plan --json` prints it. */
+    graph;
+    /** The price by phase, as `grida-fx price` prints it. */
+    price;
+    /** The target and options it was planned with; `run(plan)` uses them. */
+    request;
+    constructor(graph, price, request) {
+        this.graph = graph;
+        this.price = price;
+        this.request = request;
+    }
+    /** Whether the plan has no problems, so it may run. */
+    get ok() {
+        return this.problems.length === 0;
+    }
+    /** Why the plan is refused; empty when it is not. */
+    get problems() {
+        return (this.graph.problems ?? []).map((problem) => ({
+            where: String(problem.where ?? ""),
+            message: String(problem.message ?? ""),
+        }));
+    }
+    /** What the run may spend on what is not cached, and its ceiling, in US dollars. */
+    get estimate() {
+        const estimate = this.graph.estimate;
+        return {
+            lowUsd: Number(this.price.estimate?.low_usd ?? estimate?.low_usd ?? 0),
+            highUsd: Number(this.price.estimate?.high_usd ?? estimate?.high_usd ?? 0),
+            ceilingUsd: this.price.ceiling_usd ?? estimate?.ceiling_usd ?? null,
+        };
+    }
+    /** The price by phase. */
+    get phases() {
+        return this.price.phases ?? [];
+    }
+    /** The workflow's id. */
+    get workflowId() {
+        return this.graph.workflow?.id ?? "";
+    }
+}
+/** A plan with problems was asked to run: `the plan is refused:` and one line per problem. */
+export class PlanRefused extends FxError {
+    /** The refused plan. */
+    plan;
+    constructor(plan) {
+        const lines = plan.problems.map((problem) => `${problem.where}: ${problem.message}`);
+        super(["the plan is refused:", ...lines].join("\n"));
+        this.name = "PlanRefused";
+        this.plan = plan;
+    }
+}
+/** `grida-fx expand`: the expanded graph (fx-graph-v1), with `problems`. Never spends. */
+export async function expand(target, options = {}) {
+    return planningDocument("expand", makeRequest(target, options), options.signal);
+}
+/** `grida-fx identity`: each live instance's identity (null while it waits on a result). */
+export async function identity(target, options = {}) {
+    return planningDocument("identity", makeRequest(target, options), options.signal);
+}
+/** `grida-fx price`: the plan's price by phase. Never spends. */
+export async function price(target, options = {}) {
+    return planningDocument("price", makeRequest(target, options), options.signal);
+}
+/** Expands, checks and prices `target` (`grida-fx plan --json` and `price`). Never spends;
+ * `plan.problems` says what is wrong. */
+export async function plan(target, options = {}) {
+    return planRequest(makeRequest(target, options), options.signal);
+}
+async function planRequest(request, signal) {
+    const graph = await planningDocument("plan", request, signal, ["--json"]);
+    const priced = await planningDocument("price", request, signal);
+    return new Plan(graph, priced, request);
+}
+async function planningDocument(verb, request, signal, extra = []) {
+    return withInputsFile(request, (inputsFile) => document(verb, [...planningArgs(request, inputsFile), ...extra], callOptions(request, signal)));
+}
+function callOptions(request, signal) {
+    return {
+        cwd: request.cwd,
+        ...(request.env !== undefined ? { env: request.env } : {}),
+        ...(signal !== undefined ? { signal } : {}),
+    };
+}
+// ------------------------------------------------------------------------------------------------
+// Runs
+/** A file a run made, by digest. */
+export class RunFile {
+    digest;
+    /** The file kind (`image/png`, `json`, …). */
+    kind;
+    name;
+    size;
+    /** A collection item's key, if it has one. */
+    key;
+    /** Where the run placed it (an absolute path in the run folder), or null when no step of this
+     * run placed it (a workflow output that is one of its input files). Read it; never write it:
+     * it shares its bytes with the cache. */
+    path;
+    constructor(ref, path) {
+        if (typeof ref?.digest !== "string" || !/^[0-9a-f]{64}$/.test(ref.digest)) {
+            throw new FxError(`the run's record names a file by ${JSON.stringify(ref?.digest)}, which is not a digest`);
+        }
+        this.digest = ref.digest;
+        this.kind = ref.kind ?? "file";
+        this.name = ref.name ?? "";
+        this.size = ref.size ?? 0;
+        this.key = ref.key ?? null;
+        this.path = path;
+    }
+    /** The file's bytes. */
+    async read() {
+        if (this.path === null) {
+            throw new FxError(`the run placed no copy of ${this.name || this.digest} in its folder`);
+        }
+        return readFile(this.path);
+    }
+}
+/** A finished `run`: read from the engine's `project` and `inspect --json` of its folder. */
+export class RunResult {
+    /** The run folder, absolute. */
+    runDir;
+    /** The engine's exit status: 0 when the run is ok (and every `deliver` found its output). */
+    exitCode;
+    /** What `grida-fx run` printed: the plan and the run's summary. */
+    stdout;
+    /** The run's record, projected (`grida-fx project`). */
+    projection;
+    /** The run's summary (`grida-fx inspect --json`). */
+    inspection;
+    #outputs;
+    constructor(runDir, exit, projection, inspection) {
+        this.runDir = runDir;
+        this.exitCode = exit.status ?? -1;
+        this.stdout = exit.stdout;
+        this.projection = projection;
+        this.inspection = inspection;
+    }
+    get finished() {
+        return this.projection.run?.run_finished;
+    }
+    /** Whether every step that had to run succeeded and the run ended normally. */
+    get ok() {
+        return this.finished?.ok === true;
+    }
+    /** Whether the run stopped before everything ran (running it again continues it). */
+    get incomplete() {
+        const finished = this.finished;
+        return finished === undefined ? true : finished.incomplete === true;
+    }
+    /** What the run folder has been charged, in US dollars, over every invocation. */
+    get chargedUsd() {
+        return Number(this.inspection.run?.charged_usd ?? this.finished?.charged_usd ?? 0);
+    }
+    /** The ids of the instances that failed. */
+    get failed() {
+        return (this.finished?.failed ?? []).map(String);
+    }
+    /** Why the run stopped early, if it did. */
+    get stopped() {
+        return this.finished?.stopped ?? null;
+    }
+    /** Each instance's state, by instance id. */
+    get steps() {
+        return this.projection.instances ?? {};
+    }
+    /** Each declared output: a {@link RunFile}, a `Map` for a keyed collection, an array, a plain
+     * value, or null. */
+    get outputs() {
+        if (this.#outputs === undefined) {
+            const placed = new Map();
+            for (const step of this.inspection.run?.steps ?? []) {
+                for (const file of step.files ?? []) {
+                    if (!placed.has(file.digest)) {
+                        placed.set(file.digest, resolve(this.runDir, file.path));
+                    }
+                }
+            }
+            const outputs = {};
+            for (const [name, value] of Object.entries(this.finished?.outputs ?? {})) {
+                outputs[name] = decode(value, placed);
+            }
+            this.#outputs = outputs;
+        }
+        return this.#outputs;
+    }
+}
+/** A value of the run's record (fx-run-events-v1 `encoded`). */
+export function decode(encoded, placed) {
+    if (typeof encoded !== "object" || encoded === null || Object.keys(encoded).length !== 1) {
+        throw new FxError(`the run's record holds a value in no known form: ${JSON.stringify(encoded)}`);
+    }
+    if ("file" in encoded) {
+        return new RunFile(encoded.file, placed.get(encoded.file?.digest) ?? null);
+    }
+    if ("collection" in encoded) {
+        return new Map(encoded.collection.map(([key, item]) => [String(key), decode(item, placed)]));
+    }
+    if ("list" in encoded) {
+        return encoded.list.map((item) => decode(item, placed));
+    }
+    if ("none" in encoded) {
+        return null;
+    }
+    if ("value" in encoded) {
+        return encoded.value;
+    }
+    throw new FxError(`the run's record holds a value in no known form: ${JSON.stringify(encoded)}`);
+}
+/** The options `run` still takes with a {@link Plan}. */
+const RUN_ONLY = ["live", "yesUpTo", "runDir", "deliver", "signal"];
+/**
+ * Runs `target`, or a plan, after planning it: a plan with problems rejects with
+ * {@link PlanRefused} before any folder exists. `live: true` admits paid calls, within a
+ * ceiling. Then reads the folder back through `grida-fx project` and `inspect --json`.
+ */
+export async function run(target, options = {}) {
+    let request;
+    if (target instanceof Plan) {
+        const given = Object.entries(options)
+            .filter(([name, value]) => value !== undefined && !RUN_ONLY.includes(name))
+            .map(([name]) => name);
+        if (given.length > 0) {
+            throw new TypeError(`a Plan runs with the target and options it was planned with, so it takes no ` +
+                `${given.join(", ")}: plan again to change them`);
+        }
+        request = target.request;
+    }
+    else {
+        request = makeRequest(target, options);
+    }
+    const own = runArgs(options);
+    const signal = options.signal;
+    const planned = target instanceof Plan ? target : await planRequest(request, signal);
+    if (!planned.ok) {
+        throw new PlanRefused(planned);
+    }
+    const done = await withInputsFile(request, (inputsFile) => call(["run", ...planningArgs(request, inputsFile), ...own], callOptions(request, signal)));
+    if (done.status === INTERRUPTED) {
+        throw new FxError("the run was interrupted", {
+            exitCode: done.status,
+            stdout: done.stdout,
+            stderr: done.stderr,
+            args: done.args,
+        });
+    }
+    if (done.status !== 0 && done.status !== 1) {
+        throw failure("run", done);
+    }
+    const lines = done.stdout.split("\n");
+    const named = lines
+        .filter((line) => line.startsWith(RUN_LINE))
+        .map((line) => line.slice(RUN_LINE.length));
+    const folder = options.runDir ?? named.at(-1);
+    if (folder === undefined) {
+        const refused = lines.filter((line) => line.startsWith(REFUSED));
+        if (refused.length > 0) {
+            throw new FxError(refused.at(-1) ?? "refused", {
+                exitCode: done.status,
+                stdout: done.stdout,
+                stderr: done.stderr,
+                args: done.args,
+            });
+        }
+        const replanned = await planRequest(request, signal);
+        if (!replanned.ok) {
+            throw new PlanRefused(replanned);
+        }
+        throw failure("run", done);
+    }
+    const readOptions = callOptions(request, signal);
+    const projection = await project(folder, readOptions);
+    const inspection = await inspect(folder, readOptions);
+    return new RunResult(resolve(request.cwd, folder), done, projection, inspection);
+}
+/** `grida-fx project <run>`: a run's record projected to its state. */
+export async function project(runDir, options = {}) {
+    return document("project", [runDir], options, [0]);
+}
+/** `grida-fx inspect <run> --json`: a run's summary. `run` is a run folder, or a workflow id for
+ * its newest run. With `verify`, `verification` says whether every placed file still matches. */
+export async function inspect(run, options = {}) {
+    const args = [run, "--json", ...(options.verify === true ? ["--verify"] : [])];
+    return document("inspect", args, options, [0, 1]);
+}
+/** The engine's version (`grida-fx --version`), e.g. `0.1.0-alpha.1`. */
+export async function engineVersion(options = {}) {
+    const done = await call(["--version"], options);
+    if (done.status !== 0) {
+        throw failure("--version", done);
+    }
+    return done.stdout.trim().replace(/^grida-fx\s+/, "");
+}

package/dist/binary.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Finding the engine, the `grida-fx` binary. The `grida-fx` command this package installs and
+ * every function of the SDK find it the same way:
+ *
+ * 1. `GRIDA_FX_BIN`, when set and not empty: the path of a binary (relative to the working
+ *    directory). It must be a file.
+ * 2. The engine package for this machine (`@grida/fx-darwin-arm64`, …; see `platforms.ts`), an
+ *    optional dependency of `@grida/fx`: its `bin/grida-fx`.
+ *
+ * Nothing else: the command never looks on `PATH`, where it would find itself.
+ */
+/** The environment variable naming the binary to use. */
+export declare const BINARY_VARIABLE = "GRIDA_FX_BIN";
+/** An environment, as `process.env` holds it. */
+export type Environment = Readonly<Record<string, string | undefined>>;
+/** What finding the engine depends on, so it can be checked without the machine. */
+export interface EngineLookup {
+    readonly env: Environment;
+    /** `process.platform`. */
+    readonly os: string;
+    /** `process.arch`. */
+    readonly cpu: string;
+    /** Where a relative `GRIDA_FX_BIN` starts. */
+    readonly cwd: string;
+    /** The path of a package's `package.json`, as `require.resolve` finds it; throws when absent. */
+    resolvePackageJson(name: string): string;
+    /** Whether a path is a file. */
+    isFile(path: string): boolean;
+    /** Whether this Linux system's C library is musl rather than glibc (asked only on Linux). */
+    isMusl(): boolean;
+}
+/**
+ * The engine's path, as the module comment says; throws an {@link FxError} that says what to do
+ * when there is none.
+ */
+export declare function findEngine(lookup: EngineLookup): string;
+/** Options of {@link binary}. */
+export interface BinaryOptions {
+    /** Variables over `process.env` (a variable given `undefined` is removed). */
+    readonly env?: Environment;
+    /** Where a relative `GRIDA_FX_BIN` starts (default: the process's working directory). */
+    readonly cwd?: string;
+}
+/** The `grida-fx` binary the SDK drives, found as the module comment says. */
+export declare function binary(options?: BinaryOptions): string;
+/** The lookup of this machine and this installation of `@grida/fx`. */
+export declare function machineLookup(env: Environment, cwd: string): EngineLookup;
+/** `process.env` with `overrides` over it; a variable given `undefined` is removed. */
+export declare function mergeEnvironment(overrides: Environment | undefined): Record<string, string>;