@gooddata/create-pluggable-module 11.40.0-alpha.3

package/dist/templates/module/vitest.config.ts

@@ -0,0 +1,12 @@
+// (C) 2026 GoodData Corporation
+
+import { defineConfig } from "vitest/config";
+
+// eslint-disable-next-line no-restricted-exports
+export default defineConfig({
+    test: {
+        environment: "happy-dom",
+        include: ["src/**/*.test.{ts,tsx}"],
+        globals: true,
+    },
+});

package/esm/engine/__tests__/anchors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/anchors.test.js

@@ -0,0 +1,44 @@
+// (C) 2026 GoodData Corporation
+import { describe, expect, it } from "vitest";
+import { findAnchorLineIdx, fullAnchor, insertBeforeAnchor } from "../anchors.js";
+describe("fullAnchor", () => {
+    it("returns the bare keyword when no suffix is given", () => {
+        expect(fullAnchor()).toBe("PLUGGABLE_APP_SCAFFOLD_ANCHOR");
+    });
+    it("appends the parenthesised suffix", () => {
+        expect(fullAnchor("(stages)")).toBe("PLUGGABLE_APP_SCAFFOLD_ANCHOR (stages)");
+    });
+});
+describe("findAnchorLineIdx", () => {
+    it("returns the 0-based line index of the anchor", () => {
+        const lines = ["{", "  // some comment", "  // PLUGGABLE_APP_SCAFFOLD_ANCHOR", "}"];
+        expect(findAnchorLineIdx(lines, "test.json")).toBe(2);
+    });
+    it("disambiguates by suffix when multiple anchors are present", () => {
+        const lines = [
+            "// PLUGGABLE_APP_SCAFFOLD_ANCHOR (stages)",
+            "// PLUGGABLE_APP_SCAFFOLD_ANCHOR (remotes)",
+        ];
+        expect(findAnchorLineIdx(lines, "Dockerfile", "(stages)")).toBe(0);
+        expect(findAnchorLineIdx(lines, "Dockerfile", "(remotes)")).toBe(1);
+    });
+    it("throws when the anchor is missing", () => {
+        expect(() => findAnchorLineIdx(["foo", "bar"], "test.json")).toThrow(/Could not find "PLUGGABLE_APP_SCAFFOLD_ANCHOR" in test\.json/);
+    });
+    it("throws when the same anchor appears more than once", () => {
+        const lines = ["// PLUGGABLE_APP_SCAFFOLD_ANCHOR", "// PLUGGABLE_APP_SCAFFOLD_ANCHOR"];
+        expect(() => findAnchorLineIdx(lines, "test.json")).toThrow(/Found 2 lines matching/);
+    });
+});
+describe("insertBeforeAnchor", () => {
+    it("inserts the lines immediately before the anchor line", () => {
+        const content = "line A\n// PLUGGABLE_APP_SCAFFOLD_ANCHOR\nline B";
+        const result = insertBeforeAnchor(content, "test.json", ["INSERTED 1", "INSERTED 2"]);
+        expect(result).toBe("line A\nINSERTED 1\nINSERTED 2\n// PLUGGABLE_APP_SCAFFOLD_ANCHOR\nline B");
+    });
+    it("preserves trailing newline behaviour from split/join roundtrip", () => {
+        const content = "// PLUGGABLE_APP_SCAFFOLD_ANCHOR\n";
+        const result = insertBeforeAnchor(content, "test.json", ["X"]);
+        expect(result).toBe("X\n// PLUGGABLE_APP_SCAFFOLD_ANCHOR\n");
+    });
+});

package/esm/engine/__tests__/copyTemplate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/copyTemplate.test.js

