envio 3.9.0 → 3.10.0-resolvers.1

package/evm.schema.json

@@ -29,6 +29,13 @@
         "null"
       ]
     },
+    "resolvers": {
+      "description": "Optional relative path to the custom GraphQL resolvers, either a single module (e.g. 'src/Resolvers.ts') or a directory (e.g. 'src/resolvers'), in which case every .js/.mjs/.ts file beneath it is loaded, tests excluded. The resolvers they export are served as additional root fields on the indexer's GraphQL endpoint.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "full_batch_size": {
       "description": "Target number of events to be processed per batch. Set it to smaller number if you have many Effect API calls which are slow to resolve and can't be batched. (Default: 5000)",
       "type": [
@@ -126,6 +133,17 @@
           "type": "null"
         }
       ]
+    },
+    "bytes_type": {
+      "description": "How the `Bytes` scalar in schema.graphql is represented. `hex` keeps 0x-prefixed hex strings stored as text, `uint8array` exposes `Uint8Array` values in handlers and stores raw bytes (BYTEA in Postgres, String in ClickHouse). (default: hex)",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BytesType"
+        },
+        {
+          "type": "null"
+        }
+      ]
     }
   },
   "additionalProperties": false,
@@ -758,6 +776,21 @@
         "checksum",
         "lowercase"
       ]
+    },
+    "BytesType": {
+      "description": "How the schema.graphql `Bytes` scalar reaches handlers and storage.",
+      "oneOf": [
+        {
+          "description": "`0x`-prefixed hex strings, stored as text.",
+          "type": "string",
+          "const": "hex"
+        },
+        {
+          "description": "`Uint8Array` values, stored as raw bytes (`BYTEA` in Postgres, `String` in ClickHouse).",
+          "type": "string",
+          "const": "uint8array"
+        }
+      ]
     }
   }
 }

package/fuel.schema.json

@@ -29,6 +29,13 @@
         "null"
       ]
     },
+    "resolvers": {
+      "description": "Optional relative path to the custom GraphQL resolvers, either a single module (e.g. 'src/Resolvers.ts') or a directory (e.g. 'src/resolvers'), in which case every .js/.mjs/.ts file beneath it is loaded, tests excluded. The resolvers they export are served as additional root fields on the indexer's GraphQL endpoint.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "full_batch_size": {
       "description": "Target number of events to be processed per batch. Set it to smaller number if you have many Effect API calls which are slow to resolve and can't be batched. (Default: 5000)",
       "type": [
@@ -83,6 +90,17 @@
         "boolean",
         "null"
       ]
+    },
+    "bytes_type": {
+      "description": "How the `Bytes` scalar in schema.graphql is represented. `hex` keeps 0x-prefixed hex strings stored as text, `uint8array` exposes `Uint8Array` values in handlers and stores raw bytes (BYTEA in Postgres, String in ClickHouse). (default: hex)",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BytesType"
+        },
+        {
+          "type": "null"
+        }
+      ]
     }
   },
   "additionalProperties": false,
@@ -464,6 +482,21 @@
           }
         }
       ]
+    },
+    "BytesType": {
+      "description": "How the schema.graphql `Bytes` scalar reaches handlers and storage.",
+      "oneOf": [
+        {
+          "description": "`0x`-prefixed hex strings, stored as text.",
+          "type": "string",
+          "const": "hex"
+        },
+        {
+          "description": "`Uint8Array` values, stored as raw bytes (`BYTEA` in Postgres, `String` in ClickHouse).",
+          "type": "string",
+          "const": "uint8array"
+        }
+      ]
     }
   }
 }

package/index.d.ts

