@vtex/faststore 0.0.10 → 0.0.11

package/dist/cli/index.d.ts

@@ -369,6 +369,30 @@ type KindProvider = {
  */
 export declare const CORE_SUBGRAPH_NAME = "storefront-api-core";
 //#endregion
+//#region src/cli/asset-identity.d.ts
+/**
+ * What the manifests say about a storefront Asset, and the two ways to learn it. The Platform
+ * Extension's `extension.yaml` declares the vendor and the Asset's `asset.yaml` body lists the
+ * secret names; the declaration carries neither (ADR-00025). Inside the provider the host has read
+ * both files, so `identityOf` takes them off the `ProviderAsset`. The root-only functions
+ * (`validateExtension`, `buildExtension`, `runDev`) read the same two files through
+ * `readAssetIdentity` when their caller passes no `identity`.
+ */
+type AssetIdentity = {
+  /** `extension.yaml` › `vendor`, verbatim: the platform's kebab-case spelling. */
+  vendor: string;
+  /** `asset.yaml` › `secrets`, names only; `[]` when the body lists none. */
+  secrets: readonly string[];
+};
+/**
+ * Reads the identity from disk for a caller that has only the Asset's root: `asset.yaml` in the
+ * root for the secrets and the nearest `extension.yaml` at or above it for the vendor, from the
+ * canonical path, so an Asset opened through a link walks its real tree. A missing file is a throw
+ * that names it, both when both are missing, since an Asset outside an Account Repo has no identity
+ * to read; a caller that knows the values passes `identity` and no file is opened.
+ */
+export declare function readAssetIdentity(extensionRoot: string): AssetIdentity;
+//#endregion
 //#region src/cli/log.d.ts
 /**
  * The sink the runner reports through. Nothing under `src/cli/` prints: a host
@@ -422,6 +446,8 @@ type BuildOptions = {
   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;
+  /** The Asset's vendor and secret names. Read from `asset.yaml` and `extension.yaml` when omitted and the Asset has an API side. */
+  identity?: AssetIdentity;
 };
 /** Raised when the TypeScript compiler reports diagnostics — carries them formatted for verbatim output. */
 export declare class CompileError extends Error {
@@ -464,7 +490,7 @@ export declare class CompileError extends Error {
  * 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>;
+export declare function buildExtension(extensionRoot: string, { log, outDir: outDirOption, identity }?: BuildOptions): Promise<BuildResult>;
 //#endregion
 //#region src/cli/capability-lint.d.ts
 /** The three forbidden reaches the capability lint enforces on first-party source. */
@@ -541,6 +567,8 @@ type RunDevOptions = {
    * `supergraph.graphql` without a restart.
    */
   watchSupergraphSeconds?: number;
+  /** The Asset's vendor and secret names. Read from `asset.yaml` and `extension.yaml` when omitted. */
+  identity?: AssetIdentity;
 };
 /**
  * Orchestrates the full `runDev` loop: loads the declaration, starts
@@ -555,7 +583,7 @@ type RunDevOptions = {
  * 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>;
+export declare function runDev(extensionRoot: string, env: RunnerEnv, { log, watchSupergraphSeconds, identity: given }?: RunDevOptions): Promise<DevRunHandle>;
 type DevWatchHandle = {
   routerUrl: string;
   stop: () => Promise<void>;
@@ -563,6 +591,8 @@ type DevWatchHandle = {
 type DevWatchOptions = {
   /** Where progress, warnings and failures go. Silent when omitted: nothing in the runner prints (ADR-0026). */
   log?: RunnerLog;
+  /** The Asset's vendor and secret names. Read from `asset.yaml` and `extension.yaml` when omitted. */
+  identity?: AssetIdentity;
 };
 /**
  * Runs the dev loop under a file watcher rooted at the declaration entry's
@@ -578,7 +608,7 @@ type DevWatchOptions = {
  *
  * Like `runDev`, it installs no signal handler: the host calls `stop()`.
  */
-export declare function runDevWatch(extensionRoot: string, env: RunnerEnv, { log }?: DevWatchOptions): Promise<DevWatchHandle>;
+export declare function runDevWatch(extensionRoot: string, env: RunnerEnv, { log, identity }?: DevWatchOptions): Promise<DevWatchHandle>;
 //#endregion
 //#region src/graphql/types.d.ts
 /**
@@ -640,16 +670,12 @@ type SubgraphResolvers<TContext = SubgraphContext> = {
  * 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`).
+ * with the Platform Extension's vendor (see `applyVendorPrefix` in
+ * `./vendor-prefix`). The vendor and the secret names are not declared here:
+ * `extension.yaml` carries the vendor and the Asset's `asset.yaml` lists the
+ * secrets (ADR-00025).
  */
 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. */
@@ -658,12 +684,6 @@ type SubgraphDefinition = {
   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
@@ -696,11 +716,20 @@ declare const storefrontProvider: KindProvider;
 /** 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/vendor-prefix.d.ts
+/**
+ * The vendor as a GraphQL name prefix: every `-` becomes `_`, so `acme-corp` prefixes
+ * `acme_corp_reviews`. A digit-leading vendor is the one platform vendor refused here, with the
+ * message the Finding carries. Kept in this graphql-only module, not beside the manifest reader,
+ * so `server.mjs` bundles no file parser.
+ */
+export declare function vendorPrefixToken(vendor: 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
+ * schema: derives the prefix from `vendor`, the Platform Extension's, checks
+ * 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
@@ -713,7 +742,7 @@ export declare const skills: readonly ProviderSkill[];
  * non-atomically. Authors own idempotency/compensation for their own
  * mutations (see the RFC's "Resolved v1 decisions").
  */
-export declare function buildSubgraph(definition: SubgraphDefinition): GraphQLSchema;
+export declare function buildSubgraph(definition: SubgraphDefinition, vendor: string): GraphQLSchema;
 //#endregion
 //#region src/cli/subgraph/print-subgraph-sdl.d.ts
 /**
@@ -725,13 +754,15 @@ export declare function buildSubgraph(definition: SubgraphDefinition): GraphQLSc
  * byte-for-byte. Round-trips through `parse`/`print` so formatting is
  * normalized.
  */
-export declare function printSubgraphSdl(definition: SubgraphDefinition): string;
+export declare function printSubgraphSdl(definition: SubgraphDefinition, vendor: string): 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`.
+ * storefront body's one field, `secrets`, has nothing to say for a new Asset, so each `body` is
+ * `{}`. The one vendor the platform admits and a storefront Asset cannot use, a digit-leading
+ * one, is rejected up front (`vendorPrefixToken`), so a template never renders a test 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
@@ -756,7 +787,7 @@ export declare class TypeScriptUnavailableError extends Error {
 /**
  * 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.
+ * declaration (allow-list, the vendor's prefix token, 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.
@@ -768,15 +799,22 @@ type ValidationReport = {
   typescript?: Error;
   ok: boolean;
 };
+type ValidateOptions = {
+  /** The Asset's vendor and secret names. Read from `asset.yaml` and `extension.yaml` when omitted. */
+  identity?: AssetIdentity;
+};
 /**
  * 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:
  *
+ * 0. takes the identity the caller passed, or reads it from the manifests
+ *    (`readAssetIdentity`), which throws when the root is not inside an
+ *    Account Repo,
  * 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`),
+ * 2. builds the subgraph under the vendor's prefix (allow-list rejection and
+ *    the token check 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.
@@ -786,7 +824,7 @@ 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): Promise<ValidationReport>;
+export declare function validateExtension(extensionRoot: string, { identity: given }?: ValidateOptions): Promise<ValidationReport>;
 /**
  * Renders a `ValidationReport`'s failures as human-readable lines, grouped by
  * category (typescript, build/allow-list, capability, composition) — every
@@ -795,5 +833,5 @@ export declare function validateExtension(extensionRoot: string): Promise<Valida
  */
 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 };
+export { type AdapterHandle, type ApiBuildOutput, type AssetIdentity, 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 ValidateOptions, type ValidationReport, storefrontProvider as default };
 //# sourceMappingURL=index.d.ts.map