@@ -0,0 +1,59 @@
+// (C) 2026 GoodData Corporation
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { copyTemplate } from "../copyTemplate.js";
+describe("copyTemplate", () => {
+    let src;
+    let dest;
+    beforeEach(() => {
+        src = mkdtempSync(join(tmpdir(), "scaff-copy-src-"));
+        dest = mkdtempSync(join(tmpdir(), "scaff-copy-dest-"));
+    });
+    afterEach(() => {
+        rmSync(src, { recursive: true, force: true });
+        rmSync(dest, { recursive: true, force: true });
+    });
+    it("copies files + applies token substitutions in deterministic order", () => {
+        writeFileSync(join(src, "a.txt"), "name=PLACEHOLDER value=PLACEHOLDER2");
+        const { written } = copyTemplate(src, dest, [
+            ["PLACEHOLDER2", "second"],
+            ["PLACEHOLDER", "first"],
+        ]);
+        expect(written).toHaveLength(1);
+        expect(readFileSync(join(dest, "a.txt"), "utf-8")).toBe("name=first value=second");
+    });
+    it("recurses into subdirectories", () => {
+        mkdirSync(join(src, "sub"));
+        writeFileSync(join(src, "sub", "nested.txt"), "hi TOKEN");
+        copyTemplate(src, dest, [["TOKEN", "world"]]);
+        expect(readFileSync(join(dest, "sub", "nested.txt"), "utf-8")).toBe("hi world");
+    });
+    it("skips directories named in SKIP_DIRS (e.g. node_modules)", () => {
+        mkdirSync(join(src, "node_modules"));
+        writeFileSync(join(src, "node_modules", "junk.txt"), "should not be copied");
+        writeFileSync(join(src, "real.txt"), "real");
+        copyTemplate(src, dest, []);
+        // node_modules subdir should not be created in dest
+        expect(() => readFileSync(join(dest, "node_modules", "junk.txt"))).toThrow();
+        expect(readFileSync(join(dest, "real.txt"), "utf-8")).toBe("real");
+    });
+    it("substitutes only in text files — binaries copied bytewise", () => {
+        // .png is in BINARY_EXTENSIONS; the bytes shouldn't be touched even if they happen
+        // to contain a token-looking string.
+        const binaryContent = Buffer.from("PNGHEADER\x00TOKENISH\xff");
+        writeFileSync(join(src, "image.png"), binaryContent);
+        copyTemplate(src, dest, [["TOKENISH", "REPLACED"]]);
+        const copied = readFileSync(join(dest, "image.png"));
+        expect(copied.equals(binaryContent)).toBe(true);
+    });
+    it("token substitution ORDER matters — longer-first prevents partial overlap", () => {
+        writeFileSync(join(src, "a.txt"), "foo-bar foo");
+        const { written: _w } = copyTemplate(src, dest, [
+            ["foo-bar", "LONG"],
+            ["foo", "SHORT"],
+        ]);
+        expect(readFileSync(join(dest, "a.txt"), "utf-8")).toBe("LONG SHORT");
+    });
+});

package/esm/engine/__tests__/derived.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/derived.test.js

@@ -0,0 +1,30 @@
+// (C) 2026 GoodData Corporation
+import { describe, expect, it } from "vitest";
+import { computeFederationName, computeRemoteUrlEnvVar, computeRoute } from "../derived.js";
+describe("computeRoute", () => {
+    it("strips the gdc- prefix and prepends a slash", () => {
+        expect(computeRoute("gdc-foo")).toBe("/foo");
+    });
+    it("preserves internal hyphens", () => {
+        expect(computeRoute("gdc-foo-bar-baz")).toBe("/foo-bar-baz");
+    });
+    it("handles single-segment names", () => {
+        expect(computeRoute("gdc-x")).toBe("/x");
+    });
+});
+describe("computeFederationName", () => {
+    it("converts hyphens to underscores so the result is a valid JS identifier", () => {
+        expect(computeFederationName("gdc-foo-bar")).toBe("gdc_foo_bar");
+    });
+    it("preserves the gdc_ prefix (no leading-prefix stripping here)", () => {
+        expect(computeFederationName("gdc-x")).toBe("gdc_x");
+    });
+});
+describe("computeRemoteUrlEnvVar", () => {
+    it("strips gdc-, uppercases, and adds the _REMOTE_URL suffix", () => {
+        expect(computeRemoteUrlEnvVar("gdc-foo")).toBe("FOO_REMOTE_URL");
+    });
+    it("converts internal hyphens to underscores", () => {
+        expect(computeRemoteUrlEnvVar("gdc-foo-bar")).toBe("FOO_BAR_REMOTE_URL");
+    });
+});

package/esm/engine/__tests__/jsonAnchors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/jsonAnchors.test.js

