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

package/dist/commands/integration-layer/init.js

@@ -1,105 +1,252 @@
 import { mkdir, readdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { Args, Command, Flags } from "@oclif/core";
-// The `basic` template is vendored inline (no network fetch) — a minimal, buildable
-// extension: a GraphQL subgraph field plus a commented API-Extension example. Keep it
-// dependency-light so `extension build`/`validate` work on it out of the box.
-const TEMPLATE_FILES = {
-    "src/extension.ts": `// A minimal integration-layer extension.
-//
-// Export a GraphQL subgraph (\`typeDefs\` + \`resolvers\`) to add fields to the graph,
-// and/or \`apiExtensions\` to run synchronous commercetools cart/order callbacks.
-// Build it with:  commercetools integration-layer extension build
-// Serve it with:  commercetools integration-layer extension serve
-
-export const typeDefs = /* GraphQL */ \`
-  type Query {
-    extensionInfo: String
-  }
-\`;
-
-export const resolvers = {
-  Query: {
-    extensionInfo: () => "hello from the integration-layer extension",
-  },
-};
-
-// // Example API Extension (uncomment to block a cart line item by SKU):
-// export const apiExtensions = [
-//   {
-//     key: "block-sku",
-//     resourceTypeId: "cart",
-//     actions: ["Create", "Update"],
-//     handler: (input, ctx) => {
-//       const blocked = ctx.config.BLOCKED_SKU ?? "BLOCKED-SKU";
-//       const items = input.resource.obj?.lineItems ?? [];
-//       if (items.some((li) => li.variant?.sku === blocked)) {
-//         return { errors: [{ code: "SkuBlocked", message: \\\`\\\${blocked} is not purchasable\\\` }] };
-//       }
-//       return {};
-//     },
-//   },
-// ];
-`,
-    "package.json": `{
-  "name": "integration-layer-extension",
-  "version": "0.0.0",
+// `init` scaffolds a MONOREPO you own and grow — a pnpm workspace whose members are
+// individual extensions (`extensions/*`), seeded with one buildable hello-world
+// extension that extends `Query`. The build/validate/push flow itself lives in this
+// published CLI plugin, not in the scaffold, so an extension package stays tiny (just
+// `src/extension.ts` + a thin package.json/tsconfig). Everything is vendored inline —
+// no network fetch — and kept dependency-light so the extension commands work on it
+// out of the box. The `basic` template is the only one today.
+/** Derive a valid npm package name from the scaffold directory (fallback: a generic one). */
+function projectNameFor(dir) {
+    const sanitized = basename(resolve(dir))
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized || "integration-layer-extensions";
+}
+/** The monorepo file set, parameterized by the root package name. */
+function templateFiles(projectName) {
+    return {
+        "package.json": `{
+  "name": ${JSON.stringify(projectName)},
   "private": true,
   "type": "module",
+  "packageManager": "pnpm@11.17.0",
+  "engines": {
+    "node": "22.x || 24.x"
+  },
   "scripts": {
-    "build": "commercetools integration-layer extension build",
-    "serve": "commercetools integration-layer extension serve",
-    "push": "commercetools integration-layer extension push"
+    "build": "commercetools integration-layer extension build --all",
+    "typecheck": "pnpm -r typecheck",
+    "lint": "eslint .",
+    "dev": "commercetools integration-layer extension serve --all",
+    "validate": "commercetools integration-layer extension validate --all",
+    "push": "commercetools integration-layer extension push --all"
   },
   "devDependencies": {
-    "@commercetools/platform-sdk": "8.25.0",
-    "graphql": "^16.9.0",
-    "typescript": "^5.7.2"
+    "eslint": "^10.8.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.65.0"
   }
 }
 `,
-    "tsconfig.json": `{
+        "pnpm-workspace.yaml": `packages:
+  # Each extension is a workspace member (edit its src/extension.ts). A project deploys
+  # ONE bundle, so the root \`pnpm build\` / \`validate\` / \`push\` scripts MERGE every
+  # extension here into that single combined bundle — never one per package.
+  - 'extensions/*'
+
+# Refuse dependency versions published less than 24h ago. Minutes; 1440 = 24h.
+minimumReleaseAge: 1440
+`,
+        "tsconfig.base.json": `{
   "compilerOptions": {
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "strict": true,
+    "esModuleInterop": true,
     "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["src/**/*"]
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  }
 }
 `,
-    ".env.example": `# The authenticated commands (validate/push/status/delete, schema, config) reuse the
-# token from \`commercetools auth login\` (as a manage_project client) — no credentials
-# go here. Optionally override the integration-layer edge URL. Copy to .env.
-INTEGRATION_LAYER_URL=
+        "eslint.config.js": `import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['**/dist/**', '**/node_modules/**'] },
+  ...tseslint.configs.recommended,
+  {
+    // Allow \`_\`-prefixed unused args (resolver signatures often ignore arguments).
+    files: ['**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+    },
+  },
+);
 `,
-    ".gitignore": `node_modules/
+        ".gitignore": `node_modules/
 dist/
 .env
 `,
-    "README.md": `# integration-layer extension
+        ".env.example": `# The authenticated commands (validate/push/status/delete, schema, config) reuse the
+# token from \`commercetools auth login\` (as a manage_project client) — no credentials
+# go here. Optionally override the integration-layer edge URL. Copy to .env.
+INTEGRATION_LAYER_URL=
+`,
+        "README.md": `# ${projectName}
+
+A monorepo of commercetools integration-layer extensions, scaffolded by
+\`commercetools integration-layer init\`. Each extension is a workspace member under
+\`extensions/\`; the starter one (\`extensions/hello-world\`) adds a \`hello\` field to
+\`Query\`.
+
+A project deploys a **single bundle** — one federation subgraph the router composes
+with the integration layer. So this repo's extensions are **merged into that one
+bundle**: the root \`build\` / \`validate\` / \`push\` scripts combine everything under
+\`extensions/\` and push it as one artifact (not one per package), and \`dev\` serves that
+same merged subgraph locally. Split your code into as many \`extensions/*\` packages as
+makes sense to author — they always ship as one.
+
+## Set up the CLI (once)
+
+The \`build\`/\`serve\`/\`validate\`/\`push\` scripts run through the **commercetools CLI**'s
+\`integration-layer\` topic, added by the published
+\`@commercetools/cli-topic-integration-layer\` plugin. Install the CLI globally with
+pnpm, add the plugin, then log in:
+
+\`\`\`sh
+# Install the commercetools CLI globally with pnpm, then add the integration-layer
+# topic. The plugin is on the public npm registry, so no auth or scope mapping is
+# needed. (Install from @dev for now — the \`plugins\` command is only in the CLI's dev
+# prerelease; drop @dev once it ships to @latest.)
+pnpm add -g @commercetools/cli@dev
+commercetools plugins install @commercetools/cli-topic-integration-layer
+
+# Log in once — mints the manage_project token the authenticated commands reuse
+# (validate/push/status/delete, schema, config) and sets your target project.
+commercetools auth login --project-key <your-project-key>
+\`\`\`
+
+## Getting started
 
-Scaffolded by \`commercetools integration-layer init\`.
+Everything runs through pnpm — the scripts below wrap the \`commercetools
+integration-layer extension …\` commands.
 
-- \`commercetools integration-layer extension build\` — bundle \`src/extension.ts\`
-- \`commercetools integration-layer extension serve\` — local dev server
-- \`commercetools integration-layer extension push\` — validate + upload
+\`\`\`sh
+pnpm install
 
-Run \`commercetools auth login\` first — the authenticated commands (push/validate/
-status/delete, schema, config) reuse that token. Optionally copy \`.env.example\` to
-\`.env\` to override the integration-layer edge URL.
+# From the repo root — these operate on the ONE combined bundle:
+pnpm dev        # merge every extension into one subgraph and serve it behind a local
+                # federated gateway (+ the integration layer) at
+                # http://localhost:4000/graphql — the production topology in miniature.
+                # Needs \`commercetools auth login\` (composes against your live schema).
+pnpm validate   # compose the combined bundle against the live schema (no upload)
+pnpm push       # validate + upload the combined bundle (replaces the project's one)
+
+# …or focus on a single extension in isolation (standalone subgraph, no login needed):
+pnpm --filter @extensions/hello-world dev
+\`\`\`
+
+With \`pnpm dev\` running, open http://localhost:4000/graphql for a GraphiQL over the
+merged schema; the raw combined extensions subgraph is at \`/_extension\`, and the
+browsable merged (extensions + integration layer) schema at \`/composed\`.
+
+Optionally copy \`.env.example\` to \`.env\` to override the integration-layer edge URL.
+
+## Adding another extension
+
+Copy \`extensions/hello-world\` to \`extensions/<your-extension>\`, rename it in its
+\`package.json\`, and edit its \`src/extension.ts\`. The root scripts discover every folder
+under \`extensions/\` automatically and merge it into the single bundle — so \`pnpm dev\`,
+\`validate\`, and \`push\` all just pick it up, with no port wrangling. (Two extensions
+can each add fields to \`Query\`; they only clash if they declare the *same* field.)
 `,
+        "extensions/hello-world/package.json": `{
+  "name": "@extensions/hello-world",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "commercetools integration-layer extension build",
+    "dev": "commercetools integration-layer extension serve",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "~6.0.3"
+  }
+}
+`,
+        "extensions/hello-world/tsconfig.json": `{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+`,
+        "extensions/hello-world/src/extension.ts": `/**
+ * A hello-world integration-layer extension — the PURELY ADDITIVE pattern: it adds a
+ * brand-new root field (\`Query.hello\`) and shares nothing with the integration layer,
+ * so the two \`Query\` types merge with no change to it and composition is trivial.
+ *
+ * An extension exports \`typeDefs\` (a federation-v2 SDL string) + \`resolvers\` and runs
+ * in a restricted runtime. Edit this file, then from the repo ROOT run \`pnpm validate\` /
+ * \`pnpm push\` — every extension is merged into the one bundle the project deploys (the
+ * target project comes from your \`commercetools auth login\`). Iterate on just this one
+ * with \`pnpm --filter @extensions/hello-world dev\`.
+ */
+
+export const typeDefs = \`
+  extend schema @link(url: "https://specs.apollo.dev/federation/v2.3")
+
+  type Query {
+    "A friendly greeting contributed by this extension."
+    hello(name: String): String!
+  }
+\`;
+
+/**
+ * The per-call capability context the restricted runtime hands each resolver.
+ * \`now()\` is the current epoch millis (a convenience — \`Date.now()\` works too);
+ * \`config\` is this extension's merchant-supplied \`{ key: value }\` map, with secret
+ * values decrypted host-side (e.g. \`ctx.config.API_KEY\`). Set values with
+ * \`commercetools integration-layer config set <KEY> <VALUE>\`.
+ */
+interface ExtensionContext {
+  now(): number;
+  config: Readonly<Record<string, string>>;
+}
+
+export const resolvers = {
+  Query: {
+    // A resolver receives (parent, args, context): \`_parent\` is the object the field
+    // hangs off (nothing here — this is a root field), \`args\` are the field arguments
+    // from the query, and \`ctx\` exposes the restricted runtime's host capabilities.
+    hello: (_parent: unknown, { name }: { name?: string }, ctx: ExtensionContext) => {
+      const greeting = ctx.config.GREETING ?? "Hello";
+      return \`\${greeting}, \${name ?? "world"}, from your integration-layer extension!\`;
+    },
+  },
 };
+`,
+    };
+}
 export default class Init extends Command {
-    static description = "Scaffold an integration-layer extension project from a template";
+    static description = "Scaffold an integration-layer extensions monorepo (a pnpm workspace with one hello-world extension)";
     static examples = [
-        "<%= config.bin %> integration-layer init my-extension",
-        "<%= config.bin %> integration-layer init my-extension --template basic",
+        "<%= config.bin %> integration-layer init",
+        "<%= config.bin %> integration-layer init my-extensions",
+        "<%= config.bin %> integration-layer init my-extensions --template basic",
     ];
     static args = {
-        directory: Args.string({ description: "directory to scaffold into", required: true }),
+        directory: Args.string({
+            description: "directory to scaffold the monorepo into (defaults to the current directory)",
+            default: ".",
+        }),
     };
     static flags = {
         template: Flags.string({
@@ -118,18 +265,22 @@ export default class Init extends Command {
         const dir = args.directory;
         const existing = await readdir(dir).catch(() => []);
         if (existing.length > 0 && !flags.force) {
-            this.error(`Directory '${dir}' is not empty. Pass --force to scaffold into it anyway.`);
+            const what = dir === "." ? "The current directory" : `Directory '${dir}'`;
+            this.error(`${what} is not empty. Pass --force to scaffold into it anyway.`);
         }
-        for (const [relPath, contents] of Object.entries(TEMPLATE_FILES)) {
+        const files = templateFiles(projectNameFor(dir));
+        for (const [relPath, contents] of Object.entries(files)) {
             const target = join(dir, relPath);
             await mkdir(join(target, ".."), { recursive: true });
             await writeFile(target, contents, "utf8");
         }
-        this.log(`✓ scaffolded a '${flags.template}' extension in ${dir}`);
+        const location = dir === "." ? "the current directory" : dir;
+        this.log(`✓ scaffolded a '${flags.template}' extensions monorepo in ${location}`);
         this.log("Next steps:");
-        this.log(`  cd ${dir}`);
-        this.log("  npm install");
-        this.log("  commercetools integration-layer extension serve");
+        if (dir !== ".")
+            this.log(`  cd ${dir}`);
+        this.log("  pnpm install");
+        this.log("  pnpm dev   # run the hello-world extension locally");
     }
 }
 //# sourceMappingURL=init.js.map

package/dist/commands/integration-layer/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/integration-layer/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEnD,oFAAoF;AACpF,sFAAsF;AACtF,8EAA8E;AAC9E,MAAM,cAAc,GAA2B;IAC7C,kBAAkB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCrB;IACC,cAAc,EAAE;;;;;;;;;;;;;;;;CAgBjB;IACC,eAAe,EAAE;;;;;;;;;;;CAWlB;IACC,cAAc,EAAE;;;;CAIjB;IACC,YAAY,EAAE;;;CAGf;IACC,WAAW,EAAE;;;;;;;;;;;CAWd;CACA,CAAC;AAEF,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,OAAO;IACvC,MAAM,CAAU,WAAW,GAAG,iEAAiE,CAAC;IAEhG,MAAM,CAAU,QAAQ,GAAG;QACzB,uDAAuD;QACvD,wEAAwE;KACzE,CAAC;IAEF,MAAM,CAAU,IAAI,GAAG;QACrB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,4BAA4B,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KACtF,CAAC;IAEF,MAAM,CAAU,KAAK,GAAG;QACtB,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC;YACrB,WAAW,EAAE,qBAAqB;YAClC,OAAO,EAAE,CAAC,OAAO,CAAC;YAClB,OAAO,EAAE,OAAO;SACjB,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YACnB,IAAI,EAAE,GAAG;YACT,WAAW,EAAE,qCAAqC;YAClD,OAAO,EAAE,KAAK;SACf,CAAC;KACH,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QAE3B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC,CAAC;QAChE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,0DAA0D,CAAC,CAAC;QAC1F,CAAC;QAED,KAAK,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;YACjE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAClC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,mBAAmB,KAAK,CAAC,QAAQ,kBAAkB,GAAG,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;IAChE,CAAC"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/integration-layer/init.ts"],"names":[],"mappings":"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"}

package/dist/lib/awaitBundleState.d.ts

@@ -0,0 +1,33 @@
+import { type ExtensionMeta } from "./ilClient.js";
+/** How the wait ended. Only `failed` means "the push produced a broken bundle". */
+export type BundleOutcome = {
+    kind: "running";
+    meta: ExtensionMeta;
+} | {
+    kind: "failed";
+    meta: ExtensionMeta;
+} | {
+    kind: "superseded";
+    meta: ExtensionMeta;
+} | {
+    kind: "unknown";
+    reason: string;
+    meta?: ExtensionMeta;
+};
+export interface AwaitOptions {
+    /** Give up after this long. */
+    timeoutMs: number;
+    /** Gap between metadata reads. */
+    intervalMs: number;
+    /** Injected so tests don't actually sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injected so tests control elapsed time. */
+    now?: () => number;
+}
+/**
+ * Poll until `version` leaves `pending`, or we run out of time.
+ *
+ * The first read happens immediately — an extension that was already mid-poll can
+ * settle the version before we ever sleep.
+ */
+export declare function awaitBundleState(baseUrl: string, projectKey: string, token: string, version: number, options: AwaitOptions): Promise<BundleOutcome>;

package/dist/lib/awaitBundleState.js

@@ -0,0 +1,77 @@
+// Wait for a just-pushed bundle version to prove itself.
+//
+// A push only STORES a bundle. The extension picks it up on its own poll, tries to
+// load it, and reports back — so the version starts `pending` and only becomes
+// `running` (it loaded and published its schema) or `failed` (it didn't, with a
+// reason) a little later. Until this, `push` reported success the moment the bytes
+// landed, which meant a bundle the sandbox refuses to run looked like a clean push.
+//
+// This polls the project's bundle metadata until the pushed version settles, and
+// hands the caller back an outcome it can turn into an exit code.
+//
+// Three things it deliberately does NOT do:
+//
+//   - It never treats "I couldn't find out" as a failure. An integration layer that
+//     predates bundle state reports no `state` at all, and a project whose extension
+//     isn't deployed yet will never move off `pending`. Both are `unknown`, not
+//     `failed` — failing a push for them would break perfectly good workflows.
+//   - It doesn't watch for the version to change under it. If someone else pushes
+//     while we wait, the newest version is no longer ours; we say so and stop rather
+//     than report on somebody else's push.
+//   - It doesn't retry transient metadata-read errors into a verdict. A read that
+//     throws ends the wait as `unknown` with the error attached.
+import { fetchExtensionMeta } from "./ilClient.js";
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll until `version` leaves `pending`, or we run out of time.
+ *
+ * The first read happens immediately — an extension that was already mid-poll can
+ * settle the version before we ever sleep.
+ */
+export async function awaitBundleState(baseUrl, projectKey, token, version, options) {
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const deadline = now() + options.timeoutMs;
+    for (;;) {
+        let meta;
+        try {
+            meta = await fetchExtensionMeta(baseUrl, projectKey, token);
+        }
+        catch (err) {
+            return {
+                kind: "unknown",
+                reason: `could not read the stored bundle's status: ${err.message}`,
+            };
+        }
+        if (meta === null) {
+            // Deleted out from under us between the push and this read.
+            return { kind: "unknown", reason: "no bundle is stored for this project any more" };
+        }
+        if (meta.state === undefined) {
+            // An integration layer that doesn't report state. Nothing to wait for.
+            return {
+                kind: "unknown",
+                reason: "this integration layer does not report bundle status",
+                meta,
+            };
+        }
+        if (meta.version !== version) {
+            // Someone else pushed while we were waiting; the newest version isn't ours.
+            return { kind: "superseded", meta };
+        }
+        if (meta.state === "running")
+            return { kind: "running", meta };
+        if (meta.state === "failed")
+            return { kind: "failed", meta };
+        // Still pending.
+        if (now() >= deadline) {
+            return {
+                kind: "unknown",
+                reason: `the extension did not report on version ${version} within ${Math.round(options.timeoutMs / 1000)}s`,
+                meta,
+            };
+        }
+        await sleep(options.intervalMs);
+    }
+}
+//# sourceMappingURL=awaitBundleState.js.map

package/dist/lib/awaitBundleState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"awaitBundleState.js","sourceRoot":"","sources":["../../src/lib/awaitBundleState.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,mFAAmF;AACnF,+EAA+E;AAC/E,gFAAgF;AAChF,mFAAmF;AACnF,oFAAoF;AACpF,EAAE;AACF,iFAAiF;AACjF,kEAAkE;AAClE,EAAE;AACF,4CAA4C;AAC5C,EAAE;AACF,oFAAoF;AACpF,qFAAqF;AACrF,gFAAgF;AAChF,+EAA+E;AAC/E,kFAAkF;AAClF,qFAAqF;AACrF,2CAA2C;AAC3C,kFAAkF;AAClF,iEAAiE;AAEjE,OAAO,EAAE,kBAAkB,EAAsB,MAAM,eAAe,CAAC;AAoBvE,MAAM,YAAY,GAAG,CAAC,EAAU,EAAiB,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAe,EACf,UAAkB,EAClB,KAAa,EACb,OAAe,EACf,OAAqB;IAErB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAE3C,SAAS,CAAC;QACR,IAAI,IAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,8CAA+C,GAAa,CAAC,OAAO,EAAE;aAC/E,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,4DAA4D;YAC5D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,+CAA+C,EAAE,CAAC;QACtF,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,uEAAuE;YACvE,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,sDAAsD;gBAC9D,IAAI;aACL,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC7B,4EAA4E;YAC5E,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACtC,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC/D,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAE7D,iBAAiB;QACjB,IAAI,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;YACtB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,2CAA2C,OAAO,WAAW,IAAI,CAAC,KAAK,CAC7E,OAAO,CAAC,SAAS,GAAG,IAAI,CACzB,GAAG;gBACJ,IAAI;aACL,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/lib/base.d.ts

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