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

package/dist/lib/base.d.ts

@@ -0,0 +1,50 @@
+import { AuthCommand, CtpAuthorizedClient } from "@commercetools/cli-plugin-auth";
+/** 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. */
+    baseUrl: string;
+    projectKey: string;
+    /** The logged-in principal's commercetools access token (the `manage_project` bearer). */
+    token: string;
+}
+/** The subset of parsed flags {@link IntegrationLayerCommand.resolveIlContext} reads. */
+export interface IlFlagValues {
+    "integration-layer-url"?: string;
+    "project-key"?: string;
+}
+/**
+ * Derive the integration-layer EXTENSIONS edge base URL from the authenticated
+ * principal's commercetools region. The extensions edge — the connector-backend pod
+ * that serves the CLI's `/<project>/subgraph` + `/<project>/extension/*` routes —
+ * follows the same host convention as the commercetools API itself
+ * (`<svc>.<region>.commercetools.com`, cf. the auth client's
+ * `auth.<region>.commercetools.com`), so a login in region `eu-central-1.aws`
+ * resolves to `https://extensions.integration-layer.eu-central-1.aws.commercetools.com`
+ * (the production host). `--integration-layer-url` / `INTEGRATION_LAYER_URL` stays
+ * the explicit override — e.g. to point at a local edge or a staging edge on the
+ * escemo/stage zone, which don't follow the production convention. Returns undefined
+ * only when the region is absent, so resolveIlContext then fails loudly.
+ */
+export declare function edgeUrlForRegion(region: string): string | undefined;
+export declare abstract class IntegrationLayerCommand extends AuthCommand {
+    /**
+     * Whether the command needs a logged-in principal. True for every command that
+     * calls the integration layer; a command that only conditionally reaches it (e.g.
+     * `serve` in standalone mode) sets this false and relies on {@link resolveIlContext}
+     * to fail loudly if the network path is actually taken.
+     */
+    protected authorized: boolean;
+    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>;
+    /** The logged-in commercetools principal, or an `AuthorizationError` pointing at `auth login`. */
+    protected requirePrincipal(): CtpAuthorizedClient;
+    /**
+     * Resolve the integration-layer base URL + project key from the login context and
+     * take the principal's access token as the bearer. Fails loudly (no defensive
+     * defaults) when a required value is absent.
+     */
+    protected resolveIlContext(flags: IlFlagValues): Promise<IlContext>;
+}

package/dist/lib/base.js