@@ -0,0 +1,52 @@
+// (C) 2026 GoodData Corporation
+import { describe, expect, it } from "vitest";
+import { ensureTrailingCommaBeforeAnchor } from "../jsonAnchors.js";
+describe("ensureTrailingCommaBeforeAnchor", () => {
+    it("adds a comma to a code line that lacks one", () => {
+        const input = `[
+    { "a": 1 }
+    // PLUGGABLE_APP_SCAFFOLD_ANCHOR
+]`;
+        const output = ensureTrailingCommaBeforeAnchor(input);
+        expect(output).toContain('{ "a": 1 },');
+    });
+    it("is idempotent when the comma is already present", () => {
+        const input = `[
+    { "a": 1 },
+    // PLUGGABLE_APP_SCAFFOLD_ANCHOR
+]`;
+        expect(ensureTrailingCommaBeforeAnchor(input)).toBe(input);
+    });
+    it("inserts the comma before an inline // comment, preserving the comment position", () => {
+        const input = `[
+    { "a": 1 } // last entry
+    // PLUGGABLE_APP_SCAFFOLD_ANCHOR
+]`;
+        const output = ensureTrailingCommaBeforeAnchor(input);
+        const lines = output.split("\n");
+        expect(lines[1]).toBe('    { "a": 1 }, // last entry');
+    });
+    it("skips blank lines and pure-comment lines when looking back for the last code line", () => {
+        const input = `[
+    { "a": 1 }
+
+    // a separator comment
+    // PLUGGABLE_APP_SCAFFOLD_ANCHOR
+]`;
+        const output = ensureTrailingCommaBeforeAnchor(input);
+        expect(output).toContain('{ "a": 1 },');
+    });
+    it("honours the disambiguating suffix", () => {
+        const input = `[
+    { "a": 1 }
+    // PLUGGABLE_APP_SCAFFOLD_ANCHOR (alpha)
+    { "b": 2 }
+    // PLUGGABLE_APP_SCAFFOLD_ANCHOR (beta)
+]`;
+        const output = ensureTrailingCommaBeforeAnchor(input, "(beta)");
+        // Only the (beta) anchor's preceding line gets the comma added.
+        const lines = output.split("\n");
+        expect(lines.find((l) => l.includes('"a": 1'))).toBe('    { "a": 1 }');
+        expect(lines.find((l) => l.includes('"b": 2'))).toBe('    { "b": 2 },');
+    });
+});

package/esm/engine/__tests__/repoDetection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/repoDetection.test.js

@@ -0,0 +1,63 @@
+// (C) 2026 GoodData Corporation
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { detectRepo, findUp } from "../repoDetection.js";
+describe("findUp", () => {
+    let root;
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "scaff-findup-"));
+    });
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+    });
+    it("returns the directory containing the marker when present at cwd", () => {
+        writeFileSync(join(root, "marker.txt"), "");
+        expect(findUp(root, "marker.txt")).toBe(root);
+    });
+    it("walks upward and finds the marker in an ancestor", () => {
+        writeFileSync(join(root, "marker.txt"), "");
+        mkdirSync(join(root, "a", "b"), { recursive: true });
+        expect(findUp(join(root, "a", "b"), "marker.txt")).toBe(root);
+    });
+    it("returns undefined when no ancestor has the marker", () => {
+        // unlikely but possible: tmpdir's parents won't have our marker
+        expect(findUp(root, "definitely-not-here-marker.json")).toBeUndefined();
+    });
+});
+describe("detectRepo", () => {
+    let root;
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "scaff-detect-"));
+    });
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+    });
+    it("reports rush when rush.json is present", () => {
+        writeFileSync(join(root, "rush.json"), "{}");
+        const repo = detectRepo(root);
+        expect(repo.packageManager).toBe("rush");
+        expect(repo.repoRoot).toBe(root);
+    });
+    it("detects pnpm via pnpm-lock.yaml", () => {
+        writeFileSync(join(root, "pnpm-lock.yaml"), "");
+        const repo = detectRepo(root);
+        expect(repo.packageManager).toBe("pnpm");
+    });
+    it("detects yarn via yarn.lock", () => {
+        writeFileSync(join(root, "yarn.lock"), "");
+        const repo = detectRepo(root);
+        expect(repo.packageManager).toBe("yarn");
+    });
+    it("falls back to npm when no lockfile is present", () => {
+        const repo = detectRepo(root);
+        expect(repo.packageManager).toBe("npm");
+    });
+    it("prefers rush over other lockfiles", () => {
+        writeFileSync(join(root, "rush.json"), "{}");
+        writeFileSync(join(root, "pnpm-lock.yaml"), "");
+        const repo = detectRepo(root);
+        expect(repo.packageManager).toBe("rush");
+    });
+});

