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

package/esm/engine/copyTemplate.js

@@ -0,0 +1,70 @@
+// (C) 2026 GoodData Corporation
+import { cpSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { join } from "path";
+/**
+ * Directories that should never be copied. Tooling output (`node_modules`,
+ * `esm`, `dist`, `.rush`, etc.) gets regenerated by the consumer's package
+ * manager once the new module is installed, and including them would balloon
+ * the published tarball and risk shipping stale .tsbuildinfo / .vite caches.
+ */
+const SKIP_DIRS = new Set(["node_modules", "esm", "dist", ".rush", "rush-logs", ".__mf__temp", ".vite"]);
+const SKIP_SUFFIXES = [".tsbuildinfo"];
+/**
+ * Files for which token-substitution-in-text would corrupt the byte stream.
+ * Binary files must be copied verbatim.
+ */
+const BINARY_EXTENSIONS = new Set([
+    ".ico",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+]);
+/**
+ * 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 function copyTemplate(srcDir, destDir, replacements) {
+    const written = [];
+    copyRecursive(srcDir, destDir, replacements, written);
+    return { written };
+}
+function copyRecursive(srcDir, destDir, replacements, written) {
+    mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = join(srcDir, entry.name);
+        const destPath = join(destDir, entry.name);
+        // Symlinks and rush-style packages-link dirs would not survive npm-pack anyway —
+        // and copying them in client repos would yank in unrelated workspace state.
+        if (entry.isSymbolicLink() || entry.name === "packages-link")
+            continue;
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            copyRecursive(srcPath, destPath, replacements, written);
+            continue;
+        }
+        if (SKIP_SUFFIXES.some((s) => entry.name.endsWith(s)))
+            continue;
+        copyFile(srcPath, destPath, entry.name, replacements, written);
+    }
+}
+function copyFile(srcPath, destPath, name, replacements, written) {
+    const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+    if (BINARY_EXTENSIONS.has(ext)) {
+        cpSync(srcPath, destPath);
+        written.push(destPath);
+        return;
+    }
+    let content = readFileSync(srcPath, "utf-8");
+    for (const [token, value] of replacements) {
+        content = content.replaceAll(token, value);
+    }
+    writeFileSync(destPath, content, "utf-8");
+    written.push(destPath);
+}

package/esm/engine/derived.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure name transformations shared between profiles. No filesystem access —
+ * these turn an `appName` into the conventionally-derived route, federation
+ * name, and remote-URL env-var name.
+ */
+export declare function computeRoute(appName: string): string;
+/** Module Federation `name` must be a valid JS identifier. */
+export declare function computeFederationName(appName: string): string;
+/**
+ * Compile-time global name. Follows the existing host pattern
+ * (HOME_UI_REMOTE_URL): strip "gdc-", uppercase, "-" → "_", add suffix.
+ */
+export declare function computeRemoteUrlEnvVar(appName: string): string;
+/**
+ * Scans every harness vite.config.ts under <repoRoot>/modules/ (and apps/) for
+ * the PORT default literal, returns the next available port. The harness port
+ * vs module-federation preview port live in pairs separated by +100, hence the
+ * +1 here (caller adds +100 for the federation port).
+ *
+ * `extraDirs` adds host-shaped directories beyond `modules/` to also scan —
+ * gdc-ui includes `apps/` here, the lean repo passes nothing.
+ */
+export declare function computeDevPort(repoRoot: string, extraDirs?: readonly string[]): number;
+/**
+ * Returns this package's own version, read at runtime from its package.json.
+ * Used by the client profile to stamp `workspace:*` SDK deps with a concrete
+ * version that matches the SDK release this scaffolder shipped against.
+ *
+ * Resolved via import.meta.url so it works whether the engine runs from src/
+ * (during local dev) or esm/ (after publish).
+ */
+export declare function getOwnPackageVersion(): string;

package/esm/engine/derived.js

@@ -0,0 +1,85 @@
+// (C) 2026 GoodData Corporation
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+/**
+ * Pure name transformations shared between profiles. No filesystem access —
+ * these turn an `appName` into the conventionally-derived route, federation
+ * name, and remote-URL env-var name.
+ */
+export function computeRoute(appName) {
+    return "/" + appName.replace(/^gdc-/, "");
+}
+/** Module Federation `name` must be a valid JS identifier. */
+export function computeFederationName(appName) {
+    return appName.replaceAll("-", "_");
+}
+/**
+ * Compile-time global name. Follows the existing host pattern
+ * (HOME_UI_REMOTE_URL): strip "gdc-", uppercase, "-" → "_", add suffix.
+ */
+export function computeRemoteUrlEnvVar(appName) {
+    return appName.replace(/^gdc-/, "").replaceAll("-", "_").toUpperCase() + "_REMOTE_URL";
+}
+/**
+ * Scans every harness vite.config.ts under <repoRoot>/modules/ (and apps/) for
+ * the PORT default literal, returns the next available port. The harness port
+ * vs module-federation preview port live in pairs separated by +100, hence the
+ * +1 here (caller adds +100 for the federation port).
+ *
+ * `extraDirs` adds host-shaped directories beyond `modules/` to also scan —
+ * gdc-ui includes `apps/` here, the lean repo passes nothing.
+ */
+export function computeDevPort(repoRoot, extraDirs = []) {
+    // 8449 is the seed: gdc-sample-users sits at 8450; new apps start above it.
+    let maxPort = 8449;
+    const scanForHarnessPorts = (root, viteRelativePath) => {
+        if (!existsSync(root))
+            return;
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const viteConfig = join(root, entry.name, viteRelativePath);
+            if (!existsSync(viteConfig))
+                continue;
+            const content = readFileSync(viteConfig, "utf-8");
+            const portMatch = content.match(/["']PORT["']\]?\)?\s*\|\|\s*["'](\d+)["']/);
+            if (portMatch) {
+                const port = parseInt(portMatch[1], 10);
+                if (port > maxPort)
+                    maxPort = port;
+            }
+            else {
+                // The regex is tuned to the harness template shape
+                // (`env["PORT"] || "NNNN"`). A miss usually means the harness
+                // was hand-refactored — warn so the next scaffolded app's port
+                // collision doesn't surprise the user at dev-server start time.
+                console.warn(`  Warning: could not detect port literal in ${viteConfig} — port collision possible.`);
+            }
+        }
+    };
+    scanForHarnessPorts(join(repoRoot, "modules"), "harness/vite.config.ts");
+    for (const extra of extraDirs) {
+        scanForHarnessPorts(join(repoRoot, extra), "vite.config.ts");
+    }
+    return maxPort + 1;
+}
+/**
+ * Returns this package's own version, read at runtime from its package.json.
+ * Used by the client profile to stamp `workspace:*` SDK deps with a concrete
+ * version that matches the SDK release this scaffolder shipped against.
+ *
+ * Resolved via import.meta.url so it works whether the engine runs from src/
+ * (during local dev) or esm/ (after publish).
+ */
+export function getOwnPackageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // engine/derived.{ts,js} → src or esm, then up one more to package root.
+    const pkgPath = join(here, "..", "..", "package.json");
+    const raw = readFileSync(pkgPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.version) {
+        throw new Error(`create-pluggable-module package.json at ${pkgPath} has no "version" field.`);
+    }
+    return parsed.version;
+}

package/esm/engine/jsonAnchors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Walks back from the anchor line in a JSONC file and appends a comma to the
+ * last real code line if it doesn't already end with one. Idempotent: if the
+ * comma is already there (e.g. a previous scaffold added it), this is a no-op.
+ *
+ * JSONC requires a comma between array entries. The original `rush init-pluggable-app`
+ * scripts in both gdc-ui repos did this fix-up by hand; this generalises it so any
+ * profile inserting into a JSONC array can use it.
+ *
+ * Inline `// ...` comments after a JSON token are preserved exactly where they were —
+ * the comma slots into the gap between the code part and the comment, not at end of line.
+ */
+export declare function ensureTrailingCommaBeforeAnchor(content: string, suffix?: string): string;

package/esm/engine/jsonAnchors.js

@@ -0,0 +1,42 @@
+// (C) 2026 GoodData Corporation
+import { findAnchorLineIdx, fullAnchor } from "./anchors.js";
+/**
+ * Walks back from the anchor line in a JSONC file and appends a comma to the
+ * last real code line if it doesn't already end with one. Idempotent: if the
+ * comma is already there (e.g. a previous scaffold added it), this is a no-op.
+ *
+ * JSONC requires a comma between array entries. The original `rush init-pluggable-app`
+ * scripts in both gdc-ui repos did this fix-up by hand; this generalises it so any
+ * profile inserting into a JSONC array can use it.
+ *
+ * Inline `// ...` comments after a JSON token are preserved exactly where they were —
+ * the comma slots into the gap between the code part and the comment, not at end of line.
+ */
+export function ensureTrailingCommaBeforeAnchor(content, suffix) {
+    const lines = content.split("\n");
+    // Synthetic filename — findAnchorLineIdx's error messages need a label and this
+    // helper isn't told the real path. The label only matters if the anchor is missing,
+    // which can't actually happen here because checkAnchors already verified the file.
+    const anchorIdx = findAnchorLineIdx(lines, `<jsonc with ${fullAnchor(suffix)}>`, suffix);
+    for (let i = anchorIdx - 1; i >= 0; i--) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed.startsWith("//"))
+            continue;
+        const commentIdx = raw.indexOf("//");
+        const codePart = commentIdx === -1 ? raw : raw.slice(0, commentIdx);
+        if (!codePart.trimEnd().endsWith(",")) {
+            if (commentIdx === -1) {
+                lines[i] = raw.trimEnd() + ",";
+            }
+            else {
+                const code = codePart.replace(/\s+$/, "");
+                // Whitespace between token and `//`.
+                const gap = codePart.slice(code.length);
+                lines[i] = code + "," + gap + raw.slice(commentIdx);
+            }
+        }
+        break;
+    }
+    return lines.join("\n");
+}