@@ -0,0 +1,85 @@
+// 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.
+//
+// `@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).
+import { Flags } from "@oclif/core";
+import { AuthCommand, AuthorizationError, CtpAuthorizedClient, } from "@commercetools/cli-plugin-auth";
+/**
+ * Derive the integration-layer EXTENSIONS edge base URL from the authenticated
+ * principal's commercetools region. The extensions edge — the connector-backend pod
+ * that serves the CLI's `/<project>/subgraph` + `/<project>/extension/*` routes —
+ * follows the same host convention as the commercetools API itself
+ * (`<svc>.<region>.commercetools.com`, cf. the auth client's
+ * `auth.<region>.commercetools.com`), so a login in region `eu-central-1.aws`
+ * resolves to `https://extensions.integration-layer.eu-central-1.aws.commercetools.com`
+ * (the production host). `--integration-layer-url` / `INTEGRATION_LAYER_URL` stays
+ * the explicit override — e.g. to point at a local edge or a staging edge on the
+ * escemo/stage zone, which don't follow the production convention. Returns undefined
+ * only when the region is absent, so resolveIlContext then fails loudly.
+ */
+export function edgeUrlForRegion(region) {
+    const trimmed = region.trim();
+    if (!trimmed)
+        return undefined;
+    return `https://extensions.integration-layer.${trimmed}.commercetools.com`;
+}
+export class IntegrationLayerCommand extends AuthCommand {
+    /**
+     * Whether the command needs a logged-in principal. True for every command that
+     * calls the integration layer; a command that only conditionally reaches it (e.g.
+     * `serve` in standalone mode) sets this false and relies on {@link resolveIlContext}
+     * to fail loudly if the network path is actually taken.
+     */
+    authorized = true;
+    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",
+            env: "INTEGRATION_LAYER_URL",
+            helpGroup: "INTEGRATION LAYER",
+        }),
+        "project-key": Flags.string({
+            description: "override the logged-in project key",
+            helpGroup: "INTEGRATION LAYER",
+        }),
+    };
+    async init() {
+        await super.init();
+        if (this.authorized)
+            this.requirePrincipal();
+    }
+    /** The logged-in commercetools principal, or an `AuthorizationError` pointing at `auth login`. */
+    requirePrincipal() {
+        const principal = this.getAuthentication()?.getPrincipal();
+        if (principal instanceof CtpAuthorizedClient)
+            return principal;
+        throw new AuthorizationError("not logged in — run `commercetools auth login` first");
+    }
+    /**
+     * Resolve the integration-layer base URL + project key from the login context and
+     * take the principal's access token as the bearer. Fails loudly (no defensive
+     * defaults) when a required value is absent.
+     */
+    async resolveIlContext(flags) {
+        const principal = this.requirePrincipal();
+        const token = principal.getAccessToken().getTokenValue();
+        const projectKey = flags["project-key"] ?? principal.getProjectKey();
+        if (!projectKey) {
+            throw new Error("no project key — log in with `commercetools auth login --project-key <key>` or pass --project-key");
+        }
+        const baseUrl = flags["integration-layer-url"] ?? edgeUrlForRegion(principal.getRegion());
+        if (!baseUrl) {
+            throw new Error("could not resolve the integration layer URL: pass --integration-layer-url or set " +
+                "INTEGRATION_LAYER_URL (the extensions edge base, e.g. " +
+                "https://extensions.integration-layer.eu-central-1.aws.commercetools.com)");
+        }
+        return { baseUrl: baseUrl.replace(/\/+$/, ""), projectKey, token };
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/lib/base.js.map

@@ -0,0 +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"}

package/dist/lib/ilClient.d.ts

@@ -0,0 +1,93 @@
+/** A single {key,value,secret} entry of a project's extension config (secret values redacted on read). */
+export interface ConfigEntry {
+    key: string;
+    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;
+    length: number;
+    uploadedAt: number;
+    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;
+    description: string;
+}
+export interface RemoteValidationResult {
+    valid: boolean;
+    composes: boolean;
+    compositionErrors: string[];
+    breakingChanges: BreakingChange[];
+    /** False when no published baseline was available, so the breaking check was skipped. */
+    comparedToPublished: boolean;
+}
+/** 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>;
+/** 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`).
+ *
+ * `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`). */
+export declare function deleteExtensionSubgraph(baseUrl: string, projectKey: string, token: string): Promise<void>;
+/** List the project's extension config entries, secret values redacted (`GET …/extension/config`). */
+export declare function listConfig(baseUrl: string, projectKey: string, token: string): Promise<ConfigEntry[]>;
+/**
+ * Upsert/delete config entries and return the resulting (redacted) list
+ * (`PATCH …/extension/config`). An entry with `value: null` deletes that key. PATCH
+ * (not PUT) so a single set/unset touches one key without clobbering the rest.
+ */
+export declare function patchConfig(baseUrl: string, projectKey: string, token: string, entries: Array<{
+    key: string;
+    value: string | null;
+    secret?: boolean;
+}>): Promise<ConfigEntry[]>;

package/dist/lib/ilClient.js

@@ -0,0 +1,120 @@
+// Low-level HTTP client for the integration layer's per-project manage-surface
+// routes. Every call is parameterised by (baseUrl, projectKey, token) — the command
+// layer resolves those (`IntegrationLayerCommand.resolveIlContext`, whose token is the
+// `commercetools auth login` principal's) and this module just speaks the wire
+// protocol. The route bodies these mirror live in the integration
+// layer's `routes/manage.ts`; the request/response shapes here are extracted from the
+// `ee-ext` tooling's `remoteValidate.ts` / `push.ts` (which read them from env) and
+// the remaining manage routes (config, status, delete, subgraph).
+function apiRoot(baseUrl, projectKey) {
+    return `${baseUrl.replace(/\/+$/, "")}/${encodeURIComponent(projectKey)}`;
+}
+function bearer(token) {
+    return { Authorization: `Bearer ${token}` };
+}
+/** GET the project's raw core-subgraph SDL — the compose input (`GET …/subgraph`). */
+export async function fetchSubgraphSdl(baseUrl, projectKey, token) {
+    const url = `${apiRoot(baseUrl, projectKey)}/subgraph`;
+    const res = await fetch(url, { headers: { accept: "text/plain", ...bearer(token) } });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`could not fetch core-subgraph SDL (${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`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...bearer(token) },
+        body: JSON.stringify({ typeDefs }),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`schema validation request failed (${res.status}): ${text}`);
+    }
+    return JSON.parse(text);
+}
+/**
+ * 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",
+        headers: {
+            "Content-Type": "text/javascript",
+            // 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,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`PUT extension/bundle failed (${res.status}): ${text}`);
+    }
+    return JSON.parse(text);
+}
+/** The stored bundle's metadata, or null if none is stored (`GET …/extension/bundle/meta`). */
+export async function fetchExtensionMeta(baseUrl, projectKey, token) {
+    const url = `${apiRoot(baseUrl, projectKey)}/extension/bundle/meta`;
+    const res = await fetch(url, { headers: { accept: "application/json", ...bearer(token) } });
+    if (res.status === 404)
+        return null;
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`GET extension/bundle/meta failed (${res.status}): ${text}`);
+    }
+    return JSON.parse(text);
+}
+/** Remove the project's extension subgraph from Hive (`DELETE …/extension/subgraph`). */
+export async function deleteExtensionSubgraph(baseUrl, projectKey, token) {
+    const url = `${apiRoot(baseUrl, projectKey)}/extension/subgraph`;
+    const res = await fetch(url, { method: "DELETE", headers: { ...bearer(token) } });
+    if (!res.ok && res.status !== 204) {
+        const text = await res.text();
+        throw new Error(`DELETE extension/subgraph failed (${res.status}): ${text}`);
+    }
+}
+/** List the project's extension config entries, secret values redacted (`GET …/extension/config`). */
+export async function listConfig(baseUrl, projectKey, token) {
+    const url = `${apiRoot(baseUrl, projectKey)}/extension/config`;
+    const res = await fetch(url, { headers: { accept: "application/json", ...bearer(token) } });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`GET extension/config failed (${res.status}): ${text}`);
+    }
+    return JSON.parse(text);
+}
+/**
+ * Upsert/delete config entries and return the resulting (redacted) list
+ * (`PATCH …/extension/config`). An entry with `value: null` deletes that key. PATCH
+ * (not PUT) so a single set/unset touches one key without clobbering the rest.
+ */
+export async function patchConfig(baseUrl, projectKey, token, entries) {
+    const url = `${apiRoot(baseUrl, projectKey)}/extension/config`;
+    const res = await fetch(url, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json", ...bearer(token) },
+        body: JSON.stringify(entries),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`PATCH extension/config failed (${res.status}): ${text}`);
+    }
+    return JSON.parse(text);
+}
+//# sourceMappingURL=ilClient.js.map

