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

package/dist/lib/tooling/staticAnalysis.js

@@ -0,0 +1,167 @@
+// Best-effort static analysis of an extension's source, run by `validate`/`push`.
+//
+// Kept in sync with commercetools/integration-layer-extension-examples
+// (packages/tooling/src/staticAnalysis.ts) — that repo is the canonical copy, and it
+// in turn mirrors the connector's `webPlatformEndowments` (octolog-extensions-sandbox
+// service/src/bundle/sandbox/compartment.ts), the real source of truth for what the
+// sandbox endows. When the connector's endowment list changes, update ILEE first,
+// then port the change here. The resolver environment provides a restricted set of
+// capabilities, not a full Node runtime, so this flags patterns that won't work there
+// before the bundle is uploaded. It parses the author's own source files to a
+// TypeScript AST (so a mention in a comment or string is never a false positive) and
+// is a lint, not an enforcement boundary — it catches honest mistakes, not deliberate
+// obfuscation. It rejects:
+//   - a well-known global the sandbox does NOT endow (`process`, `Buffer`,
+//     `setInterval`, `SharedArrayBuffer`, `WebAssembly`, DOM globals, …) — so an
+//     author who reaches for one is warned here instead of crashing at runtime;
+//   - importing a Node built-in (`fs`, `crypto`, `node:*`, …) — use `fetch` or an npm package;
+//   - `eval` / `new Function`.
+import { readFile } from "node:fs/promises";
+import ts from "typescript";
+/** Node core modules an extension may not import; `node:`-prefixed ids are also rejected. */
+const NODE_BUILTINS = new Set([
+    "assert", "async_hooks", "buffer", "child_process", "cluster", "console",
+    "constants", "crypto", "dgram", "dns", "domain", "events", "fs", "http",
+    "http2", "https", "inspector", "module", "net", "os", "path", "perf_hooks",
+    "process", "punycode", "querystring", "readline", "repl", "stream",
+    "string_decoder", "sys", "timers", "tls", "trace_events", "tty", "url",
+    "util", "v8", "vm", "worker_threads", "zlib",
+]);
+// The web-platform globals the sandbox endows (its "Tier-1 data surface"), on top
+// of the ECMAScript intrinsics SES lockdown leaves in place (JSON, Object, Array,
+// Map, Set, Promise, RegExp, typed arrays, …, always available). This mirrors the
+// connector's `webPlatformEndowments` (bundle/sandbox/compartment.ts) and is the
+// SOURCE OF TRUTH `UNAVAILABLE_GLOBALS` is the curated complement of — keep the two
+// in sync when the connector's endowment list changes. Referenced by the check so
+// a global that is BOTH endowed and (mistakenly) listed as unavailable never fires.
+const ENDOWED_GLOBALS = new Set([
+    "fetch",
+    "setTimeout", "clearTimeout",
+    "Date", "Math",
+    "URL", "URLSearchParams",
+    "TextEncoder", "TextDecoder", "btoa", "atob",
+    "Headers", "Request", "Response", "FormData",
+    "structuredClone", "Intl",
+    "AbortController", "AbortSignal",
+    "console", // tamed, forwarded to the host logger
+]);
+// Well-known globals the sandbox deliberately does NOT provide, each with a hint at
+// the endowed alternative. Using one throws at runtime, so flag it at validate time.
+// NOT exhaustive (it can't enumerate every absent name) and NOT a security boundary
+// — a curated, high-signal set: Node-only globals, and the capability / DoS /
+// side-channel globals the compartment withholds on purpose (see compartment.ts).
+const UNAVAILABLE_GLOBALS = new Map([
+    // Node-only — read config from `ctx.config`, or use the web-standard equivalent.
+    ["process", "read configuration from `ctx.config` instead"],
+    ["Buffer", "use `TextEncoder`/`Uint8Array`, or `btoa`/`atob` for base64"],
+    ["global", "use `globalThis`"],
+    ["setInterval", "the sandbox endows `setTimeout`/`clearTimeout` only — loop with `setTimeout`"],
+    ["clearInterval", "the sandbox endows `setTimeout`/`clearTimeout` only"],
+    ["setImmediate", "use `setTimeout(fn, 0)`"],
+    // Deliberately withheld (capability / DoS / side-channel) — see compartment.ts.
+    ["SharedArrayBuffer", "withheld — shared memory is a cross-sandbox channel"],
+    ["Atomics", "withheld — pairs with SharedArrayBuffer (channel + synchronous blocking)"],
+    ["WebAssembly", "withheld — a second execution engine is not exposed to extensions"],
+    ["MessageChannel", "withheld — communication primitive"],
+    ["MessagePort", "withheld — communication primitive"],
+    ["BroadcastChannel", "withheld — communication primitive"],
+    ["WeakRef", "withheld — GC observability is a side channel"],
+    ["FinalizationRegistry", "withheld — GC observability is a side channel"],
+    ["performance", "withheld — high-resolution timing is a side channel; use `Date.now()`"],
+    ["CompressionStream", "withheld — decompression is an unbounded DoS vector"],
+    ["DecompressionStream", "withheld — decompression is an unbounded DoS vector"],
+    // Browser/DOM globals that simply do not exist server-side.
+    ["window", "not available (no DOM); use `globalThis`"],
+    ["document", "not available (no DOM)"],
+    ["localStorage", "not available; use `ctx.config` for configuration"],
+    ["sessionStorage", "not available; use `ctx.config` for configuration"],
+    ["XMLHttpRequest", "not available; use the global `fetch`"],
+    ["WebSocket", "not available; only outbound `fetch` egress is provided"],
+]);
+/** Is `spec` a Node built-in module (or a `node:`-prefixed import)? */
+function isBuiltinSpecifier(spec) {
+    if (spec.startsWith("node:"))
+        return true;
+    return NODE_BUILTINS.has(spec);
+}
+/** Analyse one already-parsed source file, appending any issues found. */
+function analyzeSourceFile(sf, issues) {
+    const report = (node, message) => {
+        const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+        issues.push({ file: sf.fileName, line: line + 1, message });
+    };
+    const checkSpecifier = (spec, node) => {
+        if (isBuiltinSpecifier(spec)) {
+            report(node, `imports the Node built-in "${spec}", which the runtime does not provide — ` +
+                "use the global `fetch` for HTTP, or bundle an npm package");
+        }
+    };
+    const visit = (node) => {
+        // import ... from "x" / export ... from "x"
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+            node.moduleSpecifier &&
+            ts.isStringLiteral(node.moduleSpecifier)) {
+            checkSpecifier(node.moduleSpecifier.text, node.moduleSpecifier);
+        }
+        if (ts.isCallExpression(node)) {
+            const callee = node.expression;
+            const firstArg = node.arguments[0];
+            // require("x") / import("x")
+            if ((callee.kind === ts.SyntaxKind.ImportKeyword ||
+                (ts.isIdentifier(callee) && callee.text === "require")) &&
+                firstArg &&
+                ts.isStringLiteral(firstArg)) {
+                checkSpecifier(firstArg.text, firstArg);
+            }
+            // eval(...)
+            if (ts.isIdentifier(callee) && callee.text === "eval") {
+                report(node, "uses `eval`, which the runtime does not allow");
+            }
+        }
+        // new Function(...)
+        if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "Function") {
+            report(node, "uses `new Function`, which the runtime does not allow");
+        }
+        // Reference to a global the sandbox does not endow (e.g. `process.env`,
+        // `new SharedArrayBuffer(…)`). Skip when the identifier is the property side of
+        // an access (`foo.process`), a declaration name, or otherwise not a value read —
+        // this is a syntactic lint, so keep it to high-signal free-identifier reads.
+        if (ts.isIdentifier(node) && UNAVAILABLE_GLOBALS.has(node.text) && !ENDOWED_GLOBALS.has(node.text)) {
+            const parent = node.parent;
+            const isPropertyName = (ts.isPropertyAccessExpression(parent) && parent.name === node) ||
+                (ts.isQualifiedName(parent) && parent.right === node);
+            // A local binding of the same name (import/param/var/function/property) is the
+            // author's own — not the ambient global — so don't flag it.
+            const isLocalBinding = (ts.isParameter(parent) ||
+                ts.isVariableDeclaration(parent) ||
+                ts.isFunctionDeclaration(parent) ||
+                ts.isBindingElement(parent) ||
+                ts.isPropertyAssignment(parent) ||
+                ts.isImportSpecifier(parent) ||
+                ts.isImportClause(parent)) &&
+                parent.name === node;
+            if (!isPropertyName && !isLocalBinding) {
+                const hint = UNAVAILABLE_GLOBALS.get(node.text) ?? "";
+                report(node, `uses the global \`${node.text}\`, which the sandbox does not provide` +
+                    (hint ? ` — ${hint}` : ""));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+}
+/**
+ * Analyse the given source files (the author's entry + its local imports) and
+ * return every runtime-incompatibility issue found. An empty array means the source
+ * is clean of the patterns this checks.
+ */
+export async function analyzeSources(files) {
+    const issues = [];
+    for (const file of files) {
+        const text = await readFile(file, "utf8");
+        const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+        analyzeSourceFile(sf, issues);
+    }
+    return issues;
+}
+//# sourceMappingURL=staticAnalysis.js.map

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

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

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

@@ -0,0 +1,19 @@
+/** Thrown when a bundle fails validation; `message` is safe to surface to the author. */
+export declare class BundleValidationError extends Error {
+    constructor(message: string);
+}
+export type ValidationResult = {
+    /** The bundle's exported SDL, or null for an API-extensions-only bundle. */
+    typeDefs: string | null;
+    /** The resolver root keys that matched a type in the schema (e.g. `Query`). */
+    resolverTypes: string[];
+    /** The keys of the bundle's commercetools API Extensions (empty if none). */
+    apiExtensionKeys: string[];
+};
+/**
+ * Validate the bundle at `bundlePath`, having analysed the author's `sourceFiles`
+ * (the entry + its local imports, as reported by {@link buildBundle}). Resolves with
+ * the parsed metadata, or rejects with a {@link BundleValidationError} carrying a
+ * precise reason. Composition is the remote check's job (see the file header).
+ */
+export declare function validateBundle(bundlePath: string, sourceFiles: string[]): Promise<ValidationResult>;

package/dist/lib/tooling/validateBundle.js

@@ -0,0 +1,144 @@
+// Validate a built bundle before it is pushed, so a broken one fails on the author's
+// machine rather than when it is loaded live.
+//
+// Copied verbatim from commercetools/integration-layer-extension-examples
+// (packages/tooling/src/validateBundle.ts). Two local checks (the push sends the SDL
+// only, so these have no remote equivalent; composition is the remote check):
+//   1. STATIC ANALYSIS of the source (staticAnalysis.ts) — run first, rejects the
+//      patterns that won't work at runtime.
+//   2. SHAPE + COHERENCE — load the bundle and confirm it exports a non-empty
+//      `typeDefs` string and a `resolvers` object whose types/fields the SDL declares
+//      (a resolver naming an undeclared field is a silent runtime no-op).
+import { readFile } from "node:fs/promises";
+import { GraphQLInterfaceType, GraphQLObjectType, buildASTSchema, parse, } from "graphql";
+import { loadBundleSource } from "./loadBundle.js";
+import { analyzeSources } from "./staticAnalysis.js";
+/** Thrown when a bundle fails validation; `message` is safe to surface to the author. */
+export class BundleValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BundleValidationError";
+    }
+}
+const API_EXTENSION_ACTIONS = new Set(['Create', 'Update']);
+/**
+ * Validate the bundle's optional `apiExtensions` export (shape only — a handler's
+ * behaviour is the author's to test). Returns the declared keys.
+ */
+function validateApiExtensions(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new BundleValidationError('`apiExtensions` must be an array');
+    }
+    const keys = new Set();
+    raw.forEach((entry, i) => {
+        if (entry === null || typeof entry !== 'object') {
+            throw new BundleValidationError(`apiExtensions[${i}] must be an object`);
+        }
+        const e = entry;
+        const key = typeof e.key === 'string' ? e.key.trim() : '';
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(key)) {
+            throw new BundleValidationError(`apiExtensions[${i}].key must be kebab-case (got '${String(e.key)}')`);
+        }
+        if (keys.has(key))
+            throw new BundleValidationError(`apiExtensions has a duplicate key '${key}'`);
+        keys.add(key);
+        if (typeof e.resourceTypeId !== 'string' || e.resourceTypeId.trim() === '') {
+            throw new BundleValidationError(`apiExtensions['${key}'].resourceTypeId must be a non-empty string`);
+        }
+        const actions = Array.isArray(e.actions) ? e.actions : [];
+        if (actions.length === 0 ||
+            !actions.every((a) => typeof a === 'string' && API_EXTENSION_ACTIONS.has(a))) {
+            throw new BundleValidationError(`apiExtensions['${key}'].actions must be a non-empty subset of ["Create","Update"]`);
+        }
+        if (typeof e.handler !== 'function') {
+            throw new BundleValidationError(`apiExtensions['${key}'].handler must be a function`);
+        }
+        if (e.condition !== undefined && typeof e.condition !== 'string') {
+            throw new BundleValidationError(`apiExtensions['${key}'].condition must be a string`);
+        }
+    });
+    return [...keys];
+}
+/**
+ * Validate the bundle at `bundlePath`, having analysed the author's `sourceFiles`
+ * (the entry + its local imports, as reported by {@link buildBundle}). Resolves with
+ * the parsed metadata, or rejects with a {@link BundleValidationError} carrying a
+ * precise reason. Composition is the remote check's job (see the file header).
+ */
+export async function validateBundle(bundlePath, sourceFiles) {
+    // 1. Static analysis of the author's source — runtime-incompatible patterns.
+    const issues = await analyzeSources(sourceFiles);
+    if (issues.length > 0) {
+        const lines = issues.map((i) => `  - ${i.file}:${i.line} — ${i.message}`).join("\n");
+        throw new BundleValidationError(`extension source uses features the runtime does not support:\n${lines}`);
+    }
+    // 2. Load the built bundle and check its shape + resolver/SDL coherence.
+    let mod;
+    try {
+        mod = loadBundleSource(await readFile(bundlePath, "utf8"));
+    }
+    catch (err) {
+        throw new BundleValidationError(`bundle is not a loadable module: ${err.message}`);
+    }
+    const { typeDefs, resolvers } = mod;
+    const apiExtensionKeys = validateApiExtensions(mod.apiExtensions);
+    // A bundle must contribute at least one of a GraphQL subgraph or API Extensions.
+    const hasTypeDefs = typeof typeDefs === "string" && typeDefs.trim() !== "";
+    if (!hasTypeDefs) {
+        if (apiExtensionKeys.length === 0) {
+            throw new BundleValidationError("bundle must export a non-empty `typeDefs` string and/or an `apiExtensions` array");
+        }
+        // API-extensions-only bundle: no SDL to check, no remote composition.
+        return { typeDefs: null, resolverTypes: [], apiExtensionKeys };
+    }
+    if (resolvers === null || typeof resolvers !== "object") {
+        throw new BundleValidationError("bundle with `typeDefs` must also export a `resolvers` object");
+    }
+    let doc;
+    try {
+        doc = parse(typeDefs);
+    }
+    catch (err) {
+        throw new BundleValidationError(`\`typeDefs\` is not valid GraphQL SDL: ${err.message}`);
+    }
+    // `assumeValidSDL` skips full re-validation (federation directives aren't defined
+    // here; the remote compose proves the SDL sound) but still rejects an SDL that
+    // references a type it never declares.
+    let schema;
+    try {
+        schema = buildASTSchema(doc, { assumeValidSDL: true });
+    }
+    catch (err) {
+        throw new BundleValidationError(`\`typeDefs\` does not build into a valid schema: ${err.message}`);
+    }
+    // Coherence: every resolver type/field must exist in the schema. A typo here
+    // would otherwise be a silent no-op the runtime serves without complaint.
+    const resolverMap = resolvers;
+    const resolverTypes = [];
+    for (const typeName of Object.keys(resolverMap)) {
+        if (typeName.startsWith("__"))
+            continue; // e.g. __resolveType — not a schema type
+        const type = schema.getType(typeName);
+        if (!type) {
+            throw new BundleValidationError(`\`resolvers\` references type \`${typeName}\`, which \`typeDefs\` does not define`);
+        }
+        resolverTypes.push(typeName);
+        const fieldResolvers = resolverMap[typeName];
+        if (fieldResolvers &&
+            typeof fieldResolvers === "object" &&
+            (type instanceof GraphQLObjectType || type instanceof GraphQLInterfaceType)) {
+            const schemaFields = type.getFields();
+            for (const fieldName of Object.keys(fieldResolvers)) {
+                if (fieldName.startsWith("__"))
+                    continue; // e.g. __resolveReference
+                if (!(fieldName in schemaFields)) {
+                    throw new BundleValidationError(`resolver \`${typeName}.${fieldName}\` has no matching field in \`typeDefs\``);
+                }
+            }
+        }
+    }
+    return { typeDefs, resolverTypes, apiExtensionKeys };
+}
+//# sourceMappingURL=validateBundle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateBundle.js","sourceRoot":"","sources":["../../../src/lib/tooling/validateBundle.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,8CAA8C;AAC9C,EAAE;AACF,0EAA0E;AAC1E,qFAAqF;AACrF,8EAA8E;AAC9E,kFAAkF;AAClF,4CAA4C;AAC5C,8EAA8E;AAC9E,sFAAsF;AACtF,0EAA0E;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,KAAK,GAEN,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,yFAAyF;AACzF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAaD,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE5D;;;GAGG;AACH,SAAS,qBAAqB,CAAC,GAAY;IACzC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,qBAAqB,CAAC,kCAAkC,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QACvB,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,IAAI,qBAAqB,CAAC,iBAAiB,CAAC,qBAAqB,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,qBAAqB,CAC7B,iBAAiB,CAAC,kCAAkC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CACtE,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,qBAAqB,CAAC,sCAAsC,GAAG,GAAG,CAAC,CAAC;QACjG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,IAAI,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC3E,MAAM,IAAI,qBAAqB,CAAC,kBAAkB,GAAG,8CAA8C,CAAC,CAAC;QACvG,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,IACE,OAAO,CAAC,MAAM,KAAK,CAAC;YACpB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAC5E,CAAC;YACD,MAAM,IAAI,qBAAqB,CAC7B,kBAAkB,GAAG,8DAA8D,CACpF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,IAAI,qBAAqB,CAAC,kBAAkB,GAAG,+BAA+B,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YACjE,MAAM,IAAI,qBAAqB,CAAC,kBAAkB,GAAG,+BAA+B,CAAC,CAAC;QACxF,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAkB,EAClB,WAAqB;IAErB,6EAA6E;IAC7E,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrF,MAAM,IAAI,qBAAqB,CAC7B,iEAAiE,KAAK,EAAE,CACzE,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,IAAI,GAAoB,CAAC;IACzB,IAAI,CAAC;QACH,GAAG,GAAG,gBAAgB,CAAC,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAoB,CAAC;IAChF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,qBAAqB,CAAC,oCAAqC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC;IACpC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAElE,iFAAiF;IACjF,MAAM,WAAW,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3E,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,qBAAqB,CAC7B,kFAAkF,CACnF,CAAC;QACJ,CAAC;QACD,sEAAsE;QACtE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,IAAI,qBAAqB,CAAC,8DAA8D,CAAC,CAAC;IAClG,CAAC;IAED,IAAI,GAAiB,CAAC;IACtB,IAAI,CAAC;QACH,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,qBAAqB,CAC7B,0CAA2C,GAAa,CAAC,OAAO,EAAE,CACnE,CAAC;IACJ,CAAC;IAED,kFAAkF;IAClF,+EAA+E;IAC/E,uCAAuC;IACvC,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,qBAAqB,CAC7B,oDAAqD,GAAa,CAAC,OAAO,EAAE,CAC7E,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,WAAW,GAAG,SAAoC,CAAC;IACzD,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAChD,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,yCAAyC;QAClF,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,qBAAqB,CAC7B,mCAAmC,QAAQ,wCAAwC,CACpF,CAAC;QACJ,CAAC;QACD,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE7B,MAAM,cAAc,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC7C,IACE,cAAc;YACd,OAAO,cAAc,KAAK,QAAQ;YAClC,CAAC,IAAI,YAAY,iBAAiB,IAAI,IAAI,YAAY,oBAAoB,CAAC,EAC3E,CAAC;YACD,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;gBACpD,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC;oBAAE,SAAS,CAAC,0BAA0B;gBACpE,IAAI,CAAC,CAAC,SAAS,IAAI,YAAY,CAAC,EAAE,CAAC;oBACjC,MAAM,IAAI,qBAAqB,CAC7B,cAAc,QAAQ,IAAI,SAAS,0CAA0C,CAC9E,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,8 +1,50 @@
 {
   "name": "@commercetools/cli-topic-integration-layer",
-  "version": "0.0.0",
-  "description": "Placeholder reserving the name for GitHub Actions trusted publishing. Replaced by the first real release.",
-  "license": "UNLICENSED",
-  "private": false,
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+  "version": "0.2.2",
+  "description": "commercetools CLI plugin: integration-layer topic",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run --disable-console-intercept"
+  },
+  "dependencies": {
+    "@apollo/composition": "^2.14.1",
+    "@apollo/gateway": "^2.14.1",
+    "@apollo/subgraph": "^2.14.1",
+    "@envelop/apollo-federation": "^8.1.1",
+    "@graphql-tools/merge": "^9.2.2",
+    "@oclif/core": "4.2.10",
+    "esbuild": "^0.28.0",
+    "graphql": "^16.9.0",
+    "graphql-yoga": "^5.21.2",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "@commercetools/cli-plugin-auth": ">=0.0.6"
+  },
+  "devDependencies": {
+    "@commercetools/cli-plugin-auth": "0.0.6",
+    "@commercetools/platform-sdk": "8.25.0",
+    "@oclif/test": "^4.1.12",
+    "@types/node": "^22.10.2",
+    "rimraf": "^6.0.1",
+    "vitest": "^4.1.8"
+  },
+  "oclif": {
+    "topicSeparator": " ",
+    "commands": "./dist/commands"
+  }
 }