@vtex/faststore 0.0.6 → 0.0.7

package/dist/cli/index.d.ts

@@ -0,0 +1,350 @@
+import { GraphQLFieldResolver, GraphQLScalarType, GraphQLSchema } from "graphql";
+import * as esbuild from "esbuild";
+//#region ../graphql-compose/dist/subgraph-names.d.ts
+/**
+ * Subgraph name the bundled core SDL is composed under. Shared by the composer
+ * (which labels core's `join__Graph` value with it) and the dev router config
+ * (which keys core's header rules and TLS escape hatch off it), so the name a
+ * schema composes under is the name the router shapes headers for.
+ */
+export declare const CORE_SUBGRAPH_NAME = "storefront-api-core";
+//#endregion
+//#region src/cli/host.d.ts
+/**
+ * What a host hands the runner. The runner bundles with the host's esbuild twice: to load an
+ * author's TypeScript declaration (`validate`, `build`, `dev`) and to emit `server.mjs` (`build`).
+ * esbuild ships a native binary that cannot be bundled, so it is the host's dependency, not the
+ * SDK's (ADR-00020).
+ */
+type RunnerHost = {
+  esbuild: typeof esbuild;
+};
+//#endregion
+//#region src/cli/build.d.ts
+/**
+ * The result of a successful build: the emitted `dist/`, the server and the
+ * SDL slice inside it, and the composed artifacts — which live in scratch,
+ * never in `dist/`.
+ */
+type BuildResult = {
+  distDir: string;
+  serverFile: string;
+  sdlPath: string;
+  supergraphFile: string;
+  publicSchemaFile: string;
+};
+/** Raised when `validate` fails as `build`'s fail-closed gate — carries the aggregated report lines. */
+export declare class ValidationGateError extends Error {
+  readonly reportLines: string[];
+  constructor(reportLines: string[]);
+}
+/** Raised when the TypeScript compiler reports diagnostics — carries them formatted for verbatim output. */
+export declare class CompileError extends Error {
+  constructor(message: string);
+}
+/**
+ * Produces the deployable artifact for an extension: runs `validate` first as a
+ * fail-closed gate (any failure emits nothing and throws `ValidationGateError`),
+ * type-checks the extension, loads the declaration through the host's esbuild,
+ * writes `extension.graphql` from `printSubgraphSdl` of that declaration and
+ * bundles `server.mjs` into a staging dir under the `.vtex/storefront/` scratch
+ * dir, and only then swaps the assembled staging dir into `dist/`. `dist/` is
+ * therefore only ever absent, the previous complete artifact, or the new
+ * complete artifact — a failed build never leaves partial output or keeps
+ * stale files from an earlier build. Output is `server.mjs` + the SDL slice
+ * only — no `router.json`, and no composed artifact (Decision 1). Throws on
+ * any failure so the caller can surface it and exit non-zero.
+ *
+ * The composed artifacts go to `.vtex/storefront/` scratch instead, so a
+ * store's CI compile has a fresh client schema without a running `dev` loop.
+ * They are composed from the same slice `server.mjs` serves and written only
+ * after `dist/` is in place, so an emitted artifact always describes emitted
+ * output.
+ */
+export declare function buildExtension(extensionRoot: string, host: RunnerHost): Promise<BuildResult>;
+//#endregion
+//#region src/cli/capability-lint.d.ts
+/** The three forbidden reaches the capability lint enforces on first-party source. */
+type CapabilityRule = 'process-env' | 'fs-import' | 'child-process-import';
+/** One violation found in the author's first-party source. */
+type CapabilityFinding = {
+  file: string;
+  rule: CapabilityRule;
+  line: number;
+  column: number;
+};
+/**
+ * Walks the extension's first-party import graph from `entry` — following
+ * relative specifiers transitively, stopping at bare specifiers
+ * (`node_modules`) — and returns every capability violation (`process.env`
+ * access, `fs`/`child_process` imports). Throws when `entry` does not exist:
+ * this check is the authoritative gate (ADR-0002), so a misconfigured entry
+ * must fail closed, never pass as "no findings". Pure over the filesystem it
+ * reads: no `process.env` access, no mutation, no exit. The TypeScript
+ * compiler is loaded on first call, never at module load (see `typescript.ts`).
+ */
+export declare function lintExtension(entry: string): Promise<CapabilityFinding[]>;
+/** Formats a finding as a single `file:line:col — rule` line for humans. */
+export declare function formatFinding(finding: CapabilityFinding): string;
+//#endregion
+//#region src/cli/runner-env.d.ts
+type RunnerEnv = {
+  account?: string;
+  workspace: string;
+  token?: string;
+  coreUrl?: string;
+  subgraphPort: number;
+  routerPort: number;
+  insecureSkipTlsVerify: boolean;
+};
+//#endregion
+//#region src/cli/dev.d.ts
+type DevRunHandle = {
+  routerUrl: string;
+  stop: () => Promise<void>;
+  /**
+   * Watch-mode reload: restart the subgraph and recompose `supergraph.graphql`
+   * in place. The router hot-swaps the rewritten file (never restarted). The
+   * declaration is re-bundled, so an edit anywhere in its first-party module
+   * graph lands on a new bundle and is evaluated afresh. Concurrent calls run
+   * one after another, and `stop` waits for the one in flight.
+   */
+  reload: () => Promise<void>;
+};
+type RunDevOptions = {
+  /**
+   * Register process SIGINT/SIGTERM handlers that tear the run down and exit.
+   * True for a standalone `dev`; watch mode passes false and owns a single
+   * handler set across reloads (see `runDevWatch`).
+   */
+  registerSignals?: boolean;
+  /**
+   * When set, generate the router config with a supergraph poll interval (in
+   * seconds). Watch mode sets it so the router hot-swaps a recomposed
+   * `supergraph.graphql` without a restart.
+   */
+  watchSupergraphSeconds?: number;
+};
+/**
+ * Orchestrates the full `runDev` loop: loads the declaration, starts
+ * the subgraph server, composes it offline with the embedded core SDL, resolves
+ * the pinned Hive Router binary, and launches the router against the composed
+ * supergraph. Returns a handle so callers (the host, or tests) can await
+ * readiness and tear the loop down. `env` defaults to the extension's `.env` +
+ * `process.env`; tests inject one directly to skip file I/O.
+ *
+ * `watchSupergraphSeconds` writes the router config with a supergraph poll
+ * interval, so a subsequently recomposed `supergraph.graphql` is hot-swapped in
+ * place (watch mode uses this instead of restarting the router).
+ */
+export declare function runDev(extensionRoot: string, host: RunnerHost, env?: RunnerEnv, { registerSignals, watchSupergraphSeconds }?: RunDevOptions): Promise<DevRunHandle>;
+type DevWatchHandle = {
+  routerUrl: string;
+  stop: () => Promise<void>;
+};
+/**
+ * Runs the dev loop under a file watcher rooted at the declaration entry's
+ * directory. On save it restarts the subgraph (new resolvers/schema) and
+ * recomposes `supergraph.graphql`; the router is launched with a supergraph
+ * poll interval, so it picks that file up and hot-swaps the graph in place —
+ * gracefully, in-flight requests drain, no restart, no port re-bind. This is
+ * why reload never touches the router child.
+ *
+ * `fs.watch` has no ignore option, so generated paths are filtered in the
+ * change callback — otherwise the run's own writes into `.vtex/storefront/`
+ * would feed the loop back into itself.
+ *
+ * Owns a single SIGINT/SIGTERM handler set across reloads (`runDev` is started
+ * with `registerSignals: false`).
+ */
+export declare function runDevWatch(extensionRoot: string, host: RunnerHost, env?: RunnerEnv): Promise<DevWatchHandle>;
+//#endregion
+//#region src/graphql/types.d.ts
+/**
+ * The extension's entire resolver security surface — exactly five keys, and
+ * nothing more (see ADR-0003). `buildContext` assembles it from the inbound
+ * subgraph request plus the declared secrets; the Seam A key-set test pins
+ * that a resolver sees these five keys and no raw request state.
+ */
+type SubgraphContext = {
+  /** Canonical `x-vtex-account`, verbatim; `''` when absent (router-bypass). */
+  account: string;
+  /** Canonical `x-vtex-workspace`, verbatim; `''` when absent. */
+  workspace: string;
+  /**
+   * The curated allow-list of forwarded `x-vtex-*` headers (locale, segment,
+   * session) — never `authorization` (that is `token`) or the tenant pair
+   * (that is `account`/`workspace`). Values keep Node's `string | string[]`
+   * shape; absent allow-listed headers are omitted.
+   */
+  headers: Record<string, string | string[]>;
+  /** Forwarded `authorization` header, verbatim (no `Bearer`-stripping); `''` when absent. */
+  token: string;
+  /**
+   * The declared secret names present in the environment, mapped to their
+   * values. Undeclared and declared-but-unset names are both absent (open
+   * record — declared-names typing holds at runtime, not in TS generics).
+   */
+  secrets: Record<string, string | undefined>;
+};
+/**
+ * The same resolver map shape `buildSubgraphSchema` accepts, with the context an author's
+ * resolver actually receives as the default.
+ *
+ * `TContext` defaults to `SubgraphContext` rather than being fixed to `unknown`, because under
+ * `strictFunctionTypes` an `unknown` context makes the third argument contravariant, and that
+ * rejects the very annotation this type is meant to support:
+ * `(_parent, _args, ctx: SubgraphContext) => …` did not compile. Naming it also lets an
+ * unannotated `ctx` infer instead of widening to `unknown`.
+ *
+ * The runner passes `SubgraphResolvers<unknown>` where it hands the map to
+ * `buildSubgraphSchema`, whose own signature is context-agnostic (`GraphQLResolverMap<any>`).
+ *
+ * Restated locally, rather than imported from `@apollo/subgraph`'s `GraphQLResolverMap<unknown>`,
+ * so `./graphql` stays a zero-import island with no `@apollo/subgraph` dependency.
+ */
+type SubgraphResolvers<TContext = SubgraphContext> = {
+  [typeName: string]: {
+    [fieldName: string]: GraphQLFieldResolver<any, TContext> | {
+      requires?: string;
+      resolve?: GraphQLFieldResolver<any, TContext>;
+      subscribe?: GraphQLFieldResolver<any, TContext>;
+    };
+  } | GraphQLScalarType | {
+    [enumValue: string]: string | number;
+  };
+};
+/**
+ * The single primitive an extension author calls. `typeDefs` is plain SDL:
+ * the author writes `@key`/`@external` on entities they extend; the SDK
+ * injects the federation `@link` preamble, generates each entity's
+ * `__resolveReference`, and prefixes every name the extension contributes
+ * with `vendor_` (see `applyVendorPrefix` in `./vendor-prefix`).
+ */
+type SubgraphDefinition = {
+  /**
+   * Required. The publisher's VTEX vendor; validated `^[a-z][a-z0-9]*$`.
+   * Prefixes every name this subgraph contributes (entity-extension fields,
+   * root fields, and declared types) — applied by the SDK, never typed by
+   * the author. See ADR-0001.
+   */
+  vendor: string;
+  /** Defaults to the package name; the subgraph name used at compose time. */
+  name?: string;
+  /** Plain SDL, authored with bare names. The SDK applies the vendor prefix. */
+  typeDefs: string;
+  /** Core entities this subgraph extends (e.g. `['Product']`); must be on the bundled allow-list. */
+  extends: string[];
+  /** Author resolvers keyed by bare names; the SDK remaps keys to the prefixed names and merges __resolveReference. */
+  resolvers: SubgraphResolvers;
+  /**
+   * Env-var names this extension declares it needs. Their values populate
+   * `ctx.secrets` (read from `process.env`); undeclared names never reach a
+   * resolver. Optional — an extension with no secrets omits it. See ADR-0003.
+   */
+  secrets?: string[];
+};
+//#endregion
+//#region src/cli/load-declaration.d.ts
+/**
+ * Resolves the extension's declaration entry point: `src/index.ts` by
+ * convention, overridable via the extension package.json's `main` field.
+ */
+export declare function resolveDeclarationEntry(extensionRoot: string): string;
+//#endregion
+//#region src/cli/subgraph/build-subgraph.d.ts
+/**
+ * Turns a `SubgraphDefinition` into an executable Federation v2 subgraph
+ * schema: validates `vendor` and the `extends` allow-list, applies the
+ * vendor-prefix pass over `typeDefs`, injects the `@link` preamble when
+ * absent, generates an identity `__resolveReference` for each entity in
+ * `extends`, merges the author's resolvers (remapped to the prefixed field
+ * names), and hands the result to `buildSubgraphSchema`. Throws descriptive
+ * errors for the declared edge scenarios instead of letting a cryptic
+ * graphql-js error surface.
+ *
+ * Extension-contributed mutations execute independently of core mutations:
+ * federation gives no distributed-transaction guarantee across subgraphs, so
+ * a document mixing an extension mutation with a core mutation runs both
+ * non-atomically. Authors own idempotency/compensation for their own
+ * mutations (see the RFC's "Resolved v1 decisions").
+ */
+export declare function buildSubgraph(definition: SubgraphDefinition): GraphQLSchema;
+//#endregion
+//#region src/cli/subgraph/print-subgraph-sdl.d.ts
+/**
+ * The federation-form SDL slice: the author's `typeDefs` with the vendor
+ * prefix applied and the `@link` preamble applied (injected, unless already
+ * present) — the exact input handed to `composeSupergraph`, whether the caller
+ * is `validate`, `build` or the `dev` loop. Routes through the same prefix pass
+ * `buildSubgraph` uses so the compose-facing SDL matches the built schema
+ * byte-for-byte. Round-trips through `parse`/`print` so formatting is
+ * normalized.
+ */
+export declare function printSubgraphSdl(definition: SubgraphDefinition): string;
+//#endregion
+//#region src/cli/templates.d.ts
+/**
+ * A scaffold for a storefront extension. `files` renders every file of the
+ * scaffold, keyed by its path relative to the extension root; nothing here
+ * writes to disk — the host (`vtex extensions add`) decides where the files go
+ * and what to do when one already exists.
+ */
+type StorefrontTemplate = {
+  name: string;
+  description: string;
+  files(options: {
+    name: string;
+    vendor: string;
+  }): Record<string, string>;
+};
+/**
+ * The scaffolds `@vtex/faststore/cli` ships. One today, `default`: the
+ * `Product.reviews` sample every reference extension in this repository
+ * started from. A `vendor` that violates the vendor grammar is rejected up
+ * front, so a template never renders a declaration that would fail `validate`.
+ */
+export declare const templates: StorefrontTemplate[];
+//#endregion
+//#region src/cli/validate.d.ts
+/**
+ * The aggregated "am I shippable?" report: every capability finding, every
+ * composition error, and — when `buildSubgraph` itself rejects the
+ * declaration (allow-list, `vendor`, malformed typeDefs) — the build error.
+ * `ok` is true only when all three are clean.
+ */
+type ValidationReport = {
+  capability: CapabilityFinding[];
+  composition: Error[];
+  buildError?: Error;
+  ok: boolean;
+};
+/**
+ * Runs the full offline validation of an extension and returns the aggregated
+ * report — the shared core behind the host's `validate` verb and `build`'s
+ * fail-closed gate. It:
+ *
+ * 1. loads the declaration through the host's esbuild (the same
+ *    `loadDeclaration` `dev` uses),
+ * 2. builds the subgraph (allow-list rejection and `vendor` validation surface
+ *    here as a thrown error, captured into `buildError`),
+ * 3. runs the capability `lintExtension` over first-party source, and
+ * 4. runs the in-process `composeCheck` of the emitted SDL slice against the
+ *    embedded core SDL.
+ *
+ * It never short-circuits: a build error still lets the capability lint run,
+ * and both are reported together. No network I/O, no router binary — the
+ * composition check is `@theguild/federation-composition` in-process, the same
+ * composer `dev` and the core SDL CI gate call (ADR-0004, D1).
+ */
+export declare function validateExtension(extensionRoot: string, host: RunnerHost): Promise<ValidationReport>;
+/**
+ * Renders a `ValidationReport`'s failures as human-readable lines, grouped by
+ * category (build/allow-list, capability, composition) — every failure in one
+ * pass, never short-circuited at the first. Returns an empty array for a clean
+ * report so the caller prints its own success line.
+ */
+export declare function formatValidationReport(report: ValidationReport): string[];
+//#endregion
+export type { BuildResult, CapabilityFinding, CapabilityRule, DevRunHandle, DevWatchHandle, RunnerHost, StorefrontTemplate, ValidationReport };
+//# sourceMappingURL=index.d.ts.map