package/dist/lib/ilClient.js.map

@@ -0,0 +1 @@
+{"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/apiExtension.d.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAction, ExtensionInput } from '@commercetools/platform-sdk';
+export type { ExtensionInput };
+export type ApiExtensionAction = Extract<ExtensionAction, 'Create' | 'Update'>;
+export interface ExtensionContext {
+    now(): number;
+    config: Readonly<Record<string, string>>;
+}
+export type ApiExtensionInput = ExtensionInput;
+export interface ApiExtensionError {
+    code: string;
+    message: string;
+}
+export type ApiExtensionResult = void | {
+    actions?: unknown[];
+    errors?: ApiExtensionError[];
+};
+export interface ApiExtensionDefinition {
+    key: string;
+    resourceTypeId: string;
+    actions: ApiExtensionAction[];
+    condition?: string;
+    handler: (input: ApiExtensionInput, ctx: ExtensionContext) => ApiExtensionResult | Promise<ApiExtensionResult>;
+}
+/** Identity helper — declare an API-Extension handler, type-checked against the SDK payload. */
+export declare function defineApiExtension(definition: ApiExtensionDefinition): ApiExtensionDefinition;
+/** Approve the write unchanged. */
+export declare function approve(): ApiExtensionResult;
+/** Block the write with a validation error (commercetools returns it to the caller). */
+export declare function block(code: string, message: string): ApiExtensionResult;
+/** Apply commercetools update actions to the triggering resource. */
+export declare function update(actions: unknown[]): ApiExtensionResult;

package/dist/lib/tooling/apiExtension.js

@@ -0,0 +1,39 @@
+// Authoring API for commercetools API Extensions.
+//
+// Copied verbatim from commercetools/integration-layer-extension-examples
+// (packages/tooling/src/apiExtension.ts). An API Extension is the commercetools
+// platform feature: a synchronous HTTP callback commercetools makes before
+// persisting a cart/order/… create or update, which can approve, modify, or BLOCK
+// the write. This is a DIFFERENT thing from a GraphQL schema extension (typeDefs +
+// resolvers), which adds fields to the graph. A bundle may export `apiExtensions`,
+// `typeDefs`/`resolvers`, or both.
+//
+// A handler is a plain function `(input, ctx) => result`. Use `defineApiExtension`
+// for type checking and the `approve` / `block` / `update` helpers to return intent
+// instead of hand-rolling the wire shape. The runtime (the sandbox) maps the result
+// to commercetools' response contract.
+//
+// The RECEIVED payload is the commercetools SDK's own `ExtensionInput` — you don't
+// define the resource types. Its `resource` is the discriminated `Reference` union,
+// so narrowing on `input.resource.typeId === 'cart'` gives you `resource.obj` typed
+// as the real `Cart` (and so on). These are type-only imports (erased by the
+// bundler), so they add nothing to the pushed bundle. The SDK does NOT model the
+// RESPONSE envelope (approve/block/actions is an HTTP contract, not a resource), so
+// `ApiExtensionResult` / `ApiExtensionError` below stay local.
+/** Identity helper — declare an API-Extension handler, type-checked against the SDK payload. */
+export function defineApiExtension(definition) {
+    return definition;
+}
+/** Approve the write unchanged. */
+export function approve() {
+    return {};
+}
+/** Block the write with a validation error (commercetools returns it to the caller). */
+export function block(code, message) {
+    return { errors: [{ code, message }] };
+}
+/** Apply commercetools update actions to the triggering resource. */
+export function update(actions) {
+    return { actions };
+}
+//# sourceMappingURL=apiExtension.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apiExtension.js","sourceRoot":"","sources":["../../../src/lib/tooling/apiExtension.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,0EAA0E;AAC1E,gFAAgF;AAChF,2EAA2E;AAC3E,kFAAkF;AAClF,mFAAmF;AACnF,mFAAmF;AACnF,mCAAmC;AACnC,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,oFAAoF;AACpF,uCAAuC;AACvC,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,oFAAoF;AACpF,6EAA6E;AAC7E,iFAAiF;AACjF,oFAAoF;AACpF,+DAA+D;AA+C/D,gGAAgG;AAChG,MAAM,UAAU,kBAAkB,CAAC,UAAkC;IACnE,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,OAAO;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,OAAe;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACzC,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,MAAM,CAAC,OAAkB;IACvC,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

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

@@ -0,0 +1,18 @@
+/** Peer modules the runtime owns — bundled never, resolved at load time. */
+export declare const HOST_PROVIDED_EXTERNALS: string[];
+/** The extension source of the example the tool is invoked inside (cwd-relative). */
+export declare function defaultEntry(): string;
+/** The bundle output for the example the tool is invoked inside (cwd-relative). */
+export declare function defaultOutfile(): string;
+export interface BuildResult {
+    /** Absolute path to the bundled artifact. */
+    outfile: string;
+    /**
+     * The author's own source files that went into the bundle (entry + local
+     * imports), absolute paths. npm packages are excluded — these feed the static
+     * analyzer, which only checks code the author wrote.
+     */
+    sourceFiles: string[];
+}
+/** Bundle `entry` into a single self-contained CJS file at `outfile`. */
+export declare function buildBundle(entry?: string, outfile?: string): Promise<BuildResult>;