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

package/README.md

@@ -24,6 +24,7 @@ commercetools integration-layer init <DIR>               # scaffold an extension
 commercetools integration-layer extension build          # bundle src/extension.ts -> dist [local]
 commercetools integration-layer extension validate        # local checks + remote compose/breaking gate
 commercetools integration-layer extension push [--force]   # build + validate + upload the bundle
+                       [--source-revision <rev> | --no-source-revision]   # provenance; default: detected from git
 commercetools integration-layer extension status          # show the project's stored bundle
 commercetools integration-layer extension delete [--yes]   # remove the extension subgraph
 

package/dist/commands/integration-layer/extension/build.d.ts

@@ -5,6 +5,8 @@ export default class ExtensionBuild extends Command {
     static flags: {
         entry: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         out: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "extensions-dir": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/integration-layer/extension/build.js

@@ -1,19 +1,40 @@
 import { Command, Flags } from "@oclif/core";
-import { buildBundle, defaultEntry, defaultOutfile } from "../../../lib/tooling/build.js";
+import { defaultEntry, defaultOutfile } from "../../../lib/tooling/build.js";
+import { bundleForFlags } from "../../../lib/tooling/extensions.js";
 export default class ExtensionBuild extends Command {
     static description = "Bundle src/extension.ts into a single self-contained CommonJS artifact";
     static examples = [
         "<%= config.bin %> integration-layer extension build",
         "<%= config.bin %> integration-layer extension build --entry src/extension.ts --out dist/extension.js",
+        "<%= config.bin %> integration-layer extension build --all",
     ];
     static flags = {
         entry: Flags.string({ description: "extension entry source file", default: defaultEntry() }),
         out: Flags.string({ description: "bundle output file", default: defaultOutfile() }),
+        all: Flags.boolean({
+            description: "merge every extension under ./extensions/* into ONE combined bundle (the single artifact a project deploys)",
+            default: false,
+        }),
+        "extensions-dir": Flags.string({
+            description: "directory holding the extension packages (used with --all)",
+            default: "extensions",
+        }),
     };
     async run() {
         const { flags } = await this.parse(ExtensionBuild);
-        const { outfile } = await buildBundle(flags.entry, flags.out);
-        this.log(`✓ bundled ${flags.entry} → ${outfile}`);
+        let built;
+        try {
+            built = await bundleForFlags({
+                all: flags.all,
+                extensionsDir: flags["extensions-dir"],
+                entry: flags.entry,
+                out: flags.out,
+            });
+        }
+        catch (err) {
+            this.error(err.message);
+        }
+        this.log(`✓ bundled ${built.describe} → ${built.outfile}`);
     }
 }
 //# sourceMappingURL=build.js.map

package/dist/commands/integration-layer/extension/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../../src/commands/integration-layer/extension/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE1F,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,OAAO;IACjD,MAAM,CAAU,WAAW,GACzB,wEAAwE,CAAC;IAE3E,MAAM,CAAU,QAAQ,GAAG;QACzB,qDAAqD;QACrD,sGAAsG;KACvG,CAAC;IAEF,MAAM,CAAU,KAAK,GAAG;QACtB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,6BAA6B,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC;QAC5F,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC;KACpF,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACnD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9D,IAAI,CAAC,GAAG,CAAC,aAAa,KAAK,CAAC,KAAK,MAAM,OAAO,EAAE,CAAC,CAAC;IACpD,CAAC"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../../src/commands/integration-layer/extension/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEpE,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,OAAO;IACjD,MAAM,CAAU,WAAW,GACzB,wEAAwE,CAAC;IAE3E,MAAM,CAAU,QAAQ,GAAG;QACzB,qDAAqD;QACrD,sGAAsG;QACtG,2DAA2D;KAC5D,CAAC;IAEF,MAAM,CAAU,KAAK,GAAG;QACtB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,6BAA6B,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC;QAC5F,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC;QACnF,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC;YACjB,WAAW,EACT,6GAA6G;YAC/G,OAAO,EAAE,KAAK;SACf,CAAC;QACF,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC;YAC7B,WAAW,EAAE,4DAA4D;YACzE,OAAO,EAAE,YAAY;SACtB,CAAC;KACH,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACnD,IAAI,KAAK,CAAC;QACV,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,cAAc,CAAC;gBAC3B,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,aAAa,EAAE,KAAK,CAAC,gBAAgB,CAAC;gBACtC,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,aAAa,KAAK,CAAC,QAAQ,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7D,CAAC"}

package/dist/commands/integration-layer/extension/push.d.ts

@@ -5,8 +5,23 @@ export default class ExtensionPush extends IntegrationLayerCommand {
     static flags: {
         entry: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         out: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "extensions-dir": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "source-revision": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "no-source-revision": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "wait-timeout": import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
+    /**
+     * Report how the pushed version fared and say whether the command should fail.
+     *
+     * Only a genuine `failed` verdict is an error. Not being ABLE to find out — an
+     * older integration layer, an extension that isn't deployed, a metadata read that
+     * errored — is reported honestly and left as a success, because the push itself
+     * did land and failing it would break workflows that never had this signal.
+     */
+    private reportOutcome;
     /** True when the remote result should abort the push. */
     private reportRemote;
     run(): Promise<void>;

package/dist/commands/integration-layer/extension/push.js

@@ -1,25 +1,114 @@
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { Flags } from "@oclif/core";
-import { buildBundle, defaultEntry, defaultOutfile } from "../../../lib/tooling/build.js";
+import { defaultEntry, defaultOutfile } from "../../../lib/tooling/build.js";
+import { bundleForFlags } from "../../../lib/tooling/extensions.js";
 import { validateBundle, BundleValidationError } from "../../../lib/tooling/validateBundle.js";
 import { pushBundle, remoteValidate } from "../../../lib/ilClient.js";
+import { awaitBundleState } from "../../../lib/awaitBundleState.js";
+import { resolveSourceRevision } from "../../../lib/sourceRevision.js";
 import { IntegrationLayerCommand } from "../../../lib/base.js";
+// How often to re-read the bundle's status while waiting. The extension re-reads its
+// bundle on its own ~30s poll, so a tighter interval just adds requests without
+// learning anything sooner; 5s keeps the command feeling responsive when the
+// extension happens to be mid-poll already.
+const POLL_INTERVAL_MS = 5000;
+/**
+ * Name a build the way its author recognises it: the integration layer's version
+ * number AND the source revision it was built from. The number is an internal
+ * counter — the commit is the identity. Falls back to the bare version when the
+ * push recorded no revision.
+ */
+function describeBuild(version, sourceRevision) {
+    return sourceRevision
+        ? `version ${version} (source revision ${sourceRevision})`
+        : `version ${version}`;
+}
 export default class ExtensionPush extends IntegrationLayerCommand {
     static description = "Build + validate (local + remote) + upload the bundle, replacing the project's stored one";
     static examples = [
         "<%= config.bin %> integration-layer extension push",
         "<%= config.bin %> integration-layer extension push --force",
+        "<%= config.bin %> integration-layer extension push --all",
+        "<%= config.bin %> integration-layer extension push --source-revision r48211",
+        "<%= config.bin %> integration-layer extension push --no-source-revision",
     ];
     static flags = {
         entry: Flags.string({ description: "extension entry source file", default: defaultEntry() }),
         out: Flags.string({ description: "bundle output file", default: defaultOutfile() }),
+        all: Flags.boolean({
+            description: "merge every extension under ./extensions/* into ONE combined bundle and push that single artifact (the deployed shape)",
+            default: false,
+        }),
+        "extensions-dir": Flags.string({
+            description: "directory holding the extension packages (used with --all)",
+            default: "extensions",
+        }),
         force: Flags.boolean({
             char: "f",
             description: "upload despite a failing REMOTE validation (the local check always hard-fails)",
             default: false,
         }),
+        // Provenance. The default is auto-detection from the working copy, so a plain
+        // `push` records where the build came from with no ceremony; the flag is for a
+        // non-git VCS, a CI build id, or anything else the integrator identifies revisions
+        // by (the integration layer stores an opaque string).
+        "source-revision": Flags.string({
+            description: "version-control revision this build came from (default: detected from the git working copy; also settable via EXTENSION_SOURCE_REVISION)",
+            env: "EXTENSION_SOURCE_REVISION",
+            exclusive: ["no-source-revision"],
+        }),
+        "no-source-revision": Flags.boolean({
+            description: "push without recording any source revision",
+            default: false,
+        }),
+        // A push only STORES the bundle; the extension loads it on its own poll and
+        // reports back. Waiting for that verdict is the default because a push that
+        // reports success while the bundle can't actually run is the thing worth
+        // catching — especially in CI, where this is the difference between a green
+        // pipeline and a green pipeline that shipped a broken extension.
+        wait: Flags.boolean({
+            description: "wait for the extension to load the pushed version and report back (use --no-wait to return as soon as it is stored)",
+            default: true,
+            allowNo: true,
+        }),
+        "wait-timeout": Flags.integer({
+            description: "seconds to wait for the pushed version to be confirmed before giving up (the push still stands)",
+            default: 180,
+        }),
     };
+    /**
+     * Report how the pushed version fared and say whether the command should fail.
+     *
+     * Only a genuine `failed` verdict is an error. Not being ABLE to find out — an
+     * older integration layer, an extension that isn't deployed, a metadata read that
+     * errored — is reported honestly and left as a success, because the push itself
+     * did land and failing it would break workflows that never had this signal.
+     */
+    reportOutcome(outcome, version) {
+        switch (outcome.kind) {
+            case "running":
+                this.log(`✓ ${describeBuild(version, outcome.meta.sourceRevision)} is running — the extension loaded it and published its schema`);
+                return false;
+            case "failed": {
+                this.logToStderr(`✗ ${describeBuild(version, outcome.meta.sourceRevision)} could not be loaded and is NOT in use.`);
+                if (outcome.meta.reason)
+                    this.logToStderr(`  reason: ${outcome.meta.reason}`);
+                const served = outcome.meta.served;
+                this.logToStderr(served == null
+                    ? "  no stored version could be loaded, so this project currently has no extension running."
+                    : `  ${describeBuild(served.version, served.sourceRevision)} is still in use; fix the bundle and push again.`);
+                return true;
+            }
+            case "superseded":
+                this.log(`⚠ another push replaced version ${version} with ${describeBuild(outcome.meta.version, outcome.meta.sourceRevision)} while waiting; not reporting on it`);
+                return false;
+            case "unknown":
+                this.log(`⚠ could not confirm version ${version}: ${outcome.reason}`);
+                this.log("  the bundle is stored; check the extension panel in the Merchant Center.");
+                return false;
+        }
+    }
     /** True when the remote result should abort the push. */
     reportRemote(result) {
         if (!result.composes) {
@@ -45,7 +134,19 @@ export default class ExtensionPush extends IntegrationLayerCommand {
         const { flags } = await this.parse(ExtensionPush);
         // Bundle, then VALIDATE before we touch the store. Local check first — it always
         // hard-fails, regardless of --force.
-        const { outfile, sourceFiles } = await buildBundle(flags.entry, flags.out);
+        let outfile;
+        let sourceFiles;
+        try {
+            ({ outfile, sourceFiles } = await bundleForFlags({
+                all: flags.all,
+                extensionsDir: flags["extensions-dir"],
+                entry: flags.entry,
+                out: flags.out,
+            }));
+        }
+        catch (err) {
+            this.error(err.message);
+        }
         let typeDefs;
         try {
             const local = await validateBundle(outfile, sourceFiles);
@@ -74,10 +175,43 @@ export default class ExtensionPush extends IntegrationLayerCommand {
         }
         const bundle = await readFile(outfile, "utf8");
         const filename = `${basename(outfile).replace(/\.[^.]+$/, "")}.cjs`;
+        // Which of the integrator's revisions this build came from. Reported so the
+        // Merchant Center, the connector's log lines and `{ _extensionBundle }` can all
+        // name it. Detected from the working copy unless the caller said otherwise; a
+        // build outside version control simply reports none (see sourceRevision.ts).
+        const sourceRevision = flags["no-source-revision"]
+            ? undefined
+            : await resolveSourceRevision(flags["source-revision"], process.cwd());
+        if (sourceRevision) {
+            this.log(`Source revision: ${sourceRevision}`);
+        }
+        else if (!flags["no-source-revision"]) {
+            // Say so rather than staying silent: the operator console and the connector
+            // logs will show no revision for this push, and that's worth knowing now.
+            this.logToStderr("⚠ no source revision detected (not a git checkout?) — pushing without one. " +
+                "Pass --source-revision to record one explicitly.");
+        }
         const url = `${baseUrl}/${encodeURIComponent(projectKey)}/extension/bundle`;
         this.log(`Pushing extension bundle (${bundle.length} bytes) → ${url}`);
-        const meta = await pushBundle(baseUrl, projectKey, token, bundle, filename);
+        const meta = await pushBundle(baseUrl, projectKey, token, bundle, filename, sourceRevision);
         this.log(`✓ stored revision ${meta.version} (${meta.length} bytes, filename ${meta.filename ?? filename})`);
+        if (meta.sourceRevision) {
+            this.log(`  built from ${meta.sourceRevision}`);
+        }
+        if (!flags.wait) {
+            return;
+        }
+        // Storing it isn't running it. Wait for the extension to actually load this
+        // version and say so, and fail the command if it couldn't — otherwise a bundle
+        // the sandbox refuses to run exits 0 and looks like a successful push.
+        this.log(`Waiting for the extension to load version ${meta.version}…`);
+        const outcome = await awaitBundleState(baseUrl, projectKey, token, meta.version, {
+            timeoutMs: flags["wait-timeout"] * 1000,
+            intervalMs: POLL_INTERVAL_MS,
+        });
+        if (this.reportOutcome(outcome, meta.version)) {
+            this.error("The pushed bundle could not be loaded.");
+        }
     }
 }
 //# sourceMappingURL=push.js.map

package/dist/commands/integration-layer/extension/push.js.map

@@ -1 +1 @@
-{"version":3,"file":"push.js","sourceRoot":"","sources":["../../../../src/commands/integration-layer/extension/push.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"push.js","sourceRoot":"","sources":["../../../../src/commands/integration-layer/extension/push.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,cAAc,EAA+B,MAAM,0BAA0B,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAsB,MAAM,kCAAkC,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,qFAAqF;AACrF,gFAAgF;AAChF,6EAA6E;AAC7E,4CAA4C;AAC5C,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,SAAS,aAAa,CAAC,OAAe,EAAE,cAAuB;IAC7D,OAAO,cAAc;QACnB,CAAC,CAAC,WAAW,OAAO,qBAAqB,cAAc,GAAG;QAC1D,CAAC,CAAC,WAAW,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,uBAAuB;IAChE,MAAM,CAAU,WAAW,GACzB,2FAA2F,CAAC;IAE9F,MAAM,CAAU,QAAQ,GAAG;QACzB,oDAAoD;QACpD,4DAA4D;QAC5D,0DAA0D;QAC1D,6EAA6E;QAC7E,yEAAyE;KAC1E,CAAC;IAEF,MAAM,CAAU,KAAK,GAAG;QACtB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,6BAA6B,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC;QAC5F,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC;QACnF,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC;YACjB,WAAW,EACT,wHAAwH;YAC1H,OAAO,EAAE,KAAK;SACf,CAAC;QACF,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC;YAC7B,WAAW,EAAE,4DAA4D;YACzE,OAAO,EAAE,YAAY;SACtB,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YACnB,IAAI,EAAE,GAAG;YACT,WAAW,EAAE,gFAAgF;YAC7F,OAAO,EAAE,KAAK;SACf,CAAC;QACF,8EAA8E;QAC9E,+EAA+E;QAC/E,mFAAmF;QACnF,sDAAsD;QACtD,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC;YAC9B,WAAW,EACT,0IAA0I;YAC5I,GAAG,EAAE,2BAA2B;YAChC,SAAS,EAAE,CAAC,oBAAoB,CAAC;SAClC,CAAC;QACF,oBAAoB,EAAE,KAAK,CAAC,OAAO,CAAC;YAClC,WAAW,EAAE,4CAA4C;YACzD,OAAO,EAAE,KAAK;SACf,CAAC;QACF,4EAA4E;QAC5E,4EAA4E;QAC5E,yEAAyE;QACzE,4EAA4E;QAC5E,iEAAiE;QACjE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;YAClB,WAAW,EACT,qHAAqH;YACvH,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,IAAI;SACd,CAAC;QACF,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC;YAC5B,WAAW,EACT,iGAAiG;YACnG,OAAO,EAAE,GAAG;SACb,CAAC;KACH,CAAC;IAEF;;;;;;;OAOG;IACK,aAAa,CAAC,OAAsB,EAAE,OAAe;QAC3D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,SAAS;gBACZ,IAAI,CAAC,GAAG,CACN,KAAK,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,gEAAgE,CACzH,CAAC;gBACF,OAAO,KAAK,CAAC;YACf,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,IAAI,CAAC,WAAW,CACd,KAAK,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,yCAAyC,CAClG,CAAC;gBACF,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM;oBAAE,IAAI,CAAC,WAAW,CAAC,aAAa,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC9E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;gBACnC,IAAI,CAAC,WAAW,CACd,MAAM,IAAI,IAAI;oBACZ,CAAC,CAAC,0FAA0F;oBAC5F,CAAC,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC,kDAAkD,CAChH,CAAC;gBACF,OAAO,IAAI,CAAC;YACd,CAAC;YACD,KAAK,YAAY;gBACf,IAAI,CAAC,GAAG,CACN,mCAAmC,OAAO,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,qCAAqC,CACzJ,CAAC;gBACF,OAAO,KAAK,CAAC;YACf,KAAK,SAAS;gBACZ,IAAI,CAAC,GAAG,CAAC,+BAA+B,OAAO,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;gBACtE,IAAI,CAAC,GAAG,CAAC,2EAA2E,CAAC,CAAC;gBACtF,OAAO,KAAK,CAAC;QACjB,CAAC;IACH,CAAC;IAED,yDAAyD;IACjD,YAAY,CAAC,MAA8B;QACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,CAAC,qEAAqE,CAAC,CAAC;YACxF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,iBAAiB;gBAAE,IAAI,CAAC,WAAW,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;QAC7E,CAAC;aAAM,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,WAAW,CAAC,sEAAsE,CAAC,CAAC;YACzF,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;gBAC5C,IAAI,CAAC,WAAW,CAAC,QAAQ,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CACN,yGAAyG,CAC1G,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,qFAAqF,CAAC,CAAC;QAClG,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAElD,iFAAiF;QACjF,qCAAqC;QACrC,IAAI,OAAe,CAAC;QACpB,IAAI,WAAqB,CAAC;QAC1B,IAAI,CAAC;YACH,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,cAAc,CAAC;gBAC/C,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,aAAa,EAAE,KAAK,CAAC,gBAAgB,CAAC;gBACtC,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC,CAAC,CAAC;QACN,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,QAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACzD,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;YAC1B,IAAI,CAAC,GAAG,CACN,uCAAuC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,IAAI;gBACjF,mBAAmB,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CACpE,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,qBAAqB;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClE,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAE1E,iFAAiF;QACjF,yEAAyE;QACzE,yEAAyE;QACzE,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACxC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;oBACjB,IAAI,CAAC,KAAK,CAAC,uEAAuE,CAAC,CAAC;gBACtF,CAAC;gBACD,IAAI,CAAC,WAAW,CAAC,sDAAsD,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC;QAEpE,4EAA4E;QAC5E,gFAAgF;QAChF,8EAA8E;QAC9E,6EAA6E;QAC7E,MAAM,cAAc,GAAG,KAAK,CAAC,oBAAoB,CAAC;YAChD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,MAAM,qBAAqB,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACzE,IAAI,cAAc,EAAE,CAAC;YACnB,IAAI,CAAC,GAAG,CAAC,oBAAoB,cAAc,EAAE,CAAC,CAAC;QACjD,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,EAAE,CAAC;YACxC,4EAA4E;YAC5E,0EAA0E;YAC1E,IAAI,CAAC,WAAW,CACd,6EAA6E;gBAC3E,kDAAkD,CACrD,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,kBAAkB,CAAC,UAAU,CAAC,mBAAmB,CAAC;QAC5E,IAAI,CAAC,GAAG,CAAC,6BAA6B,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;QAC5F,IAAI,CAAC,GAAG,CAAC,qBAAqB,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM,oBAAoB,IAAI,CAAC,QAAQ,IAAI,QAAQ,GAAG,CAAC,CAAC;QAC5G,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QAED,4EAA4E;QAC5E,+EAA+E;QAC/E,uEAAuE;QACvE,IAAI,CAAC,GAAG,CAAC,6CAA6C,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;QACvE,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE;YAC/E,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,GAAG,IAAI;YACvC,UAAU,EAAE,gBAAgB;SAC7B,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC"}

package/dist/commands/integration-layer/extension/serve.d.ts

@@ -7,12 +7,31 @@ export default class ExtensionServe extends IntegrationLayerCommand {
         port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         compose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         gateway: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "extensions-dir": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    /**
+     * `--all`: merge every extension under `./extensions/*` into ONE federation subgraph —
+     * the single bundle a project deploys — and serve it behind a local federated gateway
+     * with the deployed integration layer, exactly the two-subgraph shape the router plans
+     * over (core + the combined `extensions` subgraph). Like `--gateway` it reaches the
+     * integration layer (fetches its SDL, mints an anonymous session), so it needs a
+     * `commercetools auth login`. Watches every extension and hot-reloads: any edit
+     * re-merges the combined subgraph, and a schema change recomposes + rebuilds the gateway.
+     */
+    private runAll;
     /**
      * Start esbuild in watch mode over the current example and feed `onBuild` a freshly
      * loaded subgraph on every (re)build. Resolves once the initial build has produced
      * one (so the caller can start serving); later rebuilds fire `onBuild` again.
      */
     private watchAndBuild;
+    /**
+     * The generic watcher underneath {@link watchAndBuild}: esbuild-watch `entry`, and on
+     * every successful (re)build load the bundle and hand the raw module to `onReload`.
+     * `--all` uses this directly (it needs the module's resolvers to merge subgraphs);
+     * single-mode wraps it to build one subgraph.
+     */
+    private watchEntry;
 }

package/dist/commands/integration-layer/extension/serve.js

@@ -23,7 +23,8 @@ import { buildSubgraphSchema } from "@apollo/subgraph";
 import { context as esbuildContext } from "esbuild";
 import { defaultEntry, defaultOutfile, HOST_PROVIDED_EXTERNALS } from "../../../lib/tooling/build.js";
 import { loadBundleSource } from "../../../lib/tooling/loadBundle.js";
-import { composeWithIntegrationLayer, } from "../../../lib/tooling/compose.js";
+import { composeWithIntegrationLayer } from "../../../lib/tooling/compose.js";
+import { discoverExtensions, mergeExtensionSubgraph } from "../../../lib/tooling/extensions.js";
 import { makeGateway, mintAnonymousSession } from "../../../lib/tooling/gateway.js";
 import { fetchSubgraphSdl } from "../../../lib/ilClient.js";
 import { IntegrationLayerCommand } from "../../../lib/base.js";
@@ -84,9 +85,21 @@ export default class ExtensionServe extends IntegrationLayerCommand {
             description: "make /graphql an executable federated gateway over both subgraphs",
             default: false,
         }),
+        all: Flags.boolean({
+            description: "merge every extension under ./extensions/* into ONE subgraph (the single deployed bundle) and serve it behind a local federated gateway with the integration layer",
+            default: false,
+        }),
+        "extensions-dir": Flags.string({
+            description: "directory holding the extension packages (used with --all)",
+            default: "extensions",
+        }),
     };
     async run() {
         const { flags } = await this.parse(ExtensionServe);
+        if (flags.all) {
+            await this.runAll(flags);
+            return;
+        }
         const entry = defaultEntry();
         const outfile = defaultOutfile();
         const port = flags.port;
@@ -253,16 +266,211 @@ export default class ExtensionServe extends IntegrationLayerCommand {
         // Keep the process alive; the server + esbuild watcher run until a signal.
         await new Promise(() => { });
     }
+    /**
+     * `--all`: merge every extension under `./extensions/*` into ONE federation subgraph —
+     * the single bundle a project deploys — and serve it behind a local federated gateway
+     * with the deployed integration layer, exactly the two-subgraph shape the router plans
+     * over (core + the combined `extensions` subgraph). Like `--gateway` it reaches the
+     * integration layer (fetches its SDL, mints an anonymous session), so it needs a
+     * `commercetools auth login`. Watches every extension and hot-reloads: any edit
+     * re-merges the combined subgraph, and a schema change recomposes + rebuilds the gateway.
+     */
+    async runAll(flags) {
+        const port = flags.port;
+        const root = process.cwd();
+        const extensions = await discoverExtensions(root, flags["extensions-dir"]);
+        if (extensions.length === 0) {
+            this.error(`no extensions found under ./${flags["extensions-dir"]}/*/src/extension.ts — run --all from the monorepo root`);
+        }
+        // Reach the integration layer exactly like --gateway: its core-subgraph SDL is the
+        // compose baseline, and an anonymous session authenticates the gateway's calls.
+        const { baseUrl, projectKey, token } = await this.resolveIlContext(flags);
+        const integrationLayerGraphqlUrl = `${baseUrl}/${encodeURIComponent(projectKey)}/graphql`;
+        this.log(`Fetching integration-layer subgraph SDL for '${projectKey}' from ${baseUrl} …`);
+        const integrationLayerSdl = await fetchSubgraphSdl(baseUrl, projectKey, token);
+        const integrationLayerBearer = await mintAnonymousSession(baseUrl, projectKey);
+        this.log("Minted an anonymous session for the gateway.");
+        // The single combined-extensions subgraph endpoint — the gateway's one data source
+        // besides the integration layer, named `extensions` just like the deployed bundle.
+        const extensionUrl = `http://localhost:${port}/_extension`;
+        // Per-extension loaded module (typeDefs + resolvers), merged into ONE subgraph on
+        // each rebuild. The yoga factories/gateway close over these so a reload applies with
+        // no restart.
+        const modules = new Map();
+        let combinedSchema;
+        let composed;
+        let gatewayYoga;
+        let gatewaySupergraphSdl;
+        let apolloGateway;
+        const log = (m) => this.log(m);
+        const warn = (m) => this.logToStderr(m);
+        // Merge all extensions into one subgraph, compose with the integration layer, and
+        // (re)build the gateway when the supergraph changes. No-op until every extension has
+        // produced its first build; a string-compare skips the gateway rebuild for a
+        // resolver-only edit (the /_extension hot-reload alone covers it).
+        const recompose = async () => {
+            if (modules.size < extensions.length)
+                return;
+            try {
+                const merged = mergeExtensionSubgraph([...modules].map(([name, m]) => ({ name, typeDefs: m.typeDefs, resolvers: m.resolvers })));
+                combinedSchema = merged.schema;
+                composed = composeWithIntegrationLayer(integrationLayerSdl, merged.sdl, {
+                    integrationLayerUrl: integrationLayerGraphqlUrl,
+                    extensionUrl,
+                });
+            }
+            catch (err) {
+                warn(`✗ ${err.message}`);
+                return;
+            }
+            if (!composed.ok) {
+                warn("✗ extensions do not compose with the integration layer:");
+                for (const e of composed.errors)
+                    warn(`  - ${e}`);
+                return;
+            }
+            log(`✓ composes with the integration layer — full schema at http://localhost:${port}/composed`);
+            if (composed.supergraphSdl === gatewaySupergraphSdl) {
+                log("  (gateway plan unchanged — extension reloaded in place)");
+                return;
+            }
+            try {
+                const gw = await makeGateway({ supergraphSdl: composed.supergraphSdl, integrationLayerBearer });
+                const prev = apolloGateway;
+                apolloGateway = gw;
+                gatewaySupergraphSdl = composed.supergraphSdl;
+                gatewayYoga = createYoga({
+                    plugins: [useApolloFederation({ gateway: gw })],
+                    graphqlEndpoint: "/graphql",
+                    landingPage: false,
+                });
+                log(`✓ gateway ready at http://localhost:${port}/graphql`);
+                if (prev)
+                    await prev.stop();
+            }
+            catch (err) {
+                warn(`✗ gateway build failed: ${err.message}`);
+            }
+        };
+        // Watch + build each extension; awaiting sequentially means the last first-build
+        // triggers the initial merge/compose. `recompose` fires again on every later rebuild.
+        const contexts = [];
+        for (const ext of extensions) {
+            const ctx = await this.watchEntry(ext.entry, ext.outfile, async (mod) => {
+                const { typeDefs, resolvers } = mod;
+                if (typeof typeDefs !== "string" || typeDefs.trim() === "") {
+                    warn(`✗ extension '${ext.name}' exported no \`typeDefs\` string`);
+                    return;
+                }
+                if (resolvers === null || typeof resolvers !== "object") {
+                    warn(`✗ extension '${ext.name}' exported no \`resolvers\` object`);
+                    return;
+                }
+                modules.set(ext.name, { typeDefs, resolvers });
+                await recompose();
+            });
+            contexts.push(ctx);
+        }
+        if (!combinedSchema) {
+            for (const ctx of contexts)
+                await ctx.dispose();
+            this.error("extensions did not merge into a subgraph (see errors above)");
+        }
+        if (composed && !composed.ok) {
+            warn("⚠ extensions do not compose with the integration layer yet — the gateway is " +
+                "unavailable until they do; fix the errors above and save to recompose.");
+        }
+        // The combined extensions subgraph (executable), at the internal /_extension the
+        // gateway reaches over HTTP. `schema: () => …` re-reads the latest merge, so a
+        // hot-reload applies with no restart.
+        const subgraphYoga = createYoga({
+            schema: () => combinedSchema,
+            context: () => devContext(),
+            graphqlEndpoint: "/_extension",
+            landingPage: false,
+        });
+        // The browsable (not executable) merged API schema.
+        const composedYoga = createYoga({
+            schema: () => {
+                if (!composed?.ok) {
+                    throw new Error(`extensions do not compose with the integration layer:\n${(composed?.errors ?? []).join("\n")}`);
+                }
+                return composed.apiSchema;
+            },
+            graphqlEndpoint: "/composed",
+            landingPage: false,
+        });
+        const server = createServer((req, res) => {
+            const path = (req.url ?? "").split("?")[0];
+            if (req.method === "GET" && (path === "/schema.graphql" || path === "/supergraph.graphql")) {
+                if (!composed?.ok) {
+                    res.statusCode = 503;
+                    res.setHeader("content-type", "text/plain");
+                    res.end(`extensions do not compose with the integration layer:\n${(composed?.errors ?? []).join("\n")}\n`);
+                    return;
+                }
+                res.setHeader("content-type", "text/plain; charset=utf-8");
+                res.end(path === "/schema.graphql" ? composed.apiSdl : composed.supergraphSdl);
+                return;
+            }
+            if (path.startsWith("/composed"))
+                return void composedYoga(req, res);
+            if (path.startsWith("/graphql")) {
+                if (!gatewayYoga) {
+                    const errs = composed && !composed.ok ? composed.errors : [];
+                    res.statusCode = 503;
+                    res.setHeader("content-type", "text/plain");
+                    res.end(`gateway not ready — extensions do not compose with the integration layer:\n${errs.join("\n")}\n`);
+                    return;
+                }
+                return void gatewayYoga(req, res);
+            }
+            // /_extension — the combined extensions subgraph.
+            return void subgraphYoga(req, res);
+        });
+        await new Promise((resolve) => server.listen(port, resolve));
+        const base = `http://localhost:${port}`;
+        const names = extensions.map((e) => e.name).join(", ");
+        const lines = [
+            `\n🔌 ${extensions.length} extension(s) merged into one subgraph (${names}), live behind a federated gateway:`,
+        ];
+        lines.push(`   ${base}/graphql   — FEDERATED gateway (combined extensions + deployed integration layer)`);
+        lines.push(`   ${base}/_extension — the combined extensions subgraph (gateway routes to it)`);
+        lines.push(`   ${base}/composed  — full merged schema (browsable; not executable)`);
+        lines.push(`   ${base}/schema.graphql, ${base}/supergraph.graphql — SDL (text)`);
+        lines.push(`   open ${base}/graphql in a browser for GraphiQL`);
+        lines.push(`   watching ${extensions.length} extension(s) — edit and save to hot-reload\n`);
+        this.log(lines.join("\n"));
+        const shutdown = () => {
+            for (const ctx of contexts)
+                void ctx.dispose();
+            server.close(() => process.exit(0));
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        // Keep the process alive; the server + esbuild watchers run until a signal.
+        await new Promise(() => { });
+    }
     /**
      * Start esbuild in watch mode over the current example and feed `onBuild` a freshly
      * loaded subgraph on every (re)build. Resolves once the initial build has produced
      * one (so the caller can start serving); later rebuilds fire `onBuild` again.
      */
     async watchAndBuild(entry, outfile, onBuild) {
+        return this.watchEntry(entry, outfile, async (mod) => {
+            await onBuild(buildSubgraph(mod));
+        });
+    }
+    /**
+     * The generic watcher underneath {@link watchAndBuild}: esbuild-watch `entry`, and on
+     * every successful (re)build load the bundle and hand the raw module to `onReload`.
+     * `--all` uses this directly (it needs the module's resolvers to merge subgraphs);
+     * single-mode wraps it to build one subgraph.
+     */
+    async watchEntry(entry, outfile, onReload) {
         const reload = async () => {
             const source = await readFile(outfile, "utf8");
-            const mod = loadBundleSource(source);
-            await onBuild(buildSubgraph(mod));
+            await onReload(loadBundleSource(source));
         };
         let firstBuildDone;
         const firstBuild = new Promise((resolve) => {