package/esm/engine/__tests__/scrubPackageJsonVersions.d.ts

@@ -0,0 +1 @@
+export declare function scrubPackageJsonVersions(content: string): string;

package/esm/engine/__tests__/scrubPackageJsonVersions.js

@@ -0,0 +1,34 @@
+// (C) 2026 GoodData Corporation
+/**
+ * Replace dep/SDK version strings in a scaffolded package.json with the
+ * placeholder `<VERSION>`. Walks the JSON tree (rather than regex-matching
+ * raw text) so it only touches `version` and values inside the dep maps —
+ * `description`, URLs, `engines`, etc. stay verbatim.
+ *
+ * Re-serializes with the same 4-space indent + trailing newline the scaffolder
+ * itself writes (runProfile.ts), so the output is byte-identical to the
+ * scaffolded file except for the scrubbed slots.
+ *
+ * Lives outside `*.test.ts` so vitest's auto-discovery doesn't re-run callers
+ * as duplicate tests; both `snapshot.test.ts` and `scrubPackageJsonVersions.test.ts`
+ * import it.
+ */
+const DEP_MAPS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+export function scrubPackageJsonVersions(content) {
+    const pkg = JSON.parse(content);
+    if (typeof pkg["version"] === "string") {
+        pkg["version"] = "<VERSION>";
+    }
+    for (const key of DEP_MAPS) {
+        const deps = pkg[key];
+        if (deps && typeof deps === "object" && !Array.isArray(deps)) {
+            const depsRecord = deps;
+            for (const dep of Object.keys(depsRecord)) {
+                if (typeof depsRecord[dep] === "string") {
+                    depsRecord[dep] = "<VERSION>";
+                }
+            }
+        }
+    }
+    return JSON.stringify(pkg, null, 4) + "\n";
+}

package/esm/engine/__tests__/scrubPackageJsonVersions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/scrubPackageJsonVersions.test.js