@@ -1377,7 +1377,7 @@ type SvmNamedAccounts<
   Acc extends Readonly<Record<string, unknown>>,
   Fields extends SvmFieldsSelection,
 > = {
-  readonly [K in keyof Acc & string]: SvmInstructionAccount<Fields, K>;
+  readonly [K in keyof Acc]: SvmInstructionAccount<Fields, K & string>;
 };
 
 /** The parent transaction of a {@link SvmInstruction}, narrowed to the
@@ -1423,7 +1423,7 @@ type SvmSelectedInstruction<Fields extends SvmFieldsSelection, ProgInstr> = {
   readonly instructionName: string;
   readonly discriminator: string;
   readonly programId: SvmInstrField<Fields, "programId", string>;
-  readonly data: SvmInstrField<Fields, "data", string>;
+  readonly data: SvmInstrField<Fields, "data", Uint8Array>;
   readonly path: SvmInstrField<Fields, "path", readonly number[]>;
   readonly isInner: SvmInstrField<Fields, "isInner", boolean>;
   readonly args: SvmInstrField<
@@ -1484,6 +1484,37 @@ export type SvmOnInstructionHandlerArgs<
   Instruction extends keyof SvmProgramsT[Program] & string = never,
 > = SvmOnInstructionArgsFor<SvmInstruction<Fields, Program, Instruction>, GlobalConfig>;
 
+/** The named accounts of a configured instruction. Falls back to an open
+ * record when the instruction carries no resolved schema, so its filter keys
+ * are unconstrained rather than unusable. */
+type SvmAccountsOf<Program extends string, Instruction extends string> =
+  SvmConfiguredInstruction<Program, Instruction>["accounts"];
+
+/** One AND-group of account narrowings: every named account must match one of
+ * its listed pubkeys. Names are the instruction's own account names. */
+export type SvmAccountsFilter<Accounts> = {
+  readonly [K in keyof Accounts]?: string | readonly string[];
+};
+
+/** The `where` option value of `indexer.onInstruction`.
+ *
+ * `accounts` accepts either a single AND-group of account narrowings, or an
+ * array of them (OR semantics). `block.slot._gte` promotes to the
+ * registration's startBlock and overrides the chain-level `start_block` — use
+ * it to restrict per-instruction processing without touching `config.yaml`.
+ * Only `_gte` is supported here; use `indexer.onSlot` for `_lte` / `_every`. */
+export type SvmOnInstructionWhere<Accounts> = {
+  /** Match only inner (CPI-invoked) or only outer instructions. Absent
+   * matches both. */
+  readonly isInner?: boolean;
+  readonly accounts?: SvmAccountsFilter<Accounts> | readonly SvmAccountsFilter<Accounts>[];
+  readonly block?: {
+    readonly slot?: {
+      readonly _gte?: number;
+    };
+  };
+};
+
 /** Options for an SVM `indexer.onInstruction` registration. */
 export type SvmOnInstructionOptions<
   P extends string = string,
@@ -1493,10 +1524,11 @@ export type SvmOnInstructionOptions<
   /** Program name as declared under `chains[].programs[].name` in
    * `config.yaml`. */
   readonly program: P;
-  /** Instruction name as declared under
-   * `chains[].programs[].instructions[].name` in `config.yaml`. */
+  /** Instruction name from the program's IDL, or from
+   * `chains[].programs[].instructions[].name` when the layout is inline. */
   readonly instruction: I;
   readonly fields?: Fields & SvmFieldsLiteralCheck<Fields>;
+  readonly where?: SvmOnInstructionWhere<SvmAccountsOf<P, I>>;
 };
 
 /** Handler function for an SVM `indexer.onInstruction` registration. Takes
@@ -1736,9 +1768,10 @@ type SvmEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
           }
             ? {
                 /**
-                 * Register an instruction handler. Dispatch matches on
-                 * `(programId, discriminator)` from the YAML config.
-                 * Handler `fields` is the only source of payload selection.
+                 * Register an instruction handler. `program` and `instruction`
+                 * name an entry from the IDL or YAML. Dispatch uses that
+                 * instruction's discriminator. Handler `fields` is the only
+                 * source of payload selection.
                  */
                 readonly onInstruction: <
                   P extends keyof Programs & string,
@@ -1905,8 +1938,8 @@ type SvmSimulateItem<Config extends IndexerConfigTypes = GlobalConfig> =
             path?: readonly number[];
             /** Override the program id. Defaults to the configured `program_id`. */
             programId?: string;
-            /** Raw instruction data, `0x`-prefixed hex. */
-            data?: string;
+            /** Raw instruction data. Defaults to the configured discriminator bytes. */
+            data?: Uint8Array;
             /** Whether this is a CPI-invoked inner instruction. */
             isInner?: boolean;
             /** Decoded args. Keys match the instruction's arg names. */
@@ -1980,10 +2013,10 @@ type ConfigEntities<Config extends IndexerConfigTypes = GlobalConfig> =
 type PerChainEntityNames<Config extends IndexerConfigTypes = GlobalConfig> =
   Config extends { perChainEntities: infer Names extends string } ? Names : never;
 
