@vtex/faststore 0.0.7 → 0.0.8

package/dist/cli/index.d.ts

@@ -1,5 +1,365 @@
 import { GraphQLFieldResolver, GraphQLScalarType, GraphQLSchema } from "graphql";
-import * as esbuild from "esbuild";
+//#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
@@ -9,59 +369,102 @@ import * as esbuild from "esbuild";
  */
 export declare const CORE_SUBGRAPH_NAME = "storefront-api-core";
 //#endregion
-//#region src/cli/host.d.ts
+//#region src/cli/log.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).
+ * 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 RunnerHost = {
-  esbuild: typeof esbuild;
+type RunnerLog = {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
 };
 //#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/`.
+ * 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 BuildResult = {
-  distDir: string;
+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 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.
+ * 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 `dist/` is in place, so an emitted artifact always describes emitted
- * output.
+ * 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, host: RunnerHost): Promise<BuildResult>;
+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. */
@@ -96,7 +499,25 @@ type RunnerEnv = {
   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 = {
@@ -112,12 +533,8 @@ type DevRunHandle = {
   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;
+  /** 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
@@ -130,18 +547,23 @@ type RunDevOptions = {
  * 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.
+ * 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, host: RunnerHost, env?: RunnerEnv, { registerSignals, watchSupergraphSeconds }?: RunDevOptions): Promise<DevRunHandle>;
+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
@@ -154,10 +576,9 @@ type DevWatchHandle = {
  * 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`).
+ * Like `runDev`, it installs no signal handler: the host calls `stop()`.
  */
-export declare function runDevWatch(extensionRoot: string, host: RunnerHost, env?: RunnerEnv): Promise<DevWatchHandle>;
+export declare function runDevWatch(extensionRoot: string, env: RunnerEnv, { log }?: DevWatchOptions): Promise<DevWatchHandle>;
 //#endregion
 //#region src/graphql/types.d.ts
 /**
@@ -252,6 +673,29 @@ type SubgraphDefinition = {
  */
 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
@@ -285,38 +729,43 @@ 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.
+ * 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.
  */
-type StorefrontTemplate = {
-  name: string;
-  description: string;
-  files(options: {
-    name: string;
-    vendor: string;
-  }): Record<string, string>;
-};
+export declare const templates: readonly Template[];
+//#endregion
+//#region src/cli/typescript.d.ts
 /**
- * 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`.
+ * 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 const templates: StorefrontTemplate[];
+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.
- * `ok` is true only when all three are clean.
+ * `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;
 };
 /**
@@ -324,7 +773,7 @@ type ValidationReport = {
  * 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
+ * 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`),
@@ -337,14 +786,14 @@ type ValidationReport = {
  * 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>;
+export declare function validateExtension(extensionRoot: string): 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.
+ * 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 { BuildResult, CapabilityFinding, CapabilityRule, DevRunHandle, DevWatchHandle, RunnerHost, StorefrontTemplate, ValidationReport };
+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