@@ -0,0 +1,79 @@
+// (C) 2026 GoodData Corporation
+import { describe, expect, it } from "vitest";
+import { scrubPackageJsonVersions } from "./scrubPackageJsonVersions.js";
+/**
+ * Direct tests for the package.json version-scrubber used by the snapshot test.
+ * The scrubber's contract:
+ *   1. Replaces top-level `version` with "<VERSION>".
+ *   2. Replaces every string value inside the four dep maps with "<VERSION>".
+ *   3. Leaves everything else alone — descriptions, URLs, engines, repository,
+ *      author, etc. — even when those strings happen to contain an X.Y.Z
+ *      substring.
+ *
+ * Without these tests the scrubber's correctness is only inferred from the
+ * full snapshot, which would also pass if the function quietly over-matched.
+ */
+describe("scrubPackageJsonVersions", () => {
+    function scrubAndParse(pkg) {
+        return JSON.parse(scrubPackageJsonVersions(JSON.stringify(pkg, null, 4) + "\n"));
+    }
+    it("scrubs the top-level version field", () => {
+        const out = scrubAndParse({ name: "x", version: "1.2.3-alpha.0" });
+        expect(out["version"]).toBe("<VERSION>");
+    });
+    it("scrubs every entry in dependencies, devDependencies, peerDependencies, optionalDependencies", () => {
+        const out = scrubAndParse({
+            dependencies: { react: "19.1.1", "@gooddata/sdk-ui": "workspace:*" },
+            devDependencies: { vite: "^8.0.0" },
+            peerDependencies: { typescript: ">=5.0.0" },
+            optionalDependencies: { fsevents: "2.3.3" },
+        });
+        expect(out["dependencies"]["react"]).toBe("<VERSION>");
+        expect(out["dependencies"]["@gooddata/sdk-ui"]).toBe("<VERSION>");
+        expect(out["devDependencies"]["vite"]).toBe("<VERSION>");
+        expect(out["peerDependencies"]["typescript"]).toBe("<VERSION>");
+        expect(out["optionalDependencies"]["fsevents"]).toBe("<VERSION>");
+    });
+    it("does NOT scrub a description containing an X.Y.Z substring (regression: this is what the old regex broke on)", () => {
+        const out = scrubAndParse({
+            name: "x",
+            description: "Works against the GoodData API v2.5.1 endpoint",
+        });
+        expect(out["description"]).toBe("Works against the GoodData API v2.5.1 endpoint");
+    });
+    it("does NOT scrub a URL containing a version-shaped path segment", () => {
+        const out = scrubAndParse({
+            name: "x",
+            homepage: "https://example.com/docs/v1.2.3/intro",
+            repository: { type: "git", url: "https://github.com/foo/bar/tree/v3.4.5" },
+        });
+        expect(out["homepage"]).toBe("https://example.com/docs/v1.2.3/intro");
+        expect(out["repository"]["url"]).toBe("https://github.com/foo/bar/tree/v3.4.5");
+    });
+    it("does NOT scrub engines (different drift cadence; informative to surface in snapshots)", () => {
+        const out = scrubAndParse({ engines: { node: ">=24.12.0" } });
+        expect(out["engines"]["node"]).toBe(">=24.12.0");
+    });
+    it("does NOT scrub author / name / license / type fields", () => {
+        const out = scrubAndParse({
+            name: "my-pkg",
+            author: "Acme",
+            license: "MIT",
+            type: "module",
+        });
+        expect(out["name"]).toBe("my-pkg");
+        expect(out["author"]).toBe("Acme");
+        expect(out["license"]).toBe("MIT");
+        expect(out["type"]).toBe("module");
+    });
+    it("survives missing / non-object dep maps without throwing", () => {
+        expect(() => scrubPackageJsonVersions(JSON.stringify({ name: "x" }))).not.toThrow();
+        // dep maps deliberately wrong shape — should not crash, just skip.
+        expect(() => scrubPackageJsonVersions(JSON.stringify({ name: "x", dependencies: null }))).not.toThrow();
+    });
+    it("emits 4-space indent + trailing newline (matches what the scaffolder itself writes)", () => {
+        const raw = scrubPackageJsonVersions(JSON.stringify({ name: "x", version: "1.0.0" }));
+        expect(raw.endsWith("\n")).toBe(true);
+        expect(raw).toContain('\n    "name"');
+    });
+});

package/esm/engine/__tests__/snapshot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/engine/__tests__/snapshot.test.js

@@ -0,0 +1,93 @@
+// (C) 2026 GoodData Corporation
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "fs";
+import { createRequire } from "module";
+import { tmpdir } from "os";
+import { dirname, join, relative } from "path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { clientProfile } from "../../profiles/client.js";
+import { runProfileWithAnswers } from "../runProfile.js";
+import { scrubPackageJsonVersions } from "./scrubPackageJsonVersions.js";
+// Resolve workspace template paths via pnpm's symlinks. The template packages
+// are devDependencies of @gooddata/create-pluggable-module — pnpm symlinks
+// them into this package's node_modules in workspace mode. Probe target is
+// `<pkg>/tsconfig.json` (template packages don't export `./package.json`).
+const requireFromHere = createRequire(import.meta.url);
+const WORKSPACE_TEMPLATE_ROOTS = {
+    module: dirname(requireFromHere.resolve("gdc-app-template-name-module/tsconfig.json")),
+    harness: dirname(requireFromHere.resolve("gdc-app-template-name-harness/tsconfig.json")),
+};
+/**
+ * Walks a directory and returns a stable, sorted map of relative-path → file
+ * content. Used to snapshot the entire scaffolded tree.
+ */
+function treeToMap(root) {
+    const out = {};
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            const rel = relative(root, abs);
+            // Binary files (images, fonts) — record only their size so changes
+            // surface in the snapshot without including raw bytes.
+            const ext = entry.name.slice(entry.name.lastIndexOf(".")).toLowerCase();
+            if ([".png", ".jpg", ".jpeg", ".gif", ".ico", ".woff", ".woff2", ".ttf", ".eot"].includes(ext)) {
+                out[rel] = `<binary, ${statSync(abs).size} bytes>`;
+                continue;
+            }
+            const raw = readFileSync(abs, "utf-8");
+            out[rel] = entry.name === "package.json" ? scrubPackageJsonVersions(raw) : raw;
+        }
+    }
+    walk(root);
+    return out;
+}
+describe("snapshot: client profile end-to-end scaffold", () => {
+    let testRoot;
+    beforeEach(() => {
+        testRoot = mkdtempSync(join(tmpdir(), "scaff-snapshot-"));
+        // Silence the scaffolder's console output during tests.
+        vi.spyOn(console, "log").mockImplementation(() => { });
+        vi.spyOn(console, "warn").mockImplementation(() => { });
+        vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        rmSync(testRoot, { recursive: true, force: true });
+        vi.restoreAllMocks();
+    });
+    it("produces a deterministic scaffold (client profile, fresh non-rush dir)", async () => {
+        // Two overrides on the client profile for snapshot purposes:
+        //   1. postCopy: client profile would otherwise try to run `npm install` —
+        //      irrelevant to the file-tree snapshot.
+        //   2. preferWorkspaceTemplate: hermetic source selection. The engine's
+        //      default is "use dist/templates/ if it exists, else workspace" —
+        //      which silently flips the test's source depending on whether anyone
+        //      ran prepack on this machine. Force workspace so the snapshot is
+        //      reproducible from a clean checkout.
+        const profileForSnapshot = {
+            ...clientProfile,
+            preferWorkspaceTemplate: true,
+            // Engine refuses to resolve workspace templates without explicit roots —
+            // supply the require.resolve-derived paths.
+            templateSubtreeRoots: WORKSPACE_TEMPLATE_ROOTS,
+            postCopy: async () => {
+                // no-op — snapshot only cares about the produced file tree
+            },
+        };
+        await runProfileWithAnswers(profileForSnapshot, {
+            appName: "gdc-snap-test",
+            title: "Snapshot Test",
+            scope: "workspace",
+        }, {
+            repo: {
+                repoRoot: testRoot,
+                packageManager: "npm",
+            },
+            steps: [], // no registration anchors needed in a non-rush dir
+        });
+        const tree = treeToMap(join(testRoot, "modules", "gdc-snap-test"));
+        expect(tree).toMatchSnapshot();
+    });
+});

