@commercetools/cli-topic-integration-layer 0.2.2 → 0.4.0

package/dist/lib/base.d.ts

@@ -1,4 +1,11 @@
 import { AuthCommand, CtpAuthorizedClient } from "@commercetools/cli-plugin-auth";
+/**
+ * Reconstruct the logged-in principal from the persisted credentials file. Returns
+ * undefined when no valid client-credentials login is on disk (absent file, or a
+ * different auth kind), so unauthorized commands still run. No network. Exported for
+ * tests; commands go through {@link IntegrationLayerCommand.requirePrincipal}.
+ */
+export declare function loadPersistedPrincipal(credentialsFile?: string): Promise<CtpAuthorizedClient | undefined>;
 /** The resolved, ready-to-use integration-layer context: where to call and as whom. */
 export interface IlContext {
     /** The integration-layer edge base URL, trailing slashes trimmed. */
@@ -26,6 +33,21 @@ export interface IlFlagValues {
  * only when the region is absent, so resolveIlContext then fails loudly.
  */
 export declare function edgeUrlForRegion(region: string): string | undefined;
+/**
+ * The GRAPHQL edge (the integration-router) for a region — where operations are
+ * actually served, at `/{project}/graphql`. A distinct host from the extensions
+ * edge above: the extensions edge is the connector backend (manage_project routes),
+ * the graphql edge is the router. `--graphql-url` / `IL_GRAPHQL_URL` overrides it
+ * for staging zones, which don't follow the production convention.
+ */
+export declare function graphqlEdgeUrlForRegion(region: string): string | undefined;
+/**
+ * The IDENTITY edge (the storefront pod) for a region — where sessions are minted,
+ * at `POST /{project}/session`. Again a distinct host from both of the above; the
+ * four-pod split put shopper identity, shopper GraphQL, and the machine surface on
+ * separate ingresses. `--auth-url` / `IL_AUTH_URL` overrides it.
+ */
+export declare function authEdgeUrlForRegion(region: string): string | undefined;
 export declare abstract class IntegrationLayerCommand extends AuthCommand {
     /**
      * Whether the command needs a logged-in principal. True for every command that
@@ -34,11 +56,24 @@ export declare abstract class IntegrationLayerCommand extends AuthCommand {
      * to fail loudly if the network path is actually taken.
      */
     protected authorized: boolean;
+    /**
+     * The principal loaded from `~/.commercetools/credentials` in {@link init}, or
+     * undefined when no valid login is persisted. Resolved once per command run so the
+     * synchronous {@link requirePrincipal} call sites (here and in `explore`) are unchanged.
+     */
+    private persistedPrincipal?;
     static baseFlags: {
         "integration-layer-url": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         "project-key": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     protected init(): Promise<void>;
+    /**
+     * Read the persisted login from `~/.commercetools/credentials`. Returns undefined when
+     * no login is on disk (so unauthorized commands like standalone `serve` still run) and
+     * only fails loudly when the file is present but malformed. No network — the token was
+     * already minted by `auth login` and serialized whole.
+     */
+    private loadPersistedPrincipal;
     /** The logged-in commercetools principal, or an `AuthorizationError` pointing at `auth login`. */
     protected requirePrincipal(): CtpAuthorizedClient;
     /**

package/dist/lib/base.js

@@ -1,16 +1,62 @@
 // Base class for the topic's commands that reach the integration layer's
-// `manage_project` boundary. It extends the host CLI's `AuthCommand`
-// (`@commercetools/cli-plugin-auth`), so the bearer is the token
-// `commercetools auth login` already persisted to `~/.commercetools/credentials`
-// (loaded into the security context by the auth plugin's prerun hook) — no separate
-// credential handling, exactly as the `connect` topic does.
+// `manage_project` boundary. The bearer is the token `commercetools auth login`
+// already persisted to `~/.commercetools/credentials`; we read it back from disk
+// here rather than from the auth plugin's in-memory security context — see below.
 //
-// `@commercetools/cli-plugin-auth` is a PEER dependency: at runtime the plugin uses
-// the HOST CLI's copy, so the static auth manager/repository the host wires up are
-// the same singletons this class reads (a bundled second copy would see an empty
-// security context and reject every logged-in caller).
+// `@commercetools/cli-plugin-auth` holds the security context in a MODULE-LEVEL
+// STATIC (`SecurityContextHolder.globalContext`), so there is one context per loaded
+// copy of that module. When this topic is bundled into the host CLI it resolves up
+// into the host's single copy and the static the host fills is the one we read. But
+// when the topic is installed via `oclif plugins install`, it lands in the oclif data
+// dir's own node_modules tree, npm auto-installs the declared `cli-plugin-auth` there,
+// and Node loads that as a SECOND, distinct module instance. `auth login`'s prerun
+// hook (running in the host) fills the HOST copy's static; a read via the inherited
+// `getAuthentication()` would hit the DATA-DIR copy's empty static and reject every
+// logged-in caller ("not logged in"). This is not hypothetical — it is the exact
+// failure mode that a CI symlink-dedupe workaround previously papered over.
+//
+// The cure is to stop depending on cross-copy static identity. `auth login` serializes
+// the full principal (token, region, project key, scope, expiry) to
+// `~/.commercetools/credentials` via the host CLI's `FileBasedAuthenticationRepository`.
+// We reconstruct it from that same file, from THIS module's own copy of the repository
+// — no network, no auth manager, no shared static — so it no longer matters whether one
+// or two copies of `cli-plugin-auth` are loaded. Accordingly `cli-plugin-auth` is a
+// regular `dependency`, not a peer: a second copy is now harmless. The path, auth id
+// (`"client-credentials"`), and serialized shape mirror the host CLI's
+// `providers.ts`/`init.ts` wiring exactly.
+import os from "node:os";
+import path from "node:path";
 import { Flags } from "@oclif/core";
-import { AuthCommand, AuthorizationError, CtpAuthorizedClient, } from "@commercetools/cli-plugin-auth";
+import { AuthCommand, AuthorizationError, CtpAuthorizedClient, CtpClientAuthenticationToken, FileBasedAuthenticationRepository, } from "@commercetools/cli-plugin-auth";
+/**
+ * Where `commercetools auth login` persists the serialized principal, and the auth id
+ * it files the client-credentials token under. These mirror the host CLI's
+ * `providers.ts` (`@commercetools/cli`) — the on-disk credentials contract — verbatim.
+ */
+const CREDENTIALS_FILE = path.join(os.homedir(), ".commercetools", "credentials");
+const CLIENT_CREDENTIALS_AUTH_ID = "client-credentials";
+/**
+ * A `FileBasedAuthenticationRepository` over the shared credentials file, wired to
+ * deserialize the client-credentials principal. Constructed from THIS module's copy of
+ * `cli-plugin-auth`, so `loadAuthentication()` reconstructs the principal regardless of
+ * how many copies of the auth plugin are loaded (see the header note).
+ */
+function persistedAuthenticationRepository(credentialsFile) {
+    const repository = new FileBasedAuthenticationRepository(credentialsFile);
+    repository.addSerializable(CLIENT_CREDENTIALS_AUTH_ID, CtpClientAuthenticationToken, CtpClientAuthenticationToken.Serializable);
+    return repository;
+}
+/**
+ * Reconstruct the logged-in principal from the persisted credentials file. Returns
+ * undefined when no valid client-credentials login is on disk (absent file, or a
+ * different auth kind), so unauthorized commands still run. No network. Exported for
+ * tests; commands go through {@link IntegrationLayerCommand.requirePrincipal}.
+ */
+export async function loadPersistedPrincipal(credentialsFile = CREDENTIALS_FILE) {
+    const authentication = await persistedAuthenticationRepository(credentialsFile).loadAuthentication();
+    const principal = authentication?.getPrincipal();
+    return principal instanceof CtpAuthorizedClient ? principal : undefined;
+}
 /**
  * Derive the integration-layer EXTENSIONS edge base URL from the authenticated
  * principal's commercetools region. The extensions edge — the connector-backend pod
@@ -30,6 +76,31 @@ export function edgeUrlForRegion(region) {
         return undefined;
     return `https://extensions.integration-layer.${trimmed}.commercetools.com`;
 }
+/**
+ * The GRAPHQL edge (the integration-router) for a region — where operations are
+ * actually served, at `/{project}/graphql`. A distinct host from the extensions
+ * edge above: the extensions edge is the connector backend (manage_project routes),
+ * the graphql edge is the router. `--graphql-url` / `IL_GRAPHQL_URL` overrides it
+ * for staging zones, which don't follow the production convention.
+ */
+export function graphqlEdgeUrlForRegion(region) {
+    const trimmed = region.trim();
+    if (!trimmed)
+        return undefined;
+    return `https://graphql.integration-layer.${trimmed}.commercetools.com`;
+}
+/**
+ * The IDENTITY edge (the storefront pod) for a region — where sessions are minted,
+ * at `POST /{project}/session`. Again a distinct host from both of the above; the
+ * four-pod split put shopper identity, shopper GraphQL, and the machine surface on
+ * separate ingresses. `--auth-url` / `IL_AUTH_URL` overrides it.
+ */
+export function authEdgeUrlForRegion(region) {
+    const trimmed = region.trim();
+    if (!trimmed)
+        return undefined;
+    return `https://auth.integration-layer.${trimmed}.commercetools.com`;
+}
 export class IntegrationLayerCommand extends AuthCommand {
     /**
      * Whether the command needs a logged-in principal. True for every command that
@@ -38,6 +109,12 @@ export class IntegrationLayerCommand extends AuthCommand {
      * to fail loudly if the network path is actually taken.
      */
     authorized = true;
+    /**
+     * The principal loaded from `~/.commercetools/credentials` in {@link init}, or
+     * undefined when no valid login is persisted. Resolved once per command run so the
+     * synchronous {@link requirePrincipal} call sites (here and in `explore`) are unchanged.
+     */
+    persistedPrincipal;
     static baseFlags = {
         "integration-layer-url": Flags.string({
             description: "integration-layer extensions edge base URL (also settable via INTEGRATION_LAYER_URL); overrides the URL derived from your login region",
@@ -51,14 +128,23 @@ export class IntegrationLayerCommand extends AuthCommand {
     };
     async init() {
         await super.init();
+        this.persistedPrincipal = await this.loadPersistedPrincipal();
         if (this.authorized)
             this.requirePrincipal();
     }
+    /**
+     * Read the persisted login from `~/.commercetools/credentials`. Returns undefined when
+     * no login is on disk (so unauthorized commands like standalone `serve` still run) and
+     * only fails loudly when the file is present but malformed. No network — the token was
+     * already minted by `auth login` and serialized whole.
+     */
+    async loadPersistedPrincipal() {
+        return loadPersistedPrincipal();
+    }
     /** The logged-in commercetools principal, or an `AuthorizationError` pointing at `auth login`. */
     requirePrincipal() {
-        const principal = this.getAuthentication()?.getPrincipal();
-        if (principal instanceof CtpAuthorizedClient)
-            return principal;
+        if (this.persistedPrincipal)
+            return this.persistedPrincipal;
         throw new AuthorizationError("not logged in — run `commercetools auth login` first");
     }
     /**

package/dist/lib/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/lib/base.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,qEAAqE;AACrE,iEAAiE;AACjE,iFAAiF;AACjF,oFAAoF;AACpF,4DAA4D;AAC5D,EAAE;AACF,oFAAoF;AACpF,mFAAmF;AACnF,iFAAiF;AACjF,uDAAuD;AAEvD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AAiBxC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,wCAAwC,OAAO,oBAAoB,CAAC;AAC7E,CAAC;AAED,MAAM,OAAgB,uBAAwB,SAAQ,WAAW;IAC/D;;;;;OAKG;IACO,UAAU,GAAG,IAAI,CAAC;IAE5B,MAAM,CAAU,SAAS,GAAG;QAC1B,uBAAuB,EAAE,KAAK,CAAC,MAAM,CAAC;YACpC,WAAW,EACT,wIAAwI;YAC1I,GAAG,EAAE,uBAAuB;YAC5B,SAAS,EAAE,mBAAmB;SAC/B,CAAC;QACF,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC;YAC1B,WAAW,EAAE,oCAAoC;YACjD,SAAS,EAAE,mBAAmB;SAC/B,CAAC;KACH,CAAC;IAEiB,KAAK,CAAC,IAAI;QAC3B,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IAED,kGAAkG;IACxF,gBAAgB;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,EAAE,YAAY,EAAE,CAAC;QAC3D,IAAI,SAAS,YAAY,mBAAmB;YAAE,OAAO,SAAS,CAAC;QAC/D,MAAM,IAAI,kBAAkB,CAAC,sDAAsD,CAAC,CAAC;IACvF,CAAC;IAED;;;;OAIG;IACO,KAAK,CAAC,gBAAgB,CAAC,KAAmB;QAClD,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE,CAAC;QAEzD,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC,aAAa,EAAE,CAAC;QACrE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACb,mGAAmG,CACpG,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,uBAAuB,CAAC,IAAI,gBAAgB,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1F,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,mFAAmF;gBACjF,wDAAwD;gBACxD,0EAA0E,CAC7E,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACrE,CAAC"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/lib/base.ts"],"names":[],"mappings":"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"}

package/dist/lib/ilClient.d.ts

@@ -65,6 +65,22 @@ export interface RemoteValidationResult {
 }
 /** GET the project's raw core-subgraph SDL — the compose input (`GET …/subgraph`). */
 export declare function fetchSubgraphSdl(baseUrl: string, projectKey: string, token: string): Promise<string>;
+/**
+ * GET the project's DEPLOYED composed graph as a PUBLIC API SCHEMA — what the router
+ * actually plans and serves (core subgraph + the project's published extension),
+ * read from Hive by the integration layer and reduced there (`GET …/schema/api`).
+ *
+ * The integration layer strips the federation machinery before sending, so this is
+ * `buildSchema`-able as-is; there is no supergraph to reduce client-side. It is the
+ * byte-identical response the Merchant Center console's explorer reads under its
+ * own operator JWT — one artifact, two guards.
+ *
+ * This is the authenticated replacement for introspecting the public edge: the
+ * router runs `introspection: false`, so the composed graph is read here, over the
+ * same `manage_project` boundary as `/subgraph`. 404 means the project has never
+ * published a composable version.
+ */
+export declare function fetchDeployedApiSchemaSdl(baseUrl: string, projectKey: string, token: string): Promise<string>;
 /** POST a candidate SDL to the composition + breaking-change gate (`POST …/extension/validate`). */
 export declare function remoteValidate(baseUrl: string, projectKey: string, token: string, typeDefs: string): Promise<RemoteValidationResult>;
 /**

package/dist/lib/ilClient.js

@@ -22,6 +22,34 @@ export async function fetchSubgraphSdl(baseUrl, projectKey, token) {
     }
     return text;
 }
+/**
+ * GET the project's DEPLOYED composed graph as a PUBLIC API SCHEMA — what the router
+ * actually plans and serves (core subgraph + the project's published extension),
+ * read from Hive by the integration layer and reduced there (`GET …/schema/api`).
+ *
+ * The integration layer strips the federation machinery before sending, so this is
+ * `buildSchema`-able as-is; there is no supergraph to reduce client-side. It is the
+ * byte-identical response the Merchant Center console's explorer reads under its
+ * own operator JWT — one artifact, two guards.
+ *
+ * This is the authenticated replacement for introspecting the public edge: the
+ * router runs `introspection: false`, so the composed graph is read here, over the
+ * same `manage_project` boundary as `/subgraph`. 404 means the project has never
+ * published a composable version.
+ */
+export async function fetchDeployedApiSchemaSdl(baseUrl, projectKey, token) {
+    const url = `${apiRoot(baseUrl, projectKey)}/schema/api`;
+    const res = await fetch(url, { headers: { accept: "text/plain", ...bearer(token) } });
+    const text = await res.text();
+    if (res.status === 404) {
+        throw new Error(`project '${projectKey}' has no composed schema published yet — publish one from the ` +
+            `Merchant Center console (Schema → Refresh schema), or drop --deployed to compose locally`);
+    }
+    if (!res.ok) {
+        throw new Error(`could not fetch the deployed composed schema (${res.status}) from ${url}: ${text}`);
+    }
+    return text;
+}
 /** POST a candidate SDL to the composition + breaking-change gate (`POST …/extension/validate`). */
 export async function remoteValidate(baseUrl, projectKey, token, typeDefs) {
     const url = `${apiRoot(baseUrl, projectKey)}/extension/validate`;

package/dist/lib/ilClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"ilClient.js","sourceRoot":"","sources":["../../src/lib/ilClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ilClient.js","sourceRoot":"","sources":["../../src/lib/ilClient.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,oFAAoF;AACpF,uFAAuF;AACvF,+EAA+E;AAC/E,kEAAkE;AAClE,sFAAsF;AACtF,oFAAoF;AACpF,kEAAkE;AAwElE,SAAS,OAAO,CAAC,OAAe,EAAE,UAAkB;IAClD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC;AAC9C,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAe,EACf,UAAkB,EAClB,KAAa;IAEb,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC;IACvD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IACtF,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,CAAC,MAAM,UAAU,GAAG,KAAK,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAe,EACf,UAAkB,EAClB,KAAa;IAEb,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,aAAa,CAAC;IACzD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IACtF,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,YAAY,UAAU,gEAAgE;YACpF,0FAA0F,CAC7F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iDAAiD,GAAG,CAAC,MAAM,UAAU,GAAG,KAAK,IAAI,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,UAAkB,EAClB,KAAa,EACb,QAAgB;IAEhB,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,qBAAqB,CAAC;IACjE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE;QACjE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;KACnC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAA2B,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,UAAkB,EAClB,KAAa,EACb,MAAc,EACd,QAAgB,EAChB,cAAuB;IAEvB,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,mBAAmB,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,cAAc,EAAE,iBAAiB;YACjC,4EAA4E;YAC5E,mEAAmE;YACnE,sBAAsB,EAAE,kBAAkB,CAAC,QAAQ,CAAC;YACpD,+EAA+E;YAC/E,+EAA+E;YAC/E,0DAA0D;YAC1D,GAAG,CAAC,cAAc;gBAChB,CAAC,CAAC,EAAE,6BAA6B,EAAE,kBAAkB,CAAC,cAAc,CAAC,EAAE;gBACvE,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,MAAM,CAAC,KAAK,CAAC;SACjB;QACD,IAAI,EAAE,MAAM;KACb,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;AAC3C,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,UAAkB,EAClB,KAAa;IAEb,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,wBAAwB,CAAC;IACpE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5F,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;AAC3C,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAe,EACf,UAAkB,EAClB,KAAa;IAEb,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,qBAAqB,CAAC;IACjE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAClF,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,UAAkB,EAClB,KAAa;IAEb,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,mBAAmB,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5F,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,UAAkB,EAClB,KAAa,EACb,OAAuE;IAEvE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,mBAAmB,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE;QACjE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAC9B,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;AAC3C,CAAC"}

package/dist/lib/tooling/exploreSchema.d.ts

@@ -0,0 +1,15 @@
+import { type GraphQLSchema } from "graphql";
+/** A resolved explorer schema plus how it was obtained (for the startup banner). */
+export interface ExplorerSchema {
+    schema: GraphQLSchema;
+    sdl: string;
+    /** e.g. `local compose (core + your extension)` or `deployed (Hive)`. */
+    describe: string;
+}
+/**
+ * The local-composition path: the project's core subgraph, plus `extensionSdl` when
+ * the caller found a local extension to build. Throws with the composition errors
+ * when the two don't compose — the same failure `extension validate` reports, and a
+ * real answer rather than a half-rendered explorer.
+ */
+export declare function composeLocalExplorerSchema(coreSdl: string, extensionSdl: string | undefined): ExplorerSchema;

package/dist/lib/tooling/exploreSchema.js

@@ -0,0 +1,77 @@
+// The schema the local explorer renders — resolved one of two ways.
+//
+//   default      compose locally: the project's core-subgraph SDL (GET /subgraph)
+//                plus, when the working directory holds one, your LOCAL extension.
+//                Fast inner loop: edit the extension, restart, see your fields.
+//
+//   --deployed   the project's DEPLOYED composed graph (GET /schema/api), read from
+//                Hive by the integration layer and reduced THERE to a public API
+//                schema — exactly what the router plans and serves, including
+//                whichever extension is actually deployed. The command just
+//                buildSchema()s it, so nothing in this module handles that path.
+//
+// Only the LOCAL path composes, which is why this module exists at all: a supergraph
+// can't be composed on the server for a working-tree extension that was never pushed.
+// Both paths end at a client-facing `GraphQLSchema`, which the explorer serves to
+// GraphiQL (answering introspection locally). Execution is proxied to the real edge
+// either way — this schema drives the docs pane, autocomplete, and validation only.
+import { printSchema } from "graphql";
+import { composeServices } from "@apollo/composition";
+import { parse } from "graphql";
+import { composeWithIntegrationLayer, INTEGRATION_LAYER_SERVICE, } from "./compose.js";
+/** Placeholder URLs baked into a locally-composed supergraph. The explorer never
+ *  routes through them (it proxies whole operations to the edge), so they are
+ *  cosmetic — but composition requires each subgraph to declare one. */
+const LOCAL_IL_URL = "http://integration-layer.local/graphql";
+const LOCAL_EXTENSION_URL = "http://extension.local/graphql";
+/**
+ * Compose the core subgraph ALONE into an API schema — the local path when the
+ * working directory has no extension. `composeWithIntegrationLayer` takes two
+ * subgraphs, so the single-subgraph case goes straight to `composeServices`.
+ */
+function composeCoreOnly(coreSdl) {
+    let services;
+    try {
+        services = [
+            { name: INTEGRATION_LAYER_SERVICE, typeDefs: parse(coreSdl), url: LOCAL_IL_URL },
+        ];
+    }
+    catch (err) {
+        return { ok: false, errors: [`core-subgraph SDL is not valid GraphQL: ${err.message}`] };
+    }
+    const result = composeServices(services);
+    if (result.errors)
+        return { ok: false, errors: result.errors.map((e) => e.message) };
+    const apiSchema = result.schema.toAPISchema().toGraphQLJSSchema();
+    return {
+        ok: true,
+        apiSchema,
+        apiSdl: printSchema(apiSchema),
+        supergraphSdl: result.supergraphSdl,
+    };
+}
+/**
+ * The local-composition path: the project's core subgraph, plus `extensionSdl` when
+ * the caller found a local extension to build. Throws with the composition errors
+ * when the two don't compose — the same failure `extension validate` reports, and a
+ * real answer rather than a half-rendered explorer.
+ */
+export function composeLocalExplorerSchema(coreSdl, extensionSdl) {
+    const result = extensionSdl
+        ? composeWithIntegrationLayer(coreSdl, extensionSdl, {
+            integrationLayerUrl: LOCAL_IL_URL,
+            extensionUrl: LOCAL_EXTENSION_URL,
+        })
+        : composeCoreOnly(coreSdl);
+    if (!result.ok) {
+        throw new Error(`could not compose the schema locally:\n${result.errors.map((e) => `  - ${e}`).join("\n")}`);
+    }
+    return {
+        schema: result.apiSchema,
+        sdl: result.apiSdl,
+        describe: extensionSdl
+            ? "local compose (core subgraph + your local extension)"
+            : "local compose (core subgraph only — no extension in this directory)",
+    };
+}
+//# sourceMappingURL=exploreSchema.js.map

package/dist/lib/tooling/exploreSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exploreSchema.js","sourceRoot":"","sources":["../../../src/lib/tooling/exploreSchema.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,kFAAkF;AAClF,mFAAmF;AACnF,gFAAgF;AAChF,EAAE;AACF,oFAAoF;AACpF,iFAAiF;AACjF,8EAA8E;AAC9E,4EAA4E;AAC5E,iFAAiF;AACjF,EAAE;AACF,qFAAqF;AACrF,sFAAsF;AACtF,kFAAkF;AAClF,oFAAoF;AACpF,oFAAoF;AAEpF,OAAO,EAAE,WAAW,EAAsB,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,GAE1B,MAAM,cAAc,CAAC;AAEtB;;wEAEwE;AACxE,MAAM,YAAY,GAAG,wCAAwC,CAAC;AAC9D,MAAM,mBAAmB,GAAG,gCAAgC,CAAC;AAU7D;;;;GAIG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG;YACT,EAAE,IAAI,EAAE,yBAAyB,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE;SACjF,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,2CAA4C,GAAa,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;IACtG,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrF,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC;IAClE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,SAAS;QACT,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC;QAC9B,aAAa,EAAE,MAAM,CAAC,aAAa;KACpC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,YAAgC;IAEhC,MAAM,MAAM,GAAG,YAAY;QACzB,CAAC,CAAC,2BAA2B,CAAC,OAAO,EAAE,YAAY,EAAE;YACjD,mBAAmB,EAAE,YAAY;YACjC,YAAY,EAAE,mBAAmB;SAClC,CAAC;QACJ,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAE7B,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,0CAA0C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5F,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,SAAS;QACxB,GAAG,EAAE,MAAM,CAAC,MAAM;QAClB,QAAQ,EAAE,YAAY;YACpB,CAAC,CAAC,sDAAsD;YACxD,CAAC,CAAC,qEAAqE;KAC1E,CAAC;AACJ,CAAC"}

package/dist/lib/tooling/explorerPage.d.ts

@@ -0,0 +1 @@
+export declare const EXPLORER_HTML: string;

package/dist/lib/tooling/explorerPage.js

@@ -0,0 +1,96 @@
+// The GraphiQL page the local explorer serves at `/`.
+//
+// A static HTML shell loading GraphiQL from a CDN (esm.sh, version-pinned + SRI),
+// pointed at this same local server's `/graphql`. Nothing is templated into it: the
+// project key, the edge URL, and the session bearer all live server-side, so the
+// page holds no credential and needs no configuration.
+//
+// The local server answers introspection itself from the resolved schema and proxies
+// everything else to the deployed edge, so GraphiQL gets full docs/autocomplete even
+// though the edge itself has introspection disabled.
+export const EXPLORER_HTML = String.raw `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>GraphQL Explorer · commercetools integration layer</title>
+    <style>
+      body { margin: 0; height: 100dvh; overflow: hidden; }
+      #graphiql { height: 100dvh; }
+      .loading { display: flex; height: 100dvh; align-items: center;
+                 justify-content: center; font-family: ui-sans-serif, system-ui, sans-serif;
+                 color: #6b7280; }
+    </style>
+    <link
+      rel="stylesheet"
+      href="https://esm.sh/graphiql@5.2.4/dist/style.css"
+      integrity="sha384-TFpQQKp325U5sd3PddH4cS0KOB3Gz/aqdEe12Mqkkq3wm2MGcDhRX5WhWf+o8akh"
+      crossorigin="anonymous"
+    />
+    <link
+      rel="stylesheet"
+      href="https://esm.sh/@graphiql/plugin-explorer@5.1.3/dist/style.css"
+      integrity="sha384-vTFGj0krVqwFXLB7kq/VHR0/j2+cCT/B63rge2mULaqnib2OX7DVLUVksTlqvMab"
+      crossorigin="anonymous"
+    />
+    <script type="importmap">
+      {
+        "imports": {
+          "react": "https://esm.sh/react@19.2.0",
+          "react/jsx-runtime": "https://esm.sh/react@19.2.0/jsx-runtime",
+          "react-dom": "https://esm.sh/react-dom@19.2.0",
+          "react-dom/client": "https://esm.sh/react-dom@19.2.0/client",
+          "graphql": "https://esm.sh/graphql@16.11.0",
+          "graphiql": "https://esm.sh/graphiql@5.2.4?standalone&external=react,react-dom,@graphiql/react,graphql",
+          "graphiql/": "https://esm.sh/graphiql@5.2.4/",
+          "@graphiql/plugin-explorer": "https://esm.sh/@graphiql/plugin-explorer@5.1.3?standalone&external=react,@graphiql/react,graphql",
+          "@graphiql/react": "https://esm.sh/@graphiql/react@0.37.7?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid",
+          "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit@0.12.1?standalone&external=graphql"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="graphiql"><div class="loading">Loading the explorer…</div></div>
+    <script type="module">
+      import React from 'react';
+      import ReactDOM from 'react-dom/client';
+      import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
+      import { createGraphiQLFetcher } from '@graphiql/toolkit';
+      import { explorerPlugin } from '@graphiql/plugin-explorer';
+      import 'graphiql/setup-workers/esm.sh';
+
+      // Same-origin: this page and the GraphQL endpoint are both served by the CLI's
+      // local server, which holds the session bearer and forwards to the edge.
+      const fetcher = createGraphiQLFetcher({ url: location.origin + '/graphql' });
+
+      const plugins = [HISTORY_PLUGIN, explorerPlugin()];
+
+      const DEFAULT_QUERY = [
+        '# Local GraphQL explorer for your commercetools integration layer.',
+        '#',
+        '# Operations run against the DEPLOYED edge under the session shown in your',
+        '# terminal. Docs and autocomplete come from the schema the CLI resolved.',
+        '',
+        'query Categories {',
+        '  categories {',
+        '    items {',
+        '      name',
+        '    }',
+        '  }',
+        '}',
+        '',
+      ].join('\n');
+
+      ReactDOM.createRoot(document.getElementById('graphiql')).render(
+        React.createElement(GraphiQL, {
+          fetcher,
+          plugins,
+          defaultQuery: DEFAULT_QUERY,
+        }),
+      );
+    </script>
+  </body>
+</html>
+`;
+//# sourceMappingURL=explorerPage.js.map

package/dist/lib/tooling/explorerPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorerPage.js","sourceRoot":"","sources":["../../../src/lib/tooling/explorerPage.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,kFAAkF;AAClF,oFAAoF;AACpF,iFAAiF;AACjF,uDAAuD;AACvD,EAAE;AACF,qFAAqF;AACrF,qFAAqF;AACrF,qDAAqD;AAErD,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFtC,CAAC"}

package/dist/lib/tooling/explorerServer.d.ts

@@ -0,0 +1,27 @@
+import { type Server } from "node:http";
+import { type GraphQLSchema } from "graphql";
+/** The GraphQL-over-HTTP request body GraphiQL sends. */
+export interface GraphQLBody {
+    query?: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}
+export interface ExplorerServerOptions {
+    /** The schema introspection is answered from (docs, autocomplete, validation). */
+    schema: GraphQLSchema;
+    /** Absolute URL of the deployed edge's per-project GraphQL endpoint. */
+    endpoint: string;
+    /** Session bearer attached to every proxied operation. Never sent to the browser. */
+    bearer: string;
+}
+/**
+ * Build (but do not listen on) the explorer's server.
+ *
+ * The edge endpoint is validated ONCE here, not per request: it must be an
+ * absolute `http:`/`https:` URL. It comes from the operator's own login region or
+ * their explicit `--graphql-url` / `IL_GRAPHQL_URL`, so this is not a trust
+ * boundary — but pinning the scheme up front means a typo or a stray `file://`
+ * fails at startup with a clear message rather than at the first query, and the
+ * value the proxy uses can never be anything else.
+ */
+export declare function createExplorerServer(opts: ExplorerServerOptions): Server;