-/** The row shape the chain-agnostic test-indexer operations exchange. A
- * per-chain entity's row is only identified together with its chain, so the
- * chain id travels alongside the entity fields. */
-type TestIndexerEntityRow<
+/** The row shape chain-agnostic APIs exchange. A per-chain entity's row is
+ * only identified together with its chain, so the chain id travels alongside
+ * the entity fields. */
+type ChainScopedEntityRow<
   Config extends IndexerConfigTypes,
   Name,
   Entity
@@ -2177,7 +2210,7 @@ export type TestIndexerFromConfig<Config extends IndexerConfigTypes = GlobalConf
 } & SingleEcosystemTestChains<Config> & {
   /** Entity operations for direct manipulation outside of handlers. */
   readonly [K in keyof ConfigEntities<Config>]: TestIndexerEntityOperations<
-    TestIndexerEntityRow<Config, K, ConfigEntities<Config>[K]>
+    ChainScopedEntityRow<Config, K, ConfigEntities<Config>[K]>
   >;
 };
 
@@ -2251,6 +2284,259 @@ export type EnumName = keyof EnumsT & string;
 /** Lookup an enum value type by name (e.g. `Enum<"AccountType">`). */
 export type Enum<TName extends EnumName> = EnumsT[TName];
 
+// ============== Custom Resolver Types ==============
+
+/** Handle for a custom GraphQL resolver created via {@link createResolver}. */
+export declare abstract class Resolver<Args, Output> {
+  protected opaque: Args | Output;
+}
+
+/** The selection the caller asked for: field names and their nesting, with
+ *  aliases and fragments already resolved away. A resolver may use it to skip
+ *  work it wasn't asked for — the response is projected against the declared
+ *  schema either way, so correctness never depends on honouring it. */
+export type ResolverSelection = { readonly [field: string]: ResolverSelection };
+
+/** Request metadata, forwarded by envio-serve. */
+export type ResolverContext = {
+  /** The role the operation was executed under. `admin: true` resolvers are
+   *  only reachable as `"admin"`. */
+  readonly role: "public" | "admin";
+  /** Correlates this field's work with the operation it belongs to. */
+  readonly requestId: string;
+  /** W3C trace context of the incoming request, when the caller sent one. */
+  readonly traceparent?: string;
+};
+
+/** How far a chain has been indexed. Read it to refuse to answer from a stale
+ *  index — `sourceBlock - progressBlock` is how far behind the head the
+ *  indexer is. */
+export type ChainHeight = {
+  readonly chainId: number;
+  /** `"evm"`, `"fuel"` or `"svm"`. Chain ids are only unique within one. */
+  readonly ecosystem: string;
+  readonly startBlock: number;
+  readonly endBlock: number | null;
+  /** The latest block seen on the chain. */
+  readonly sourceBlock: number;
+  /** The latest block fetched from the source. */
+  readonly bufferBlock: number;
+  /** The latest block whose events have been processed and committed. */
+  readonly progressBlock: number;
+  /** When the chain first caught up to the head, or null while it hasn't. */
+  readonly readyAt: Date | null;
+  readonly isReady: boolean;
+};
+
+/** Raw SQL, run under the resolver's `statement_timeout` and against its
+ *  bounded pool. */
+export type ResolverSql = {
+  /** ``db.sql`select 1` `` */
+  <Row = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): Promise<Row[]>;
+  /** `db.sql.unsafe(text, params)` — the direct lift for a query built as a
+   *  string with positional parameters. */
+  unsafe<Row = Record<string, unknown>>(
+    text: string,
+    params?: readonly unknown[],
+    options?: { readonly prepare?: boolean }
+  ): Promise<Row[]>;
+};
+
+/** Options accepted by `db.find`. */
+export type ResolverFindOptions<Entity> = {
+  /** Filter by field, with the same operators as `context.<Entity>.getWhere`.
+   *  Unlike `getWhere`, any field can be filtered on here — it is a query
+   *  against the table, so an unindexed field is a slow one, not an error. */
+  readonly where?: GetWhereFilter<Entity>;
+  readonly orderBy?: readonly {
+    readonly field: keyof Entity & string;
+    readonly direction: "asc" | "desc";
+  }[];
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+/** The database a resolver reads through. Every query it runs carries the
+ *  resolver's `timeoutMs` as a `statement_timeout` and takes one of the
+ *  process's bounded connections. */
+export type ResolverDb<Config extends IndexerConfigTypes = GlobalConfig> = {
+  /** Entities matching `where`, decoded exactly as a handler sees them. */
+  readonly find: <Name extends keyof ConfigEntities<Config> & string>(
+    entityName: Name,
+    options?: ResolverFindOptions<
+      ChainScopedEntityRow<Config, Name, ConfigEntities<Config>[Name]>
+    >
+  ) => Promise<
+    ChainScopedEntityRow<Config, Name, ConfigEntities<Config>[Name]>[]
+  >;
+  /** One entity by id, or null. Not available for per-chain entities, whose
+   *  key is the id together with a chain — use {@link ResolverDb.find}. */
+  readonly get: <
+    Name extends Exclude<
+      keyof ConfigEntities<Config> & string,
+      PerChainEntityNames<Config>
+    >
+  >(
+    entityName: Name,
+    id: EntityId<ConfigEntities<Config>[Name]>
+  ) => Promise<ConfigEntities<Config>[Name] | null>;
+  /** Raw SQL, for what the loaders don't express. */
+  readonly sql: ResolverSql;
+  /** The Postgres schema the indexer's tables live in. Raw SQL has to qualify
+   *  table names with it — it is not `"public"` on a hosted deployment. */
+  readonly pgSchema: string;
+  /** Several queries on one connection, under one timeout. */
+  readonly transaction: <T>(work: (sql: ResolverSql) => Promise<T>) => Promise<T>;
+  /** How far each chain has been indexed, keyed by chain id. */
+  readonly chainHeights: () => Promise<Record<string, ChainHeight>>;
+};
+
+/** Arguments passed to a {@link Resolver}'s handler. */
+export type ResolverHandlerArgs<
+  Args,
+  Config extends IndexerConfigTypes = GlobalConfig
+> = {
+  /** Coerced and validated against the declared arg schemas before the
+   *  resolver is reached. */
+  readonly args: Args;
+  readonly db: ResolverDb<Config>;
+  readonly selection: ResolverSelection;
+  readonly ctx: ResolverContext;
+};
+
+/**
+ * Declares a custom GraphQL resolver: a root query field served alongside the
+ * generated entity fields, backed by TypeScript in this project.
+ *
+ * Arguments and result are declared with the same `S` schemas effects use, and
+ * the GraphQL types are derived from them. A field is non-null unless its
+ * schema is optional. Object types must be named with {@link defineType} —
+ * GraphQL has no anonymous types.
+ *
+ * ```ts
+ * export const marketsAprByPeriod = createResolver({
+ *   name: "marketsAprByPeriod",
+ *   args: { periodStart: S.int32, periodEnd: S.int32 },
+ *   output: S.array(defineType("MarketApr", { marketAddress: S.string })),
+ *   timeoutMs: 30_000,
+ *   handler: async ({ args, db }) => db.find("MarketInfo"),
+ * });
+ * ```
+ */
+export function createResolver<
+  // Both are schemas at runtime: `createResolver` reads `output.t` and walks
+  // every argument with `toGraphQLType` while the module is being imported, so
+  // anything else fails at indexer startup rather than in the editor.
+  AS extends Record<string, Sury.Schema<unknown>>,
+  OS extends Sury.Schema<unknown>,
+  A = UnknownToOutput<AS>,
+  O = UnknownToOutput<OS>,
+  // A hack to enforce that the inferred return type matches the output schema.
+  R extends O = O
+>(options: {
+  /** The GraphQL field name. Must not collide with a generated one. */
+  readonly name: string;
+  /** Shown in the schema, for the people querying it. */
+  readonly description?: string;
+  /** Argument schemas, keyed by argument name. */
+  readonly args?: AS;
+  /** The result schema. Determines the field's GraphQL type. */
+  readonly output: OS;
+  /** Refuse the field to callers who cannot present a key from
+   *  `ENVIO_RESOLVERS_PRIVATE_KEYS` in the `x-envio-private-key` header. With
+   *  no keys configured it refuses everyone.
+   *
+   *  This hides the answers, not the field: Hasura will not route to an action
+   *  it does not publish, so a private resolver is on the public schema and its
+   *  name, arguments and result type stay visible to anonymous introspection.
+   *  A name that would itself disclose something does not belong here. */
+  readonly private?: boolean;
+  /** @deprecated The former spelling of `private`, and identical to it. */
+  readonly admin?: boolean;
+  /** Refuse to answer with a 503 when the index is further behind head than
+   *  this. A number applies to every chain; an object of chainId to blocks
+   *  applies per chain and ignores the chains it does not name — which is
+   *  usually what you want, since a few hundred blocks is seconds on one chain
+   *  and hours on another. Omitted, the resolver answers whatever the index
+   *  currently holds. */
+  readonly maxBlocksBehind?: number | Readonly<Record<number, number>>;
+  /** The `statement_timeout` every query this resolver runs is bounded by.
+   *  Required: it is the only thing bounding a runaway query. */
+  readonly timeoutMs: number;
+  readonly handler: (args: ResolverHandlerArgs<A>) => Promise<R>;
+}): Resolver<A, O>;
+
+/**
+ * Thrown by a resolver to put a specific error on the client's response.
+ *
+ * Anything else a handler throws is reported as an internal failure with its
+ * message withheld — a driver error can carry a connection string, and the
+ * caller is the public internet — so this is how a resolver says more than
+ * that. envio-serve carries the extensions through unchanged.
+ *
+ * ```ts
+ * throw new ResolverError("Service is syncing", {
+ *   code: "SERVICE_UNAVAILABLE",
+ *   httpStatus: 503,
+ * });
+ * ```
+ */
+export declare class ResolverError extends Error {
+  constructor(
+    message: string,
+    options?: {
+      /** Becomes `extensions.code`. Defaults to `"INTERNAL_SERVER_ERROR"`. */
+      readonly code?: string;
+      /** Becomes `extensions.http.status`. */
+      readonly httpStatus?: number;
+      /** Merged into `extensions` alongside `code`. */
+      readonly extensions?: Record<string, unknown>;
+    }
+  );
+  readonly code: string;
+  readonly httpStatus?: number;
+  readonly extensions?: Record<string, unknown>;
+}
+
+/** Names a schema so it can appear in the GraphQL schema as an object type. */
+export function defineType<F extends Record<string, unknown>>(
+  name: string,
+  fields: F
+): Sury.Schema<UnknownToOutput<F>>;
+
+/**
+ * Names a schema that appears in an argument.
+ *
+ * GraphQL keeps input and output types in a separate namespace from object
+ * types, so a `where` argument is declared with this rather than with
+ * {@link defineType}.
+ */
+export function defineInput<F extends Record<string, unknown>>(
+  name: string,
+  fields: F
+): Sury.Schema<UnknownToOutput<F>>;
+
+/** Every resolver declared so far, in declaration order. */
+export function getRegisteredResolvers(): readonly Resolver<unknown, unknown>[];
+
+/** The manifest and SDL for everything declared so far. */
+export function buildRegisteredManifest(): { manifest: unknown; sdl: string };
+
+/** Names a schema representing a GraphQL enum. */
+export function defineEnum<const V extends readonly string[]>(
+  name: string,
+  values: V
+): Sury.Schema<V[number]>;
+
+/** Names a schema representing a custom GraphQL scalar, such as `BigInt`. */
+export function defineScalar<T>(
+  name: string,
+  schema: Sury.Schema<T>
+): Sury.Schema<T>;
+
 // ============== Runtime values ==============
 
 /** The indexer instance. Register handlers with `indexer.onEvent`,

package/index.js

@@ -9,6 +9,16 @@ import { schema as bigDecimalSchema } from "./src/bindings/BigDecimal.res.mjs";
 
 export * from "./src/Envio.res.mjs";
 export { indexer, createTestIndexer } from "./src/Api.res.mjs";
+export {
+  createResolver,
+  defineType,
+  defineInput,
+  defineEnum,
+  defineScalar,
+  getRegisteredResolvers,
+  buildRegisteredManifest,
+  ResolverError,
+} from "./src/resolvers/index.js";
 export { default as BigDecimal } from "bignumber.js";
 
 // Important! Should match the index.d.ts file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.9.0",
+  "version": "3.10.0-resolvers.1",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -41,7 +41,6 @@
     "licenses"
   ],
   "dependencies": {
-    "@clickhouse/client": "1.17.0",
     "@elastic/ecs-pino-format": "1.4.0",
     "@fuel-ts/crypto": "0.96.1",
     "@fuel-ts/errors": "0.96.1",
@@ -69,10 +68,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.9.0",
-    "envio-linux-x64-musl": "3.9.0",
-    "envio-linux-arm64": "3.9.0",
-    "envio-darwin-x64": "3.9.0",
-    "envio-darwin-arm64": "3.9.0"
+    "envio-linux-x64": "3.10.0-resolvers.1",
+    "envio-linux-x64-musl": "3.10.0-resolvers.1",
+    "envio-linux-arm64": "3.10.0-resolvers.1",
+    "envio-darwin-x64": "3.10.0-resolvers.1",
+    "envio-darwin-arm64": "3.10.0-resolvers.1"
   }
 }

package/src/Batch.res

@@ -189,6 +189,15 @@ let addReorgCheckpoints = (
   }
 }
 
+// Checkpoint ids are handed out in ascending order as each chain's items are
+// walked in block order, so within a chain a higher id always means a later
+// block. Rollback preserves that: it deletes the chain's ids above its target
+// before any higher one is allocated, so the ids the re-indexed blocks get are
+// above everything the chain still holds. An isolated rollback leans on the
+// invariant — it deletes by `chain_id = c AND id > target`, which is only the
+// chain's stale suffix if ids and blocks agree on order within the chain. Ids
+// interleave freely *across* chains, which is exactly why that predicate can't
+// be the id bound alone.
 let prepareBatch = (
   ~checkpointIdBeforeBatch,
   ~chainsBeforeBatch: dict<chainBeforeBatch>,

package/src/Bin.res

@@ -18,11 +18,13 @@ type startCmd = {
 }
 type migrateCmd = {reset: bool, config: JSON.t}
 type dropSchemaCmd = {config: JSON.t}
+type resolversCmd = {mode: string, cwd: string, env: dict<JSON.t>, config: JSON.t}
 
 type command =
   | Start(startCmd)
   | Migrate(migrateCmd)
   | DropSchema(dropSchemaCmd)
+  | Resolvers(resolversCmd)
 
 let decodeCommand = (json: JSON.t): command => {
   let obj = switch json->JSON.Decode.object {
@@ -37,6 +39,7 @@ let decodeCommand = (json: JSON.t): command => {
   | "start" => Start(json->(Utils.magic: JSON.t => startCmd))
   | "migrate" => Migrate(json->(Utils.magic: JSON.t => migrateCmd))
   | "drop-schema" => DropSchema(json->(Utils.magic: JSON.t => dropSchemaCmd))
+  | "resolvers" => Resolvers(json->(Utils.magic: JSON.t => resolversCmd))
   | other => JsError.throwWithMessage(`Unknown command kind: ${other}`)
   }
 }
@@ -61,6 +64,12 @@ let run = async args => {
         Config.prime(config)
         processChdir(cwd)
         applyEnv(env)
+        // `envio dev` only — see ResolverProcess.startForDev. Deployed, the
+        // resolvers are their own service and are never started from here.
+        let loaded = Config.load()
+        if loaded.isDev {
+          let _ = await ResolverProcess.startForDev(~config=loaded, ~projectRoot=cwd)
+        }
         await Main.start(~reset)
       | Migrate({reset, config}) =>
         Config.prime(config)
@@ -68,6 +77,44 @@ let run = async args => {
       | DropSchema({config}) =>
         Config.prime(config)
         await Main.dropSchema()
+      | Resolvers({mode, cwd, env, config}) =>
+        Config.prime(config)
+        processChdir(cwd)
+        applyEnv(env)
+        switch mode {
+        | "manifest" => await ResolverProcess.writeManifest(~config=Config.load(), ~projectRoot=cwd)
+        | "metadata" =>
+          let handlerUrl = switch Env.Resolvers.publicUrl() {
+          | Some(url) => url
+          | None =>
+            JsError.throwWithMessage(
+              "ENVIO_RESOLVERS_PUBLIC_URL is not set. It is the URL Hasura posts to and is baked into every action, so the metadata cannot be printed without it.",
+            )
+          }
+          let metadata = await ResolverProcess.metadataJson(
+            ~config=Config.load(),
+            ~projectRoot=cwd,
+            ~handlerUrl,
+          )
+          // stdout, so it pipes into `hasura metadata apply` or `jq` rather
+          // than being buried in the log stream.
+          Console.log(JSON.stringify(metadata, ~space=2))
+        | "migrate" =>
+          let {applied, reasons} = await ResolverProcess.migrate(
+            ~config=Config.load(),
+            ~projectRoot=cwd,
+          )
+          Logging.info(
+            applied
+              ? `Updated Hasura to match these resolvers: ${reasons->Array.join("; ")}`
+              : "Hasura already matches these resolvers; nothing to update",
+          )
+        // Serving keeps the event loop alive on its own, so returning here
+        // leaves the process running rather than exiting.
+        | _ =>
+          let running = await ResolverProcess.serve(~config=Config.load(), ~projectRoot=cwd)
+          running->ResolverProcess.handleSignals
+        }
       }
     }
   } catch {