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

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

@@ -0,0 +1,98 @@
+import { Flags } from "@oclif/core";
+import { defaultEntry, defaultOutfile } from "../../../lib/tooling/build.js";
+import { bundleForFlags } from "../../../lib/tooling/extensions.js";
+import { validateBundle, BundleValidationError } from "../../../lib/tooling/validateBundle.js";
+import { remoteValidate } from "../../../lib/ilClient.js";
+import { IntegrationLayerCommand } from "../../../lib/base.js";
+export default class ExtensionValidate extends IntegrationLayerCommand {
+    static description = "Build, run local checks, then compose against the project schema and gate breaking changes";
+    static examples = [
+        "<%= config.bin %> integration-layer extension validate",
+        "<%= config.bin %> integration-layer extension validate --skip remote",
+        "<%= config.bin %> integration-layer extension validate --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: "validate every extension under ./extensions/* merged into ONE combined bundle (the single deployed artifact)",
+            default: false,
+        }),
+        "extensions-dir": Flags.string({
+            description: "directory holding the extension packages (used with --all)",
+            default: "extensions",
+        }),
+        skip: Flags.string({
+            description: "run only one half of the gate",
+            options: ["local", "remote"],
+        }),
+    };
+    /** Print a remote validation result legibly. Returns true when it passed. */
+    reportRemote(result) {
+        if (!result.composes) {
+            this.logToStderr("✗ extension does not compose with the integration layer supergraph:");
+            for (const err of result.compositionErrors)
+                this.logToStderr(`  - ${err}`);
+            return false;
+        }
+        if (result.breakingChanges.length > 0) {
+            this.logToStderr("✗ extension introduces breaking changes to the published supergraph:");
+            for (const change of result.breakingChanges) {
+                this.logToStderr(`  - [${change.type}] ${change.description}`);
+            }
+            return false;
+        }
+        if (!result.comparedToPublished) {
+            this.log("✓ composes with the integration layer supergraph (breaking-change check skipped: no published baseline)");
+            return true;
+        }
+        this.log("✓ composes with the integration layer supergraph and introduces no breaking changes");
+        return true;
+    }
+    async run() {
+        const { flags } = await this.parse(ExtensionValidate);
+        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 = null;
+        if (flags.skip !== "local") {
+            try {
+                const local = await validateBundle(outfile, sourceFiles);
+                typeDefs = local.typeDefs;
+                this.log(`✓ local checks passed (resolver roots: ${local.resolverTypes.join(", ") || "none"}; ` +
+                    `API extensions: ${local.apiExtensionKeys.join(", ") || "none"})`);
+            }
+            catch (err) {
+                if (err instanceof BundleValidationError)
+                    this.error(err.message);
+                throw err;
+            }
+        }
+        else {
+            // Skipping local: still need the SDL for the remote check — load it cheaply.
+            const local = await validateBundle(outfile, sourceFiles).catch(() => null);
+            typeDefs = local?.typeDefs ?? null;
+        }
+        if (flags.skip === "remote")
+            return;
+        if (typeDefs === null) {
+            this.log("· no GraphQL subgraph in this bundle — nothing to compose remotely.");
+            return;
+        }
+        const { baseUrl, projectKey, token } = await this.resolveIlContext(flags);
+        const result = await remoteValidate(baseUrl, projectKey, token, typeDefs);
+        if (!this.reportRemote(result))
+            this.error("remote validation failed.");
+    }
+}
+//# sourceMappingURL=validate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../../src/commands/integration-layer/extension/validate.ts"],"names":[],"mappings":"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"}

package/dist/commands/integration-layer/hello.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class IntegrationLayerHelloCommand extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

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

@@ -0,0 +1,10 @@
+import { Command } from "@oclif/core";
+export default class IntegrationLayerHelloCommand extends Command {
+    static description = "Print a hello world message from the integration-layer topic";
+    static examples = ["<%= config.bin %> integration-layer hello"];
+    async run() {
+        await this.parse(IntegrationLayerHelloCommand);
+        this.log("Hello, world!");
+    }
+}
+//# sourceMappingURL=hello.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hello.js","sourceRoot":"","sources":["../../../src/commands/integration-layer/hello.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,MAAM,CAAC,OAAO,OAAO,4BAA6B,SAAQ,OAAO;IAC/D,MAAM,CAAU,WAAW,GAAG,8DAA8D,CAAC;IAE7F,MAAM,CAAU,QAAQ,GAAG,CAAC,2CAA2C,CAAC,CAAC;IAEzE,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC5B,CAAC"}

package/dist/commands/integration-layer/init.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "@oclif/core";
+export default class Init extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        directory: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        template: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

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

@@ -0,0 +1,279 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { Args, Command, Flags } from "@oclif/core";
+// `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 --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": {
+    "eslint": "^10.8.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.65.0"
+  }
+}
+`,
+        "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,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  }
+}
+`,
+        "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/
+dist/
+.env
+`,
+        ".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
+
+Everything runs through pnpm — the scripts below wrap the \`commercetools
+integration-layer extension …\` commands.
+
+\`\`\`sh
+pnpm install
+
+# 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 extensions monorepo (a pnpm workspace with one hello-world extension)";
+    static examples = [
+        "<%= 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 the monorepo into", required: true }),
+    };
+    static flags = {
+        template: Flags.string({
+            description: "the template to use",
+            options: ["basic"],
+            default: "basic",
+        }),
+        force: Flags.boolean({
+            char: "f",
+            description: "scaffold into a non-empty directory",
+            default: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Init);
+        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 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}' extensions monorepo in ${dir}`);
+        this.log("Next steps:");
+        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

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/integration-layer/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/integration-layer/schema/fetch.d.ts

