@commercetools/cli-topic-integration-layer 0.2.1 → 0.3.1

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

@@ -4,6 +4,16 @@ export interface ConfigEntry {
     value: string | null;
     secret: boolean;
 }
+/**
+ * Lifecycle state of a stored bundle version.
+ *
+ *  pending — stored and being handed out, but nothing has confirmed it loads.
+ *  running — an extension loaded it and published its schema. Once a version
+ *            reaches this it is never demoted.
+ *  failed  — it could not be loaded (`reason` says why). The integration layer
+ *            stops handing it out and the version beneath it takes over.
+ */
+export type ExtensionState = "pending" | "running" | "failed";
 /** The stored bundle's metadata (integration layer `ExtensionMeta`). */
 export interface ExtensionMeta {
     projectKey: string;
@@ -12,6 +22,34 @@ export interface ExtensionMeta {
     version: number;
     updatedBy?: string;
     filename?: string;
+    /**
+     * The integrator's own version-control revision the stored bundle was built from,
+     * as reported on upload. Absent for a bundle uploaded without one (e.g. by hand in
+     * the Merchant Center).
+     */
+    sourceRevision?: string;
+    /**
+     * Lifecycle state of THIS version. Absent when talking to an integration layer
+     * that predates bundle state — callers must treat `undefined` as "this deployment
+     * can't tell me", not as a failure.
+     */
+    state?: ExtensionState;
+    /** Why this version failed to load; only ever set alongside state "failed". */
+    reason?: string;
+    /**
+     * The version actually in use, which is NOT always `version`: when the newest
+     * upload failed to load, the integration layer serves the one beneath it and this
+     * reports that older one. `null` when nothing is in use. Returned by the meta read
+     * only, not by an upload's response.
+     *
+     * It carries the source revision as well as the number, because the number is the
+     * integration layer's own counter — the commit is what identifies the build to
+     * whoever pushed it.
+     */
+    served?: {
+        version: number;
+        sourceRevision?: string;
+    } | null;
 }
 export interface BreakingChange {
     type: string;
@@ -27,10 +65,32 @@ 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>;
-/** Upload the built bundle, replacing the project's stored one (`PUT …/extension/bundle`). */
-export declare function pushBundle(baseUrl: string, projectKey: string, token: string, bundle: string, filename: string): Promise<ExtensionMeta>;
+/**
+ * Upload the built bundle, replacing the project's stored one (`PUT …/extension/bundle`).
+ *
+ * `sourceRevision` (optional) records which of the integrator's revisions this build
+ * came from; the integration layer stores it against the revision, shows it in the
+ * Merchant Center, and hands it to the connector.
+ */
+export declare function pushBundle(baseUrl: string, projectKey: string, token: string, bundle: string, filename: string, sourceRevision?: string): Promise<ExtensionMeta>;
 /** The stored bundle's metadata, or null if none is stored (`GET …/extension/bundle/meta`). */
 export declare function fetchExtensionMeta(baseUrl: string, projectKey: string, token: string): Promise<ExtensionMeta | null>;
 /** Remove the project's extension subgraph from Hive (`DELETE …/extension/subgraph`). */

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`;
@@ -36,8 +64,14 @@ export async function remoteValidate(baseUrl, projectKey, token, typeDefs) {
     }
     return JSON.parse(text);
 }
-/** Upload the built bundle, replacing the project's stored one (`PUT …/extension/bundle`). */
-export async function pushBundle(baseUrl, projectKey, token, bundle, filename) {
+/**
+ * Upload the built bundle, replacing the project's stored one (`PUT …/extension/bundle`).
+ *
+ * `sourceRevision` (optional) records which of the integrator's revisions this build
+ * came from; the integration layer stores it against the revision, shows it in the
+ * Merchant Center, and hands it to the connector.
+ */
+export async function pushBundle(baseUrl, projectKey, token, bundle, filename, sourceRevision) {
     const url = `${apiRoot(baseUrl, projectKey)}/extension/bundle`;
     const res = await fetch(url, {
         method: "PUT",
@@ -46,6 +80,12 @@ export async function pushBundle(baseUrl, projectKey, token, bundle, filename) {
             // The route requires the original filename (percent-encoded; it carries the
             // module's type). The bundle is plain CommonJS, so name it `.cjs`.
             "x-extension-filename": encodeURIComponent(filename),
+            // Percent-encoded for the same reason as the filename: keep an arbitrary value
+            // header-safe. Omitted entirely when there's no revision to report — the route
+            // treats a missing header as "no revision", not an error.
+            ...(sourceRevision
+                ? { "x-extension-source-revision": encodeURIComponent(sourceRevision) }
+                : {}),
             ...bearer(token),
         },
         body: bundle,

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":"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"}

package/dist/lib/sourceRevision.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Longest revision the integration layer stores — it truncates past this. Applied
+ * here too so what the CLI prints is what actually gets stored, rather than a value
+ * the server silently shortens.
+ */
+export declare const MAX_SOURCE_REVISION_LENGTH = 200;
+/**
+ * Reduce a revision to printable ASCII, length-capped — matching the integration
+ * layer's own rule, so the CLI never reports a value different from the stored one.
+ * (The server sanitizes regardless; it doesn't trust its callers. This is about
+ * telling the user the truth.)
+ */
+export declare function sanitizeSourceRevision(value: string | undefined): string | undefined;
+/**
+ * The git revision describing `cwd`'s working copy, or null when it isn't a git
+ * checkout.
+ *
+ * `git describe --tags --always` gives the most human-meaningful identifier
+ * available, in decreasing order of usefulness: an exact tag (`v1.4.2`), a tag plus
+ * distance and commit (`v1.4.2-3-g1a2b3c4d`), or — with no tags at all — the bare
+ * commit (`1a2b3c4d`). That single command therefore covers "commit hash or tag"
+ * without the caller choosing.
+ *
+ * A `-dirty` suffix is appended from `git status --porcelain -- .` rather than
+ * `describe --dirty`, because `--dirty` ignores UNTRACKED files — and an untracked
+ * source file that the entry point imports is bundled into the artifact, so a build
+ * containing it is genuinely not the tagged commit. Scoped to `-- .` so it reflects
+ * the directory being pushed, not unrelated edits elsewhere in a monorepo.
+ */
+export declare function detectGitRevision(cwd: string): Promise<string | null>;
+/**
+ * The source revision to record for this push: the explicit value if the caller gave
+ * one, else whatever the working copy says, else nothing.
+ *
+ * Nothing is a legitimate outcome — a bundle built outside version control has no
+ * revision, and inventing one ("unknown", a timestamp) would put a value in the
+ * Merchant Center and in every connector log line that means nothing.
+ */
+export declare function resolveSourceRevision(explicit: string | undefined, cwd: string): Promise<string | undefined>;

package/dist/lib/sourceRevision.js

@@ -0,0 +1,95 @@
+// Where the bundle being pushed came from — the integrator's OWN version-control
+// revision, recorded against the stored bundle by the integration layer.
+//
+// The point is provenance: with this, the Merchant Center shows which revision a
+// project is running, the connector stamps it on every log line, and
+// `{ _extensionBundle { sourceRevision } }` answers it over GraphQL. So the default
+// has to be zero-effort — `extension push` reads the working copy and reports what
+// it finds, with no flag.
+//
+// GIT is auto-detected because that's what the examples and (nearly) every
+// integrator use. Any other VCS — hg, svn, Perforce, a CI build id — is supported
+// through `--source-revision` / `EXTENSION_SOURCE_REVISION` rather than a detector
+// per system: the integration layer treats the value as an OPAQUE string, so
+// whatever identifies a revision to the integrator is the right thing to send.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+/**
+ * Longest revision the integration layer stores — it truncates past this. Applied
+ * here too so what the CLI prints is what actually gets stored, rather than a value
+ * the server silently shortens.
+ */
+export const MAX_SOURCE_REVISION_LENGTH = 200;
+/**
+ * Reduce a revision to printable ASCII, length-capped — matching the integration
+ * layer's own rule, so the CLI never reports a value different from the stored one.
+ * (The server sanitizes regardless; it doesn't trust its callers. This is about
+ * telling the user the truth.)
+ */
+export function sanitizeSourceRevision(value) {
+    if (!value)
+        return undefined;
+    const cleaned = value
+        .replace(/[^\x20-\x7e]/g, "")
+        .trim()
+        .slice(0, MAX_SOURCE_REVISION_LENGTH);
+    return cleaned || undefined;
+}
+// Run a git command in `cwd`, or return null if git isn't available, this isn't a
+// repository, or the command has nothing to say. Provenance is a nice-to-have on a
+// push: never fail the push over it.
+async function git(args, cwd) {
+    try {
+        const { stdout } = await exec("git", args, { cwd, windowsHide: true });
+        const trimmed = stdout.trim();
+        return trimmed || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The git revision describing `cwd`'s working copy, or null when it isn't a git
+ * checkout.
+ *
+ * `git describe --tags --always` gives the most human-meaningful identifier
+ * available, in decreasing order of usefulness: an exact tag (`v1.4.2`), a tag plus
+ * distance and commit (`v1.4.2-3-g1a2b3c4d`), or — with no tags at all — the bare
+ * commit (`1a2b3c4d`). That single command therefore covers "commit hash or tag"
+ * without the caller choosing.
+ *
+ * A `-dirty` suffix is appended from `git status --porcelain -- .` rather than
+ * `describe --dirty`, because `--dirty` ignores UNTRACKED files — and an untracked
+ * source file that the entry point imports is bundled into the artifact, so a build
+ * containing it is genuinely not the tagged commit. Scoped to `-- .` so it reflects
+ * the directory being pushed, not unrelated edits elsewhere in a monorepo.
+ */
+export async function detectGitRevision(cwd) {
+    // Cheapest possible "is this a git checkout?" probe — everything below is
+    // pointless outside one, and this keeps a non-git working copy silent rather than
+    // noisy.
+    if (!(await git(["rev-parse", "--git-dir"], cwd)))
+        return null;
+    const described = await git(["describe", "--tags", "--always", "--abbrev=12"], cwd);
+    // A repository with no commits yet describes to nothing — there is no revision to
+    // report, so report none.
+    if (!described)
+        return null;
+    const dirt = await git(["status", "--porcelain", "--", "."], cwd);
+    return dirt ? `${described}-dirty` : described;
+}
+/**
+ * The source revision to record for this push: the explicit value if the caller gave
+ * one, else whatever the working copy says, else nothing.
+ *
+ * Nothing is a legitimate outcome — a bundle built outside version control has no
+ * revision, and inventing one ("unknown", a timestamp) would put a value in the
+ * Merchant Center and in every connector log line that means nothing.
+ */
+export async function resolveSourceRevision(explicit, cwd) {
+    if (explicit !== undefined)
+        return sanitizeSourceRevision(explicit);
+    return sanitizeSourceRevision((await detectGitRevision(cwd)) ?? undefined);
+}
+//# sourceMappingURL=sourceRevision.js.map

package/dist/lib/sourceRevision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceRevision.js","sourceRoot":"","sources":["../../src/lib/sourceRevision.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,yEAAyE;AACzE,EAAE;AACF,iFAAiF;AACjF,qEAAqE;AACrE,oFAAoF;AACpF,mFAAmF;AACnF,0BAA0B;AAC1B,EAAE;AACF,2EAA2E;AAC3E,kFAAkF;AAClF,mFAAmF;AACnF,6EAA6E;AAC7E,+EAA+E;AAE/E,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEjC;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAyB;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,OAAO,GAAG,KAAK;SAClB,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;SAC5B,IAAI,EAAE;SACN,KAAK,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAC;IACxC,OAAO,OAAO,IAAI,SAAS,CAAC;AAC9B,CAAC;AAED,kFAAkF;AAClF,mFAAmF;AACnF,qCAAqC;AACrC,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,GAAW;IAC5C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,OAAO,IAAI,IAAI,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAW;IACjD,0EAA0E;IAC1E,kFAAkF;IAClF,SAAS;IACT,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/D,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,CAAC;IACpF,kFAAkF;IAClF,0BAA0B;IAC1B,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAE5B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAA4B,EAC5B,GAAW;IAEX,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACpE,OAAO,sBAAsB,CAAC,CAAC,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC;AAC7E,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;