package/esm/engine/anchors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Anchor-based insertion. Files touched by the scaffolder carry a
+ * `PLUGGABLE_APP_SCAFFOLD_ANCHOR` comment marking the insertion point. The
+ * keyword is identical across file types; only the surrounding comment syntax
+ * differs (`//`, `#`, etc.). Files with more than one insertion point
+ * disambiguate with a parenthesised suffix — e.g.
+ * `PLUGGABLE_APP_SCAFFOLD_ANCHOR (stages)`.
+ */
+export declare const ANCHOR_KEYWORD = "PLUGGABLE_APP_SCAFFOLD_ANCHOR";
+export declare function fullAnchor(suffix?: string): string;
+/**
+ * Locates the line containing the anchor. Throws if zero or more-than-one
+ * matches are found — the latter would mean the file's anchor disambiguation
+ * is broken and would silently corrupt subsequent runs.
+ */
+export declare function findAnchorLineIdx(lines: readonly string[], filename: string, suffix?: string): number;
+export declare function insertBeforeAnchor(content: string, filename: string, linesToInsert: readonly string[], suffix?: string): string;

package/esm/engine/anchors.js

@@ -0,0 +1,43 @@
+// (C) 2026 GoodData Corporation
+/**
+ * Anchor-based insertion. Files touched by the scaffolder carry a
+ * `PLUGGABLE_APP_SCAFFOLD_ANCHOR` comment marking the insertion point. The
+ * keyword is identical across file types; only the surrounding comment syntax
+ * differs (`//`, `#`, etc.). Files with more than one insertion point
+ * disambiguate with a parenthesised suffix — e.g.
+ * `PLUGGABLE_APP_SCAFFOLD_ANCHOR (stages)`.
+ */
+export const ANCHOR_KEYWORD = "PLUGGABLE_APP_SCAFFOLD_ANCHOR";
+export function fullAnchor(suffix) {
+    return suffix ? `${ANCHOR_KEYWORD} ${suffix}` : ANCHOR_KEYWORD;
+}
+/**
+ * Locates the line containing the anchor. Throws if zero or more-than-one
+ * matches are found — the latter would mean the file's anchor disambiguation
+ * is broken and would silently corrupt subsequent runs.
+ */
+export function findAnchorLineIdx(lines, filename, suffix) {
+    const needle = fullAnchor(suffix);
+    const matches = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(needle))
+            matches.push(i);
+    }
+    if (matches.length === 0) {
+        throw new Error(`Could not find "${needle}" in ${filename}. The anchor comment must be present so ` +
+            `the scaffolder knows where to insert new pluggable app entries.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} lines matching "${needle}" in ${filename} (at lines ${matches
+            .map((i) => i + 1)
+            .join(", ")}). Each anchor must be unique — use a "(suffix)" if multiple ` +
+            `insertion points are needed.`);
+    }
+    return matches[0];
+}
+export function insertBeforeAnchor(content, filename, linesToInsert, suffix) {
+    const lines = content.split("\n");
+    const idx = findAnchorLineIdx(lines, filename, suffix);
+    lines.splice(idx, 0, ...linesToInsert);
+    return lines.join("\n");
+}