@@ -0,0 +1,9 @@
+import { IntegrationLayerCommand } from "../../../lib/base.js";
+export default class SchemaFetch extends IntegrationLayerCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        out: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/integration-layer/schema/fetch.js

@@ -0,0 +1,27 @@
+import { writeFile } from "node:fs/promises";
+import { Flags } from "@oclif/core";
+import { fetchSubgraphSdl } from "../../../lib/ilClient.js";
+import { IntegrationLayerCommand } from "../../../lib/base.js";
+export default class SchemaFetch extends IntegrationLayerCommand {
+    static description = "Print (or write) the project's core-subgraph SDL — the input extensions compose against";
+    static examples = [
+        "<%= config.bin %> integration-layer schema fetch",
+        "<%= config.bin %> integration-layer schema fetch --out subgraph.graphql",
+    ];
+    static flags = {
+        out: Flags.string({ description: "write the SDL to this file instead of stdout" }),
+    };
+    async run() {
+        const { flags } = await this.parse(SchemaFetch);
+        const { baseUrl, projectKey, token } = await this.resolveIlContext(flags);
+        const sdl = await fetchSubgraphSdl(baseUrl, projectKey, token);
+        if (flags.out) {
+            await writeFile(flags.out, sdl, "utf8");
+            this.log(`✓ wrote ${projectKey} core-subgraph SDL → ${flags.out}`);
+        }
+        else {
+            this.log(sdl);
+        }
+    }
+}
+//# sourceMappingURL=fetch.js.map

package/dist/commands/integration-layer/schema/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../../../src/commands/integration-layer/schema/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,uBAAuB;IAC9D,MAAM,CAAU,WAAW,GACzB,yFAAyF,CAAC;IAE5F,MAAM,CAAU,QAAQ,GAAG;QACzB,kDAAkD;QAClD,yEAAyE;KAC1E,CAAC;IAEF,MAAM,CAAU,KAAK,GAAG;QACtB,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,8CAA8C,EAAE,CAAC;KACnF,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAChD,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC1E,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;QAC/D,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;YACd,MAAM,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,WAAW,UAAU,wBAAwB,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QACrE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { defineApiExtension, approve, block, update, type ApiExtensionAction, type ApiExtensionDefinition, type ApiExtensionError, type ApiExtensionInput, type ApiExtensionResult, type ExtensionContext, type ExtensionInput, } from "./lib/tooling/apiExtension.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// oclif discovers commands from the `oclif.commands` directory (see package.json).
+// The package `main` re-exports the extension authoring API so an author can import
+// the helpers/types when writing `src/extension.ts`.
+export { defineApiExtension, approve, block, update, } from "./lib/tooling/apiExtension.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,oFAAoF;AACpF,qDAAqD;AACrD,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,KAAK,EACL,MAAM,GAQP,MAAM,+BAA+B,CAAC"}

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