package/esm/engine/prompts.d.ts

@@ -0,0 +1,15 @@
+import type { IPromptDescriptor, IScaffoldAnswers } from "../types.js";
+/**
+ * Shared text-value sanity check. Blocks characters that would either break
+ * shell/script substitution (`"`, `\``, `$`, `\`), break template token
+ * substitution (`{`, `}`), or break line-based file formats (`\n`, `\r`).
+ *
+ * Exported so profiles can reuse it on their own extra prompts and keep the
+ * accepted character set consistent across the scaffolder.
+ */
+export declare function validateTextValue(value: string): string | null;
+/**
+ * Drives the full prompt sequence: shared appName/title/scope, then the
+ * profile's extraPrompts in order. Returns once every answer is collected.
+ */
+export declare function runPrompts(extraPrompts: readonly IPromptDescriptor[]): Promise<IScaffoldAnswers>;

package/esm/engine/prompts.js

@@ -0,0 +1,157 @@
+// (C) 2026 GoodData Corporation
+import { createInterface } from "readline";
+/**
+ * Thin wrapper over readline's `line` events. The reason we can't use
+ * `rl.question(prompt, cb)` is that `cb` is only attached when question() runs;
+ * if input arrives faster than question() can re-attach (which happens whenever
+ * stdin is a pipe rather than a TTY), `line` events fire with no listeners and
+ * the data is lost. We buffer them ourselves so piped input works correctly —
+ * essential for non-interactive smoke tests and CI.
+ */
+class LineReader {
+    rl;
+    buffer = [];
+    pending;
+    closed = false;
+    constructor() {
+        this.rl = createInterface({ input: process.stdin, output: process.stdout });
+        this.rl.on("line", (line) => {
+            if (this.pending) {
+                const fn = this.pending;
+                this.pending = undefined;
+                fn(line);
+            }
+            else {
+                this.buffer.push(line);
+            }
+        });
+        this.rl.on("close", () => {
+            this.closed = true;
+            if (this.pending) {
+                const fn = this.pending;
+                this.pending = undefined;
+                fn(undefined);
+            }
+        });
+    }
+    /** Resolves with the next line, or undefined if stdin closed without one. */
+    next() {
+        if (this.pending) {
+            // Footgun-guard: two pending reads on the same LineReader would
+            // have the second silently overwrite the first's resolver. Callers
+            // must await each next() before starting the next one.
+            throw new Error("LineReader.next() called while previous next() is still pending");
+        }
+        if (this.buffer.length > 0) {
+            return Promise.resolve(this.buffer.shift());
+        }
+        if (this.closed) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve) => {
+            this.pending = resolve;
+        });
+    }
+    close() {
+        this.rl.close();
+    }
+}
+const APP_NAME_RE = /^gdc-[a-z][a-z0-9-]*$/;
+/**
+ * Shared text-value sanity check. Blocks characters that would either break
+ * shell/script substitution (`"`, `\``, `$`, `\`), break template token
+ * substitution (`{`, `}`), or break line-based file formats (`\n`, `\r`).
+ *
+ * Exported so profiles can reuse it on their own extra prompts and keep the
+ * accepted character set consistent across the scaffolder.
+ */
+export function validateTextValue(value) {
+    if (/["\\\n\r`${}]/.test(value)) {
+        return "Must not contain double quotes, backslashes, backticks, dollar signs, curly braces, or newlines.";
+    }
+    return null;
+}
+// Name format only — destination-collision checking happens later in the engine,
+// AFTER the profile has resolved the dest root (the client profile lets the user
+// override the destPath, so checking modules/<name> here would miss real collisions
+// and false-positive on overrides). See runProfile.ts.
+function validateAppName(name) {
+    if (!APP_NAME_RE.test(name)) {
+        return `App name must start with "gdc-" and contain only lowercase letters, digits, and hyphens.`;
+    }
+    if (name.startsWith("gdc-app-template")) {
+        return `Names starting with "gdc-app-template" are reserved for the template itself. Choose a different name.`;
+    }
+    return null;
+}
+async function ask(reader, question) {
+    process.stdout.write(question);
+    const line = await reader.next();
+    if (line === undefined) {
+        throw new Error("stdin closed before a value was provided — non-interactive input ran out.");
+    }
+    return line;
+}
+async function askUntilValid(reader, label, validate) {
+    while (true) {
+        const value = (await ask(reader, `  ${label}: `)).trim();
+        const err = validate(value);
+        if (!err)
+            return value;
+        console.log(`  Error: ${err}`);
+    }
+}
+async function askScope(reader) {
+    while (true) {
+        const choice = (await ask(reader, "  Application scope (1 = workspace, 2 = organization): ")).trim();
+        if (choice === "1")
+            return "workspace";
+        if (choice === "2")
+            return "organization";
+        console.log('  Error: Enter "1" or "2".');
+    }
+}
+/**
+ * Drives the full prompt sequence: shared appName/title/scope, then the
+ * profile's extraPrompts in order. Returns once every answer is collected.
+ */
+export async function runPrompts(extraPrompts) {
+    const reader = new LineReader();
+    try {
+        console.log("\n  Scaffold a new pluggable application\n");
+        const appName = await askUntilValid(reader, "App name (must start with gdc-)", validateAppName);
+        const title = await askUntilValid(reader, "en-US title", (v) => {
+            if (!v)
+                return "Title is required.";
+            return validateTextValue(v);
+        });
+        const scope = await askScope(reader);
+        const answers = { appName, title, scope };
+        for (const prompt of extraPrompts) {
+            const value = await askExtra(reader, prompt);
+            if (value !== undefined) {
+                answers[prompt.key] = value;
+            }
+        }
+        return answers;
+    }
+    finally {
+        reader.close();
+    }
+}
+async function askExtra(reader, prompt) {
+    while (true) {
+        const suffix = prompt.optional ? " (optional, press Enter to skip)" : "";
+        const value = (await ask(reader, `  ${prompt.label}${suffix}: `)).trim();
+        if (!value) {
+            if (prompt.optional)
+                return undefined;
+            console.log("  Error: A value is required.");
+            continue;
+        }
+        const err = prompt.validate ? prompt.validate(value) : null;
+        if (!err)
+            return value;
+        console.log(`  Error: ${err}`);
+    }
+}

package/esm/engine/repoDetection.d.ts

@@ -0,0 +1,18 @@
+import type { IRepoInfo } from "../types.js";
+/**
+ * Walks from `startDir` upward looking for a marker file. Returns the directory
+ * containing the marker, or undefined if reached the filesystem root without
+ * finding it. Used to locate `rush.json` from any subdir within a Rush monorepo.
+ */
+export declare function findUp(startDir: string, marker: string): string | undefined;
+/**
+ * Detects the repo shape from `cwd`. The result drives:
+ * - which postCopy command runs (rush update vs npm install vs ...)
+ * - whether profiles register in rush.json
+ * - the absolute `repoRoot` that other engine steps anchor against.
+ *
+ * Precedence: rush.json wins (Rush monorepos always have a lockfile too).
+ * Otherwise, pick the package manager from whichever lockfile exists. Falls
+ * back to `npm` for fresh repos with no lockfile yet.
+ */
+export declare function detectRepo(cwd: string): IRepoInfo;

package/esm/engine/repoDetection.js

@@ -0,0 +1,47 @@
+// (C) 2026 GoodData Corporation
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+/**
+ * Walks from `startDir` upward looking for a marker file. Returns the directory
+ * containing the marker, or undefined if reached the filesystem root without
+ * finding it. Used to locate `rush.json` from any subdir within a Rush monorepo.
+ */
+export function findUp(startDir, marker) {
+    let dir = resolve(startDir);
+    while (true) {
+        if (existsSync(join(dir, marker)))
+            return dir;
+        const parent = resolve(dir, "..");
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Detects the repo shape from `cwd`. The result drives:
+ * - which postCopy command runs (rush update vs npm install vs ...)
+ * - whether profiles register in rush.json
+ * - the absolute `repoRoot` that other engine steps anchor against.
+ *
+ * Precedence: rush.json wins (Rush monorepos always have a lockfile too).
+ * Otherwise, pick the package manager from whichever lockfile exists. Falls
+ * back to `npm` for fresh repos with no lockfile yet.
+ */
+export function detectRepo(cwd) {
+    const rushRoot = findUp(cwd, "rush.json");
+    if (rushRoot) {
+        return { repoRoot: rushRoot, packageManager: "rush" };
+    }
+    const repoRoot = resolve(cwd);
+    const packageManager = detectPackageManager(repoRoot);
+    return { repoRoot, packageManager };
+}
+function detectPackageManager(repoRoot) {
+    if (existsSync(join(repoRoot, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(repoRoot, "yarn.lock")))
+        return "yarn";
+    // package-lock.json or no lockfile at all → default to npm. A scaffolder
+    // running in a fresh empty repo can still invoke `npm install` afterwards.
+    return "npm";
+}

package/esm/engine/runProfile.d.ts

@@ -0,0 +1,18 @@
+import type { IRegistrationStep, IRepoInfo, IScaffoldAnswers, IScaffoldProfile } from "../types.js";
+export declare function runProfile(profile: IScaffoldProfile): Promise<void>;
+/**
+ * Test-friendly variant: skip prompt collection, take answers as input.
+ * Also useful for programmatic consumers that want to drive the scaffolder
+ * without an interactive TTY.
+ *
+ * @alpha
+ */
+export declare function runProfileWithAnswers(profile: IScaffoldProfile, answers: IScaffoldAnswers, options?: {
+    /** Optional repo override (defaults to detecting from process.cwd()). */
+    repo?: IRepoInfo;
+    /**
+     * Optional pre-resolved registration steps. The engine usually recomputes
+     * these from `profile.registrations(repo)`; tests can pass a fixture set.
+     */
+    steps?: readonly IRegistrationStep[];
+}): Promise<void>;