package/esm/engine/checkAnchors.d.ts

@@ -0,0 +1,12 @@
+import type { IRegistrationStep } from "../types.js";
+/**
+ * Pre-flight check. Files edited by the scaffolder must already contain the
+ * PLUGGABLE_APP_SCAFFOLD_ANCHOR comment (with the right suffix where applicable)
+ * — otherwise the script would prompt the user, copy template files, and only
+ * THEN fail mid-way leaving a half-scaffolded state. Bail before any of that
+ * happens.
+ *
+ * Iterates over the profile's `registrations()` list — same list used by the
+ * insertion pass, so the two cannot drift.
+ */
+export declare function checkAnchors(steps: readonly IRegistrationStep[], repoRoot: string): void;

package/esm/engine/checkAnchors.js

@@ -0,0 +1,44 @@
+// (C) 2026 GoodData Corporation
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { fullAnchor } from "./anchors.js";
+/**
+ * Pre-flight check. Files edited by the scaffolder must already contain the
+ * PLUGGABLE_APP_SCAFFOLD_ANCHOR comment (with the right suffix where applicable)
+ * — otherwise the script would prompt the user, copy template files, and only
+ * THEN fail mid-way leaving a half-scaffolded state. Bail before any of that
+ * happens.
+ *
+ * Iterates over the profile's `registrations()` list — same list used by the
+ * insertion pass, so the two cannot drift.
+ */
+export function checkAnchors(steps, repoRoot) {
+    const missing = [];
+    for (const { file, suffix } of steps) {
+        const fullPath = join(repoRoot, file);
+        if (!existsSync(fullPath)) {
+            missing.push({ file, suffix, reason: "file not found" });
+            continue;
+        }
+        const content = readFileSync(fullPath, "utf-8");
+        const needle = fullAnchor(suffix);
+        if (!content.includes(needle)) {
+            missing.push({ file, suffix, reason: `missing "${needle}" comment` });
+        }
+    }
+    if (missing.length === 0)
+        return;
+    console.error("\n  Error: required PLUGGABLE_APP_SCAFFOLD_ANCHOR comments are missing.\n");
+    console.error("  The scaffolder inserts new entries before an anchor comment in each file");
+    console.error("  it touches. Without the anchor it cannot register the new pluggable app.\n");
+    console.error("  Missing in:");
+    for (const { file, suffix, reason } of missing) {
+        const label = suffix ? `${file} (anchor "${suffix}")` : file;
+        console.error(`    - ${label}: ${reason}`);
+    }
+    console.error(`\n  Each file needs a comment containing "PLUGGABLE_APP_SCAFFOLD_ANCHOR"`);
+    console.error(`  (with the listed suffix in parentheses if applicable) at the line where new`);
+    console.error(`  entries should be inserted. See an existing entry in any of the other anchor`);
+    console.error(`  files for the exact comment format used in that file type.\n`);
+    process.exit(1);
+}

package/esm/engine/copyTemplate.d.ts

@@ -0,0 +1,11 @@
+import type { TokenReplacements } from "../types.js";
+export interface ICopyResult {
+    /** Absolute paths of every file written. Used for the package.json transform pass. */
+    written: string[];
+}
+/**
+ * Recursively copies srcDir → destDir applying ordered string replacement to
+ * every non-binary file. Returns the list of files written so the caller can
+ * post-process specific paths (e.g. transformPackageJson).
+ */
+export declare function copyTemplate(srcDir: string, destDir: string, replacements: TokenReplacements): ICopyResult;