@vtex/faststore 0.0.6 → 0.0.8

package/dist/cli/index.d.ts

@@ -0,0 +1,799 @@
+import { GraphQLFieldResolver, GraphQLScalarType, GraphQLSchema } from "graphql";
+//#region ../../node_modules/.pnpm/@vtex+extension-cli-kit@0.1.1/node_modules/@vtex/extension-cli-kit/dist/finding.d.ts
+type Severity = 'error' | 'warning' | 'info';
+/** A place in a file, 1-based, as editors show it. */
+type Position = {
+  line: number;
+  column: number;
+};
+type Range = {
+  start: Position;
+  end: Position;
+};
+/**
+ * Every result of a check, from the core or from a kind provider (RFC-0003 §Conventions). It renders
+ * as text, as JSON and as an editor problem.
+ */
+type Finding = {
+  /** Stable, kebab-case: what was found, not where. */
+  code: string;
+  severity: Severity;
+  message: string;
+  /** A JSON pointer inside `file`; `''` is the whole file. */
+  path: string;
+  /** Relative to the Account Repo root. */
+  file: string;
+  range?: Range;
+  /** One line that says what the available fix does. */
+  fix?: string;
+  /** A URL that explains the rule. */
+  docs: string;
+};
+//#endregion
+//#region ../../node_modules/.pnpm/@vtex+extension-cli-kit@0.1.1/node_modules/@vtex/extension-cli-kit/dist/command.d.ts
+/**
+ * A flag a command declares. The core adds the global flags, gives every flag a
+ * `VTEX_EXTENSION_FLAG_*` variable, and applies `default`, `required` and `options`.
+ */
+type FlagDefinition = {
+  type: 'boolean';
+  description: string;
+  default?: boolean;
+} | {
+  type: 'string';
+  description: string;
+  default?: string;
+  required?: boolean;
+  options?: readonly string[];
+};
+/** Resolved flag values by flag name: from argv, then the variable, then `default`. */
+type FlagValues = Record<string, string | boolean | undefined>;
+/**
+ * What `run` returns: data, or the Findings of a check. `text` is the data as a terminal shows it;
+ * without it the core prints the data as JSON.
+ */
+type CommandResult<T = unknown> = {
+  data: T;
+  text?: string;
+} | {
+  findings: Finding[];
+};
+/**
+ * A command as plain data. The core parses its flags, renders its result and sets the exit code;
+ * `run` never prints.
+ */
+type CommandDefinition<Input, Context> = {
+  /** A kebab-case verb. */
+  name: string;
+  /** One sentence, shown in every command list. */
+  summary: string;
+  description?: string;
+  /** Full command lines, starting with `vtex extension <name>`, without a `$`. */
+  examples: readonly string[];
+  flags: Record<string, FlagDefinition>;
+  run(input: Input, ctx: Context): Promise<CommandResult>;
+};
+//#endregion
+//#region ../../node_modules/.pnpm/@vtex+extension-cli-kit@0.1.1/node_modules/@vtex/extension-cli-kit/dist/kinds.d.ts
+/** RFC-0001's closed set of kinds. A new kind arrives by its own RFC. */
+export declare const kinds: readonly ['storefront', 'widget', 'instructions', 'workflow', 'agent', 'function'];
+/** One of the six kinds an `asset.yaml` may declare. */
+type Kind = (typeof kinds)[number];
+//#endregion
+//#region ../../node_modules/.pnpm/@vtex+extension-cli-kit@0.1.1/node_modules/@vtex/extension-cli-kit/dist/provider.d.ts
+/**
+ * The kind provider contract version this kit describes. A provider declares the version it
+ * implements as `contract`; the CLI checks it against the range it supports.
+ */
+export declare const providerContractVersion = 0;
+/** A JSON Schema (draft 2020-12), as a plain value. */
+type JsonSchema = boolean | Readonly<Record<string, unknown>>;
+/** One Asset as a provider sees it: plain data, a copy. Its envelope is valid. */
+type ProviderAsset = {
+  /** `<ext>/<asset>`, as targets name it. */
+  target: string;
+  /** Its extension; `path` is `extensions/<folder>`. */
+  extension: {
+    name: string;
+    vendor?: string;
+    version?: string;
+    path: string;
+  };
+  name: string;
+  kind: Kind;
+  apiVersion: string;
+  /** The Asset's folder, absolute. */
+  dir: string;
+  /** Its `asset.yaml`, relative to the Account Repo root: the `file` of a Finding about it. */
+  file: string;
+  /** Relative to the extension's folder. */
+  path: string;
+  /** On disk, not listed in the inventory. */
+  staged: boolean;
+  /** The whole `asset.yaml` value, envelope included. */
+  manifest: Readonly<Record<string, unknown>>;
+  /** The Asset folder's own `package.json`, when it has one. */
+  packageJson?: Readonly<Record<string, unknown>>;
+  /**
+   * In `dev`, `build` and kind commands, the Asset's environment: `.env` then `.env.local` in the
+   * repo root, the extension's folder and the Asset's folder (a later file wins), then the
+   * environment the CLI runs with, which wins. Absent in `validate`.
+   */
+  env?: Readonly<Record<string, string>>;
+};
+/** One Asset a provider build gets: a `ProviderAsset` with the folder to write into. */
+type BuildAsset = ProviderAsset & {
+  /**
+   * Where to write the Asset's output, absolute: its staging folder,
+   * `<output root>/<ext>/<asset>.building/`. The core creates it empty before the call, renames it
+   * to the Asset's output folder, `<output root>/<ext>/<asset>/`, when the Asset is built, and
+   * removes it when the Asset fails. Do not record this path in the output: it is gone once the
+   * Asset is built.
+   */
+  outDir: string;
+};
+/** The whole Account Repo as plain data: inventory Assets only, no YAML objects. */
+type ProviderRepo = {
+  /** Absolute. */
+  root: string;
+  accounts: readonly {
+    name?: string;
+    /** `stores/<store>`. */
+    store?: string;
+    /** The `installed:` entries as written, `vendor.name@<range>`. */
+    installed: readonly string[];
+  }[];
+  extensions: readonly {
+    name: string;
+    vendor?: string;
+    version?: string;
+    /** `extensions/<folder>`. */
+    path: string;
+    /** In inventory order. `path` is relative to the extension's folder. */
+    assets: readonly {
+      name?: string;
+      kind?: string;
+      path: string;
+      packageName?: string;
+    }[];
+  }[];
+  stores: readonly {
+    name: string;
+    /** `stores/<name>`. */
+    path: string;
+    packageName?: string;
+    /** The keys of its `package.json › dependencies`. */
+    dependencies: readonly string[];
+  }[];
+};
+/** Everything the core hands a provider. */
+type ProviderContext = {
+  /** The Account Repo root, absolute. */
+  root: string;
+  repo: ProviderRepo;
+  /** `--account`, when given. */
+  account?: string;
+  /**
+   * Environment for code the provider runs. `{}` in `validate`. In `dev`, `build` and kind
+   * commands, the repo root's `.env` and `.env.local`, then the environment the CLI runs with. Each
+   * Asset's own is `ProviderAsset.env`.
+   */
+  env: Readonly<Record<string, string>>;
+  /** A progress message. The core labels it with the provider and routes it; a provider never prints. */
+  log(message: string): void;
+};
+/**
+ * One RFC 6902 operation on the `asset.yaml` a Finding names, by JSON pointer into its kind body.
+ * The core never applies one to an envelope field (`apiVersion`, `name`, `kind`, `policies`).
+ */
+type PatchOperation = {
+  op: 'add' | 'replace';
+  path: string;
+  value: unknown;
+} | {
+  op: 'remove';
+  path: string;
+};
+/**
+ * What `validate` and `build` return: a Finding that, with `fix`, may carry the edits that apply
+ * it. The core drops a `patch` from a `build` Finding.
+ */
+type ProviderFinding = Finding & {
+  patch?: readonly PatchOperation[];
+};
+/** What a template is written for. */
+type TemplateInput = {
+  vendor: string;
+  extension: string;
+  asset: string;
+  /**
+   * The new Asset's `package.json › name`, `@<vendor>/<extension>-<asset>`. A declarative Asset has
+   * no `package.json`: this is the name it would have.
+   */
+  packageName: string;
+  apiVersion: string;
+};
+/** The `package.json` fields a template's `packages` installs into. */
+type TemplateDependencyField = 'dependencies' | 'devDependencies' | 'peerDependencies';
+/** The packages a template installs, by dependency field: package name → spec, as `pnpm add` takes it. */
+type TemplatePackages = Readonly<Partial<Record<TemplateDependencyField, Readonly<Record<string, string>>>>>;
+/** What `vtex extension add --kind <kind> --template <name>` writes for a new Asset. */
+type Template = {
+  /** Kebab-case. `default` is the one `add` uses without `--template`. */
+  name: string;
+  /** One sentence, shown in a list of templates. */
+  summary: string;
+  /**
+   * The kind body fields of the new `asset.yaml`, below the envelope: never `apiVersion`, `name`,
+   * `kind` or `policies`.
+   */
+  body(input: TemplateInput): Record<string, unknown>;
+  /**
+   * Files to write, by path relative to the Asset's folder (`/`-separated) → content. Never
+   * `asset.yaml` or `package.json`, which the core writes. The core never overwrites a file.
+   */
+  files?(input: TemplateInput): Record<string, string>;
+  /**
+   * For a runnable kind: the packages `add` installs into the new Asset's package once the body
+   * and files are written, by dependency field, each `<name>: <spec>`. One `pnpm add` per field,
+   * plain for `dependencies` and `-D` for the other two, so `package.json` records the range pnpm
+   * writes for a dependency or a devDependency. A peer is different: `add` writes its range to
+   * `peerDependencies` as given, since it declares what the host must have, and `pnpm add -D`
+   * installs its dev copy. Never the kind's SDK, which `add` installs before it loads the provider.
+   * A declarative kind's template has none: its Asset has no `package.json`.
+   */
+  packages?: TemplatePackages;
+  /**
+   * For a runnable kind: other `package.json` fields `add` sets in the new Asset's package, such as
+   * `type`, `exports` and `scripts`, merged at the top level as plain JSON. Never `name`, `version`
+   * or `private`, which the core writes, nor a dependency field (`dependencies`, `devDependencies`,
+   * `peerDependencies`, `optionalDependencies`), which `packages` and pnpm own. A declarative
+   * kind's template has none.
+   */
+  packageJson?: Readonly<Record<string, unknown>>;
+};
+/**
+ * A provider skill: an Agent Skills folder that teaches a coding agent working in the Account Repo
+ * how to write Assets of the kind. The folder ships in the provider's package and holds a
+ * `SKILL.md`, plus any file it points to. `vtex extension skills`, and `add` when you agree, copy it
+ * to `.agents/skills/<name>/` and link `.claude/skills/<name>` to that copy.
+ */
+type ProviderSkill = {
+  /** Kebab-case, as `SKILL.md`'s `name`; the folder name in the repo. Prefix it with the kind. */
+  name: string;
+  /** The folder in the provider's package, absolute: `fileURLToPath(new URL(..., import.meta.url))`. */
+  dir: string;
+};
+/**
+ * How far an Asset of a dev session has come. The core sets `starting` right before it calls the
+ * provider instance's `dev`; the adapter reports `ready` or `failed`. Provisional, as the session
+ * file is.
+ */
+type AssetState = 'starting' | 'ready' | 'failed';
+/**
+ * What a dev adapter reports through, by Asset target (`<ext>/<asset>`), for the Assets its `dev`
+ * was handed. The core writes each status and Findings change to the session file and prints every
+ * call in the session's stream. A call for another Asset, a state outside `AssetState`, or
+ * `details` JSON cannot hold is ignored, with a line in the stream saying why; calls after the
+ * session stopped are ignored. Provisional.
+ */
+type DevSession = {
+  /** One line, or several, in the stream under the Asset's target. */
+  log(target: string, message: string): void;
+  /** The Asset's state; `details` (a URL, the functions it serves) replaces the last ones. */
+  status(target: string, state: AssetState, details?: Readonly<Record<string, unknown>>): void;
+  /**
+   * Replaces the Asset's Findings. Each one is checked as `validate` checks a provider's; an
+   * invalid one becomes a `provider-invalid` Finding. A `patch` is dropped.
+   */
+  findings(target: string, findings: readonly Finding[]): void;
+};
+/**
+ * A running dev adapter. The core calls `stop` once, when the session ends (Ctrl-C), for every
+ * adapter at the same time, and waits for it. A rejection is reported, never retried. Provisional.
+ */
+type AdapterHandle = {
+  stop(): Promise<void>;
+};
+/** What a kind command runs on: the provider instance's selected Assets and the parsed flags. */
+type KindCommandInput = {
+  /** The selected Assets of the kind that load this provider instance, in repo order. */
+  assets: readonly ProviderAsset[];
+  /**
+   * The verb's own flags only, resolved: argv, then `VTEX_EXTENSION_FLAG_*`, then `default`.
+   * `--account` reaches the verb as `ctx.account`.
+   */
+  flags: FlagValues;
+};
+/**
+ * A verb a provider adds under `vtex extension <kind> <verb>`. Its `name` is kebab-case and unique
+ * among the provider's commands; it has a `summary` and at least one example, each starting with
+ * `vtex extension <kind> <name>`. Its `flags` are kebab-case, and none is `json`, `quiet`,
+ * `fields`, `dry-run`, `yes`, `account` or `help`, which the core owns. The core runs it once per
+ * provider instance, with that instance's selected Assets. `run` returns data, which the core
+ * prints as the command's output, or Findings, which it renders as `validate` does (a `patch` is
+ * ignored). With Assets on several SDK versions, the output is one item per provider instance.
+ */
+type KindCommand = CommandDefinition<KindCommandInput, ProviderContext>;
+/**
+ * The code that understands one kind (RFC-0003 §The kind provider contract). A runnable kind's
+ * provider is the default export of its SDK's `./cli` entry; a declarative kind's comes from the
+ * declarative package at the repo root, as the default export of its `./<kind>/cli` entry.
+ * The core calls `validate`, `dev`, `build` and kind commands once per provider instance, with all
+ * of that instance's selected Assets.
+ */
+type KindProvider = {
+  /** The contract version it implements. */
+  contract: typeof providerContractVersion;
+  kind: Kind;
+  /** The `asset.yaml` apiVersions it understands. */
+  apiVersions: readonly string[];
+  /** Where the kind is documented; layer-3 Findings link here. */
+  docs: string;
+  /** The kind body's schema: `asset.yaml` without `apiVersion`, `name`, `kind` and `policies`. */
+  schema(apiVersion: string): JsonSchema;
+  templates: readonly Template[];
+  /** The provider skills it offers; none when absent. */
+  skills?: readonly ProviderSkill[];
+  /** Kind lints. Never prints and never writes; a Finding with `fix` may carry a `patch`. */
+  validate?(assets: readonly ProviderAsset[], ctx: ProviderContext): ProviderFinding[] | Promise<ProviderFinding[]>;
+  /**
+   * Starts one dev adapter for all of its Assets in a dev session (`vtex extension dev`), or says
+   * it has nothing to run (`'none'`). Called once per provider instance, with the instance's
+   * selected Assets that passed validation, in repo order, each with its `env`; the instances start
+   * side by side. It reports through `session` and never prints. A throw or a rejection is a
+   * `provider-failed` Finding on each of its Assets, which then do not start; the session goes on
+   * with the others. Provisional.
+   */
+  dev?(assets: readonly ProviderAsset[], session: DevSession, ctx: ProviderContext): Promise<AdapterHandle> | 'none';
+  /**
+   * Builds its Assets for `vtex extension build`. Called once per provider instance, with the
+   * instance's selected Assets that validation did not block, in repo order, each with its `env`
+   * and `outDir`, the staging folder the core renames to the Asset's output folder once the Asset
+   * is built; the instances build side by side. It writes each Asset's output into its `outDir`
+   * only, and never prints. It returns Findings, checked as `validate`'s; a `patch` is
+   * dropped. A throw or a rejection is `provider-failed`, and a return that is not a list of valid
+   * Findings is `provider-invalid`, on each of its Assets. Absent: its Assets have nothing to build.
+   */
+  build?(assets: readonly BuildAsset[], ctx: ProviderContext): ProviderFinding[] | Promise<ProviderFinding[]>;
+  /** Verbs only this kind has: `vtex extension <kind> <verb>` runs them. */
+  commands?: readonly KindCommand[];
+};
+//#endregion
+//#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/log.d.ts
+/**
+ * The sink the runner reports through. Nothing under `src/cli/` prints: a host
+ * passes one of these and decides where each line goes (ADR-0026). Three
+ * levels because the runner distinguishes them — progress, `⚠` warnings and
+ * failures — and the stand-in host keeps its stdout/stderr split; the kind
+ * provider collapses all three into the contract's single `log`.
+ */
+type RunnerLog = {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+};
+//#endregion
+//#region src/cli/build.d.ts
+/**
+ * The API side of a build: the server and the SDL slice inside `outDir`, and
+ * the composed artifacts — which live in scratch, never in `outDir`.
+ */
+type ApiBuildOutput = {
+  serverFile: string;
+  sdlPath: string;
+  supergraphFile: string;
+  publicSchemaFile: string;
+};
+/**
+ * The UI side of a build: the catalog and, when the addon emitted one, the
+ * content types, both at the top of `outDir`; the flat `docs/` folder and how
+ * many component docs landed in it.
+ */
+type UiBuildOutput = {
+  catalogPath: string;
+  contentTypesPath: string | null;
+  docsDir: string;
+  catalogEntries: number;
+  docs: number;
+};
+/** The result of a successful build: the folder it emitted into, and a side for each the Asset has. */
+type BuildResult = {
+  outDir: string;
+  api?: ApiBuildOutput;
+  ui?: UiBuildOutput;
+};
+/** 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[]);
+}
+type BuildOptions = {
+  /** Where the composed-artifact lines go. Silent when omitted: nothing in the runner prints (ADR-0026). */
+  log?: RunnerLog;
+  /** The output folder, absolute or relative to the Asset root; `dist` when omitted. `vtex extension build` passes `.vtex/build/<ext>/<asset>/`. */
+  outDir?: 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 output for a storefront Asset, both sides into the
+ * folder the caller names: `server.mjs` and the SDL slice for the API side,
+ * `catalog.json` (and `content-types.json` when the addon emitted one) with
+ * the component docs flat under `docs/` for the UI side (ADR-0026). `outDir`
+ * is `dist` under the root unless passed; `vtex extension build` passes the
+ * folder it chose, `.vtex/build/<ext>/<asset>/` by default. An `outDir` equal
+ * to the root or containing it is refused before anything runs, since the swap
+ * below empties it. An Asset with neither side throws: there is nothing to
+ * build.
+ *
+ * The UI side's `catalog.json` (and `content-types.json`) also land in the
+ * folder the Asset's `exports["./catalog.json"]` names, `dist/` by the
+ * template: that export is how a store finds the Asset (ADR-0007), so a store
+ * builds against a built Asset with no `dev` loop having run. Nothing is
+ * copied when `outDir` already is that folder.
+ *
+ * Everything that can fail runs before a byte of output exists: the API side's
+ * `validate` gate, type-check, declaration load and compose; the UI side's
+ * addon load and docs plan (a basename collision throws here). Both sides then
+ * write into one staging dir under the `.vtex/storefront/` scratch dir — the
+ * SDL and the bundled server, the catalog built with `kind: 'extension'` (an
+ * Asset named `@vtex/faststore` fails as the Core package it is not) and the
+ * docs copy — and only then is the staging dir swapped into `outDir`. `outDir`
+ * is therefore only ever absent, the previous complete output, or the new
+ * complete output — a failed build never leaves partial output or keeps stale
+ * files from an earlier build. The UI side emits no JavaScript: the store
+ * compiles the components it imports. 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 `outDir` is in place, so an emitted artifact always describes emitted
+ * output. A UI-only Asset composes nothing.
+ */
+export declare function buildExtension(extensionRoot: string, { log, outDir: outDirOption }?: BuildOptions): 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;
+  /** The Hive Router release `dev` runs: `VTEX_STOREFRONT_ROUTER_VERSION`, else the pin kramer runs. */
+  routerVersion: string;
+  /** `VTEX_STOREFRONT_ROUTER_BINARY`: a router binary to run verbatim instead of the cached or downloaded one. */
+  routerBinary?: string;
+  /**
+   * The boot snapshot of the map the host passed: `captureSecrets` reads the
+   * declared secrets from it on boot and on every reload, and the router child
+   * inherits it minus those secrets (`routerEnvironment`). Never the live
+   * `process.env`.
+   */
+  variables: Readonly<Record<string, string | undefined>>;
+};
+/**
+ * Reads the runner's env contract from the map the host passes — the runner
+ * reads no `.env` and no `process.env` itself (ADR-0026). Throws when neither
+ * `VTEX_ACCOUNT` nor `STOREFRONT_CORE_URL` is set — the runner cannot derive a
+ * core routing URL without one of the two.
+ */
+export declare function loadRunnerEnv(env: Readonly<Record<string, string | undefined>>): RunnerEnv;
+//#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 = {
+  /** Where progress, warnings and failures go. Silent when omitted: nothing in the runner prints (ADR-0026). */
+  log?: RunnerLog;
+  /**
+   * 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. The host passes `env` (`loadRunnerEnv` over
+ * the map it assembled) and owns signals and exit: `stop()` is the only
+ * teardown (ADR-0026).
+ *
+ * `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, env: RunnerEnv, { log, watchSupergraphSeconds }?: RunDevOptions): Promise<DevRunHandle>;
+type DevWatchHandle = {
+  routerUrl: string;
+  stop: () => Promise<void>;
+};
+type DevWatchOptions = {
+  /** Where progress, warnings and failures go. Silent when omitted: nothing in the runner prints (ADR-0026). */
+  log?: RunnerLog;
+};
+/**
+ * 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.
+ *
+ * Like `runDev`, it installs no signal handler: the host calls `stop()`.
+ */
+export declare function runDevWatch(extensionRoot: string, env: RunnerEnv, { log }?: DevWatchOptions): 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/provider.d.ts
+/**
+ * The storefront kind provider: the default export of `@vtex/faststore/cli`, written to contract
+ * version 0 (`@vtex/extension-cli-kit`), which `vtex extension` loads from each storefront Asset's
+ * own `@vtex/faststore` (ADR-0026). It wraps the runner's named exports.
+ *
+ * Like the rest of the runner, it prints nothing, reads no `process.env` and installs no signal
+ * handler: `process-isolation.test.ts` walks this file with the others.
+ */
+declare const storefrontProvider: KindProvider;
+//#endregion
+//#region src/cli/skills.d.ts
+/**
+ * The provider's skills, written to contract version 0 (`@vtex/extension-cli-kit`): the Agent Skills
+ * folders that teach a coding agent in an Account Repo to write storefront Assets. `vtex extension
+ * skills`, and `add` once you agree, copy each folder to `.agents/skills/<name>/` and link
+ * `.claude/skills/<name>` to it; nothing in a folder is code this package runs. `dir` is resolved
+ * against the built entry, `dist/cli/index.js`, which tsdown bundles this module into, so `../../`
+ * lands on the package root from source and from `dist/` alike.
+ */
+/** The one skill: `skills/storefront-asset/`, a `SKILL.md` and the references it points to. */
+export declare const skills: readonly ProviderSkill[];
+//#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
+/**
+ * The two templates: `default`, the API side `add` writes without `--template`, and `ui`. The
+ * storefront body is empty, so each `body` is `{}`. A `vendor` that violates the vendor grammar
+ * is rejected up front, so a template never renders a declaration that would fail `validate`.
+ *
+ * `typescript` is pinned to the SDK's optional peer range: `validate` and `dev` load the compiler
+ * from the Asset's devDependencies. `graphql` is pinned to the SDK's own range so the Asset holds
+ * one copy: graphql-js rejects a schema built by another copy of itself, which is exactly what
+ * the scaffolded test does. `react` is a peer because the store app renders the components.
+ */
+export declare const templates: readonly Template[];
+//#endregion
+//#region src/cli/typescript.d.ts
+/**
+ * Raised when the Asset's `typescript` cannot serve the capability lint or the
+ * type-check: it is not installed, or the module that loads has no compiler
+ * API (`typescript@7` exports `lib/version.cjs` and no `createSourceFile`).
+ * `validateExtension` turns it into `ValidationReport.typescript` instead of
+ * failing the whole run (ADR-0026, TypeScript 5 through the peer).
+ */
+export declare class TypeScriptUnavailableError extends Error {
+  constructor(message: string);
+}
+//#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.
+ * `typescript` is set when the Asset's `typescript` is missing or has no
+ * TypeScript 5 compiler API: the capability lint did not run, and
+ * `capability` is empty. `ok` is true only when all four are clean.
+ */
+type ValidationReport = {
+  capability: CapabilityFinding[];
+  composition: Error[];
+  buildError?: Error;
+  typescript?: 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 runner'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): Promise<ValidationReport>;
+/**
+ * Renders a `ValidationReport`'s failures as human-readable lines, grouped by
+ * category (typescript, 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 AdapterHandle, type ApiBuildOutput, type AssetState, type BuildAsset, type BuildOptions, type BuildResult, type CapabilityFinding, type CapabilityRule, type CommandDefinition, type CommandResult, type DevRunHandle, type DevSession, type DevWatchHandle, type DevWatchOptions, type Finding, type FlagDefinition, type FlagValues, type JsonSchema, type Kind, type KindCommand, type KindCommandInput, type KindProvider, type PatchOperation, type Position, type ProviderAsset, type ProviderContext, type ProviderFinding, type ProviderRepo, type ProviderSkill, type Range, type RunDevOptions, type RunnerEnv, type RunnerLog, type Severity, type Template, type TemplateDependencyField, type TemplateInput, type TemplatePackages, type UiBuildOutput, type ValidationReport, storefrontProvider as default };
+//# sourceMappingURL=index.d.ts.map