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

package/esm/engine/runProfile.js

@@ -0,0 +1,179 @@
+// (C) 2026 GoodData Corporation
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { basename, dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { insertBeforeAnchor } from "./anchors.js";
+import { checkAnchors } from "./checkAnchors.js";
+import { copyTemplate } from "./copyTemplate.js";
+import { runPrompts } from "./prompts.js";
+import { detectRepo } from "./repoDetection.js";
+/**
+ * Resolves the on-disk location of a single template subtree (`module` or `harness`).
+ *
+ * Two cases:
+ *   1. Published: prepack-bundle-template.sh copied templates into our own
+ *      package's `dist/templates/<subtree>/`. Use those — already path-rewritten.
+ *   2. Workspace dev: resolve the template package via require.resolve, so the
+ *      dependency graph stays honest. Templates live as workspace siblings.
+ *
+ * The template package names are the literal placeholder strings that get
+ * substituted at scaffold time. They look like template tokens; they ARE real
+ * workspace package identifiers.
+ */
+function getTemplateSubtreeRoot(subtree, preferWorkspace, explicitRoots) {
+    // 1. Explicit override wins. Profiles use this when the templates aren't
+    //    resolvable from the engine's runtime location — e.g. gdc-ui's internal
+    //    scaffolder, where the engine runs from a transitively-installed
+    //    `.pnpm/.../@gooddata/create-pluggable-module/` location that doesn't
+    //    have the workspace template packages alongside.
+    const explicit = explicitRoots?.[subtree];
+    if (explicit) {
+        if (!existsSync(explicit)) {
+            throw new Error(`Profile-supplied templateSubtreeRoots["${subtree}"] points at "${explicit}" but no directory exists there.`);
+        }
+        return explicit;
+    }
+    // 2. `preferWorkspaceTemplate` opts out of the bundled `dist/templates/`
+    //    path AND requires the profile to supply paths. Without paths there's
+    //    no safe place to find workspace templates at runtime — fail loudly
+    //    instead of falling through to brittle dependency-graph resolution.
+    if (preferWorkspace) {
+        throw new Error(`Profile sets preferWorkspaceTemplate=true but did not supply templateSubtreeRoots["${subtree}"]. ` +
+            `Workspace templates can't be resolved at runtime without an explicit absolute path — ` +
+            `populate templateSubtreeRoots[] in the profile (typically via import.meta.url-relative resolution).`);
+    }
+    // 3. Published path under dist/templates/ — created by prepack-bundle-template.sh
+    //    just before `npm pack` and consumed by external clients via `npm init`.
+    //    The bundled tsconfigs are pre-inlined so they don't need workspace parents.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const publishedRoot = join(here, "..", "..", "dist", "templates", subtree);
+    if (existsSync(publishedRoot))
+        return publishedRoot;
+    // 4. Nothing left to try. Both paths require setup we don't have.
+    throw new Error(`No template root for subtree "${subtree}". Either supply templateSubtreeRoots["${subtree}"] in the profile, ` +
+        `or ensure dist/templates/${subtree}/ exists (run prepack-bundle-template.sh).`);
+}
+export async function runProfile(profile) {
+    // 1. Detect the repo shape — drives everything downstream.
+    const repo = detectRepo(process.cwd());
+    // 2. Pre-flight: every file the profile wants to register in must already
+    //    carry the right anchor. Bail before prompts so we don't half-scaffold.
+    const steps = profile.registrations(repo);
+    checkAnchors(steps, repo.repoRoot);
+    // 3. Prompts: shared appName/title/scope + the profile's extras.
+    const answers = await runPrompts(profile.extraPrompts);
+    await runProfileWithAnswers(profile, answers, { repo, steps });
+}
+/**
+ * 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 async function runProfileWithAnswers(profile, answers, options) {
+    const repo = options?.repo ?? detectRepo(process.cwd());
+    const steps = options?.steps ?? profile.registrations(repo);
+    // Pre-flight in case caller didn't already do it (the prompts entry does).
+    if (!options?.steps) {
+        checkAnchors(steps, repo.repoRoot);
+    }
+    // 4. Resolve destRoot via the profile (it may consume an extra prompt like
+    //    destPath) THEN check the destination doesn't already exist. Hard-coding
+    //    `modules/<name>` here would miss real collisions when the client profile
+    //    rewrote destPath, and would false-positive when the user explicitly
+    //    targeted somewhere else.
+    const destRoot = profile.resolveDestRoot(answers, repo.repoRoot);
+    if (existsSync(destRoot)) {
+        throw new Error(`Destination ${destRoot} already exists. Choose a different app name or destPath, or remove the directory.`);
+    }
+    // 5. Derived values. Profile-specific because devPort scanning and menuOrder
+    //    computation depend on the host's registry shape.
+    const derived = profile.derive(answers, repo);
+    const ctx = {
+        answers,
+        derived,
+        repoRoot: repo.repoRoot,
+        destRoot,
+        packageManager: repo.packageManager,
+    };
+    printPlan(ctx, profile);
+    // 6. Copy template subtrees in declared order, applying token replacements.
+    const replacements = profile.buildReplacements(ctx);
+    const packageJsonsToTransform = [];
+    const preferWorkspace = profile.preferWorkspaceTemplate ?? false;
+    for (const subtree of profile.templateSubtrees) {
+        // getTemplateSubtreeRoot guarantees the returned path exists — every
+        // branch either throws or returns a path that just passed existsSync.
+        const srcDir = getTemplateSubtreeRoot(subtree, preferWorkspace, profile.templateSubtreeRoots);
+        const destSubtree = join(destRoot, subtree);
+        console.log(`\n  Copying template ${subtree}/ → ${relativeTo(repo.repoRoot, destSubtree)}/ ...`);
+        const { written } = copyTemplate(srcDir, destSubtree, replacements);
+        // Collect package.json paths for the post-copy transform pass.
+        for (const path of written) {
+            if (basename(path) === "package.json") {
+                packageJsonsToTransform.push(path);
+            }
+        }
+    }
+    // 6b. Apply profile-specific overlays on top of the templates. Used by
+    //     profiles that need files which shouldn't live in the shared template
+    //     (e.g. internal-only deploy configs that would leak GoodData infra if
+    //     shipped to client repos). See IOverlayPath.
+    for (const overlay of profile.overlayPaths ?? []) {
+        if (!existsSync(overlay.srcDir)) {
+            throw new Error(`Overlay source directory "${overlay.srcDir}" (destSubdir "${overlay.destSubdir}") does not exist.`);
+        }
+        const destSubtree = join(destRoot, overlay.destSubdir);
+        console.log(`  Applying overlay → ${relativeTo(repo.repoRoot, destSubtree)}/ (from ${overlay.srcDir}) ...`);
+        const { written } = copyTemplate(overlay.srcDir, destSubtree, replacements);
+        for (const path of written) {
+            if (basename(path) === "package.json") {
+                packageJsonsToTransform.push(path);
+            }
+        }
+    }
+    // 7. Per-package.json transform. Internal profile is a no-op; client rewrites
+    //    workspace:* deps to concrete semver versions.
+    for (const path of packageJsonsToTransform) {
+        const before = JSON.parse(readFileSync(path, "utf-8"));
+        const after = profile.transformPackageJson(before, ctx);
+        // 4-space indent + trailing newline matches the rest of the SDK.
+        writeFileSync(path, JSON.stringify(after, null, 4) + "\n", "utf-8");
+    }
+    // 8. Anchor-driven file edits. Sequential because edits to the same file from
+    //    multiple steps (e.g. host Dockerfile with two anchors) would race.
+    for (const step of steps) {
+        const fullPath = join(repo.repoRoot, step.file);
+        const suffixLabel = step.suffix ? ` (${step.suffix})` : "";
+        console.log(`  Registering in ${step.file}${suffixLabel} ...`);
+        const original = readFileSync(fullPath, "utf-8");
+        // preInsertTransform handles structural fix-ups before splice (e.g.
+        // adding a trailing comma to the last entry in a JSONC array).
+        const transformed = step.preInsertTransform
+            ? step.preInsertTransform(original, step.suffix)
+            : original;
+        const linesToInsert = step.emit(ctx);
+        const after = insertBeforeAnchor(transformed, step.file, linesToInsert, step.suffix);
+        writeFileSync(fullPath, after, "utf-8");
+    }
+    // 9. Profile-specific postCopy — rush update / npm install / nothing.
+    await profile.postCopy(ctx);
+}
+function relativeTo(repoRoot, abs) {
+    if (abs.startsWith(repoRoot)) {
+        return abs.slice(repoRoot.length).replace(/^[\\/]/, "");
+    }
+    return abs;
+}
+function printPlan(ctx, profile) {
+    const { answers, derived } = ctx;
+    console.log(`\n  Creating ${answers.appName} (profile: ${profile.name})...`);
+    console.log(`    Route:           ${derived.route}`);
+    console.log(`    Scope:           ${answers.scope}`);
+    console.log(`    Menu order:      ${derived.menuOrder}`);
+    console.log(`    Harness port:    ${derived.devPort}`);
+    console.log(`    Module fed port: ${derived.moduleDevPort}`);
+    console.log(`    Federation name: ${derived.federationName}`);
+    console.log(`    Remote URL env:  ${derived.remoteUrlEnvVar}`);
+}

package/esm/engine/spawn.d.ts

@@ -0,0 +1,13 @@
+import type { PackageManager } from "../types.js";
+/**
+ * Runs `<command> <args>` synchronously, inheriting stdio so the user sees the
+ * output as it streams. Returns true on exit code 0, false otherwise — the
+ * caller decides whether to surface the failure as fatal or as a hint in the
+ * "Next steps" message.
+ */
+export declare function runCommand(command: string, args: readonly string[], cwd: string): boolean;
+/** Returns the install command for a given package manager. */
+export declare function installCommand(pm: PackageManager): {
+    command: string;
+    args: string[];
+};

package/esm/engine/spawn.js

@@ -0,0 +1,30 @@
+// (C) 2026 GoodData Corporation
+import { spawnSync } from "child_process";
+/**
+ * Runs `<command> <args>` synchronously, inheriting stdio so the user sees the
+ * output as it streams. Returns true on exit code 0, false otherwise — the
+ * caller decides whether to surface the failure as fatal or as a hint in the
+ * "Next steps" message.
+ */
+export function runCommand(command, args, cwd) {
+    const result = spawnSync(command, [...args], {
+        cwd,
+        stdio: "inherit",
+        // Rush on Windows ships as `rush.cmd`; without shell:true spawnSync can't find it.
+        shell: process.platform === "win32",
+    });
+    return result.status === 0;
+}
+/** Returns the install command for a given package manager. */
+export function installCommand(pm) {
+    switch (pm) {
+        case "rush":
+            return { command: "rush", args: ["update"] };
+        case "pnpm":
+            return { command: "pnpm", args: ["install"] };
+        case "yarn":
+            return { command: "yarn", args: ["install"] };
+        case "npm":
+            return { command: "npm", args: ["install"] };
+    }
+}

package/esm/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runProfile, runProfileWithAnswers } from "./engine/runProfile.js";
+import { clientProfile } from "./profiles/client.js";
+export { runProfile, runProfileWithAnswers, clientProfile };
+export type { ApplicationScope, IDerivedValues, IOverlayPath, IProfileContext, IPromptDescriptor, IRegistrationStep, IRepoInfo, IScaffoldAnswers, IScaffoldProfile, PackageManager, ProfileName, TokenReplacements, } from "./types.js";
+export { ensureTrailingCommaBeforeAnchor } from "./engine/jsonAnchors.js";
+export { fullAnchor, findAnchorLineIdx, insertBeforeAnchor, ANCHOR_KEYWORD } from "./engine/anchors.js";
+export { computeRoute, computeFederationName, computeRemoteUrlEnvVar, computeDevPort, getOwnPackageVersion, } from "./engine/derived.js";
+export { runCommand, installCommand } from "./engine/spawn.js";
+export { validateTextValue } from "./engine/prompts.js";

package/esm/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// (C) 2026 GoodData Corporation
+/* oxlint-disable no-barrel-files/no-barrel-files -- this file IS the package's curated public surface */
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { runProfile, runProfileWithAnswers } from "./engine/runProfile.js";
+import { clientProfile } from "./profiles/client.js";
+// Engine API for external profile authors (e.g. gdc-ui's internal scaffolder).
+// Anything re-exported here is part of the public surface of @gooddata/create-pluggable-module.
+export { runProfile, runProfileWithAnswers, clientProfile };
+export { ensureTrailingCommaBeforeAnchor } from "./engine/jsonAnchors.js";
+export { fullAnchor, findAnchorLineIdx, insertBeforeAnchor, ANCHOR_KEYWORD } from "./engine/anchors.js";
+export { computeRoute, computeFederationName, computeRemoteUrlEnvVar, computeDevPort, getOwnPackageVersion, } from "./engine/derived.js";
+export { runCommand, installCommand } from "./engine/spawn.js";
+export { validateTextValue } from "./engine/prompts.js";
+// CLI entry — only ships the client profile. Internal/private scaffolders are
+// expected to import `runProfile` programmatically and supply their own profile.
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--help") || argv.includes("-h")) {
+        printHelp();
+        return;
+    }
+    await runProfile(clientProfile);
+}
+function printHelp() {
+    console.log(`
+  @gooddata/create-pluggable-module — scaffold a new GoodData pluggable application.
+
+  Usage:
+    npm init @gooddata/pluggable-module
+
+  Flags:
+    --help, -h      Print this help and exit.
+
+  Programmatic API:
+    import { runProfile, clientProfile, type IScaffoldProfile } from "@gooddata/create-pluggable-module";
+    await runProfile(yourCustomProfile);
+`);
+}
+// Only run the CLI when this file is the entry point (allows library use too).
+// `process.argv[1]` is the script path Node was invoked with — when this file is
+// installed as a bin, that's actually a symlink in node_modules/.bin/ pointing
+// here. Compare the realpath against this module's file URL so symlinked
+// invocation (npx, npm install -g, npm init …) still detects entry-point use.
+function isCliInvocation() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(argv1);
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliInvocation()) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/esm/profiles/__tests__/client.test.d.ts

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

package/esm/profiles/__tests__/client.test.js

@@ -0,0 +1,151 @@
+// (C) 2026 GoodData Corporation
+import { describe, expect, it } from "vitest";
+import { clientProfile } from "../client.js";
+function mockCtx(overrides = {}) {
+    return {
+        answers: { appName: "gdc-mock", title: "Mock", scope: "workspace" },
+        derived: {
+            route: "/mock",
+            federationName: "gdc_mock",
+            remoteUrlEnvVar: "MOCK_REMOTE_URL",
+            devPort: 8500,
+            moduleDevPort: 8600,
+            menuOrder: 100,
+        },
+        repoRoot: "/fake/repo",
+        destRoot: "/fake/repo/modules/gdc-mock",
+        packageManager: "npm",
+        ...overrides,
+    };
+}
+describe("clientProfile", () => {
+    it("declares the expected templateSubtrees in dep-aware order", () => {
+        // harness imports from module → module must build first
+        expect(clientProfile.templateSubtrees).toEqual(["module", "harness"]);
+    });
+    it("does not prefer workspace templates (would leak workspace tsconfig paths to clients)", () => {
+        expect(clientProfile.preferWorkspaceTemplate ?? false).toBe(false);
+    });
+    describe("buildReplacements", () => {
+        const replacements = clientProfile.buildReplacements(mockCtx());
+        const map = Object.fromEntries(replacements);
+        it("substitutes -module and -harness package names BEFORE the bare app name (longer-first ordering)", () => {
+            const keys = replacements.map(([k]) => k);
+            const idxBare = keys.indexOf("gdc-app-template-name");
+            const idxModule = keys.indexOf("gdc-app-template-name-module");
+            expect(idxModule).toBeLessThan(idxBare);
+        });
+        it("provides every template token used in scaffolded files", () => {
+            expect(map["gdc-app-template-name"]).toBe("gdc-mock");
+            expect(map["gdc-app-template-name-module"]).toBe("gdc-mock-module");
+            expect(map["gdc-app-template-name-harness"]).toBe("gdc-mock-harness");
+            expect(map["{applicationTemplateTitle}"]).toBe("Mock");
+            expect(map["{applicationTemplateScope}"]).toBe("workspace");
+            expect(map["{applicationTemplateFederationName}"]).toBe("gdc_mock");
+            expect(map["APP_TEMPLATE_REMOTE_URL"]).toBe("MOCK_REMOTE_URL");
+            expect(map["/app-template-route"]).toBe("/mock");
+            expect(map["{harnessPort}"]).toBe("8500");
+            expect(map["{modulePort}"]).toBe("8600");
+        });
+        it("strips the gdc-ui internal clean-command-state.sh prefix (helper not present in client repos)", () => {
+            expect(map["../../../../common/scripts/clean-command-state.sh && "]).toBe("");
+        });
+        it("does NOT carry the internal workspace-path depth adjustment (only the internal profile owns that)", () => {
+            // The 4→3 depth shift only makes sense inside gdc-ui where `common/`
+            // exists at the repo root. For clients, no depth shift can rescue
+            // the missing helper — strip the call instead (asserted above).
+            expect(map["../../../../common/"]).toBeUndefined();
+        });
+    });
+    describe("resolveDestRoot", () => {
+        it("uses modules/<appName> when destPath is not overridden", () => {
+            const destRoot = clientProfile.resolveDestRoot({ appName: "gdc-x", title: "X", scope: "workspace" }, "/fake/repo");
+            expect(destRoot).toBe("/fake/repo/modules/gdc-x");
+        });
+        it("accepts an in-cwd destPath override", () => {
+            const destRoot = clientProfile.resolveDestRoot({ appName: "gdc-x", title: "X", scope: "workspace", destPath: "apps/gdc-x" }, "/fake/repo");
+            expect(destRoot).toBe("/fake/repo/apps/gdc-x");
+        });
+        it("rejects path-traversal destPath that resolves outside cwd", () => {
+            expect(() => clientProfile.resolveDestRoot({
+                appName: "gdc-x",
+                title: "X",
+                scope: "workspace",
+                destPath: "../../../etc",
+            }, "/fake/repo")).toThrow(/resolves outside the current directory/);
+        });
+        it("rejects an absolute destPath outside cwd", () => {
+            expect(() => clientProfile.resolveDestRoot({
+                appName: "gdc-x",
+                title: "X",
+                scope: "workspace",
+                destPath: "/somewhere/else",
+            }, "/fake/repo")).toThrow(/resolves outside the current directory/);
+        });
+        it("does NOT confuse a cwd-prefix-overlap (e.g. `/fake/repo-other`) as inside cwd", () => {
+            expect(() => clientProfile.resolveDestRoot({
+                appName: "gdc-x",
+                title: "X",
+                scope: "workspace",
+                destPath: "../repo-other/sub",
+            }, "/fake/repo")).toThrow(/resolves outside the current directory/);
+        });
+    });
+    describe("registrations", () => {
+        it("registers in rush.json when target repo IS a Rush monorepo", () => {
+            const steps = clientProfile.registrations({
+                repoRoot: "/tmp",
+                packageManager: "rush",
+            });
+            expect(steps.map((s) => s.file)).toEqual(["rush.json"]);
+        });
+        it("does NOT register anywhere when target repo is not Rush (purely additive scaffold)", () => {
+            const steps = clientProfile.registrations({
+                repoRoot: "/tmp",
+                packageManager: "npm",
+            });
+            expect(steps).toEqual([]);
+        });
+    });
+    describe("transformPackageJson", () => {
+        it("rewrites workspace:* deps to concrete versions", () => {
+            const after = clientProfile.transformPackageJson({
+                dependencies: {
+                    "@gooddata/sdk-ui": "workspace:*",
+                    lodash: "^4.17.23",
+                },
+            }, mockCtx());
+            const deps = after["dependencies"];
+            expect(deps["@gooddata/sdk-ui"]).not.toBe("workspace:*");
+            expect(deps.lodash).toBe("^4.17.23"); // non-workspace deps untouched
+        });
+        it("preserves workspace:* for the just-scaffolded siblings (they have no published version yet)", () => {
+            const after = clientProfile.transformPackageJson({
+                dependencies: {
+                    "gdc-mock-module": "workspace:*",
+                    "gdc-mock-harness": "workspace:*",
+                    "@gooddata/sdk-ui": "workspace:*",
+                },
+            }, mockCtx());
+            const deps = after["dependencies"];
+            // sibling refs stay workspace:* — rush/pnpm/yarn workspaces resolve them locally
+            expect(deps["gdc-mock-module"]).toBe("workspace:*");
+            expect(deps["gdc-mock-harness"]).toBe("workspace:*");
+            // SDK deps still get a concrete version
+            expect(deps["@gooddata/sdk-ui"]).not.toBe("workspace:*");
+        });
+        it("strips _phase:* scripts (Rush-only, would break in non-Rush repos)", () => {
+            const after = clientProfile.transformPackageJson({
+                scripts: {
+                    "_phase:build": "npm run build",
+                    build: "tsc",
+                    test: "vitest",
+                },
+            }, mockCtx());
+            const scripts = after["scripts"];
+            expect(scripts["_phase:build"]).toBeUndefined();
+            expect(scripts.build).toBe("tsc");
+            expect(scripts.test).toBe("vitest");
+        });
+    });
+});

package/esm/profiles/client.d.ts

@@ -0,0 +1,2 @@
+import type { IScaffoldProfile } from "../types.js";
+export declare const clientProfile: IScaffoldProfile;

package/esm/profiles/client.js

@@ -0,0 +1,208 @@
+// (C) 2026 GoodData Corporation
+import { existsSync } from "fs";
+import { join, resolve, sep } from "path";
+import { computeDevPort, computeFederationName, computeRemoteUrlEnvVar, computeRoute, getOwnPackageVersion, } from "../engine/derived.js";
+import { ensureTrailingCommaBeforeAnchor } from "../engine/jsonAnchors.js";
+import { validateTextValue } from "../engine/prompts.js";
+import { installCommand, runCommand } from "../engine/spawn.js";
+const DEST_PATH_KEY = "destPath";
+/**
+ * Rewrites `workspace:*` deps to a concrete semver range based on this
+ * scaffolder's own version. The scaffolder ships locked to the SDK release
+ * train (versionPolicyName: "sdk"), so its version matches the SDK packages
+ * the templates depend on.
+ *
+ * We use a caret range so consumers get patch + minor updates within the SDK
+ * release train; alpha versions get exact pin since semver caret behaves
+ * surprisingly across prerelease boundaries.
+ */
+function buildClientDepVersion() {
+    const ownVersion = getOwnPackageVersion();
+    if (ownVersion.includes("-")) {
+        // Prerelease (alpha/beta/rc) — pin exactly.
+        return ownVersion;
+    }
+    return `^${ownVersion}`;
+}
+/**
+ * Rewrites `workspace:*` deps to a concrete version — except for the
+ * just-scaffolded siblings (the new `<app>-module` / `<app>-harness`), which
+ * stay `workspace:*` because they're brand-new local packages with no
+ * published version. The client repo's package manager resolves them via its
+ * own workspaces feature (Rush, pnpm workspaces, yarn workspaces, etc.).
+ */
+function rewriteWorkspaceDeps(deps, version, siblings) {
+    if (!deps)
+        return deps;
+    const out = {};
+    for (const [name, range] of Object.entries(deps)) {
+        if (range === "workspace:*") {
+            out[name] = siblings.has(name) ? "workspace:*" : version;
+        }
+        else {
+            out[name] = range;
+        }
+    }
+    return out;
+}
+export const clientProfile = {
+    name: "client",
+    extraPrompts: [
+        {
+            key: DEST_PATH_KEY,
+            label: "Destination path (relative to cwd, default ./modules/<name>)",
+            optional: true,
+            validate: validateTextValue,
+        },
+    ],
+    resolveDestRoot(answers, cwd) {
+        const overridden = answers[DEST_PATH_KEY];
+        if (overridden) {
+            const resolved = resolve(cwd, overridden);
+            // Reject path traversal: `..` segments or absolute paths outside cwd.
+            // The text-validation regex blocks shell-injection chars but not `..`,
+            // so a value like "../../etc" would otherwise resolve outside cwd.
+            // `+ sep` prevents prefix-overlap matches (`/proj` vs `/proj-other`).
+            if (resolved !== cwd && !resolved.startsWith(cwd + sep)) {
+                throw new Error(`destPath "${overridden}" resolves outside the current directory (${resolved}). ` +
+                    `Choose a destination inside ${cwd}.`);
+            }
+            return resolved;
+        }
+        return join(cwd, "modules", answers.appName);
+    },
+    templateSubtrees: ["module", "harness"],
+    derive(answers, repo) {
+        const devPort = computeDevPort(repo.repoRoot);
+        return {
+            route: computeRoute(answers.appName),
+            federationName: computeFederationName(answers.appName),
+            remoteUrlEnvVar: computeRemoteUrlEnvVar(answers.appName),
+            devPort,
+            moduleDevPort: devPort + 100,
+            // No host menu to slot into — keep a stable default so scaffolded apps
+            // are still self-consistent and the harness can still read it.
+            menuOrder: 100,
+        };
+    },
+    buildReplacements(ctx) {
+        const { answers, derived } = ctx;
+        // Order matters: longer tokens (containing shorter ones as substring)
+        // MUST come first. `gdc-app-template-module` before `gdc-app-template`.
+        return [
+            ["gdc-app-template-name-module", `${answers.appName}-module`],
+            ["gdc-app-template-name-harness", `${answers.appName}-harness`],
+            ["gdc-app-template-name", answers.appName],
+            ["{applicationTemplateTitle}", answers.title],
+            ["{applicationTemplateScope}", answers.scope],
+            ["{applicationTemplateFederationName}", derived.federationName],
+            ["APP_TEMPLATE_REMOTE_URL", derived.remoteUrlEnvVar],
+            ["/app-template-route", derived.route],
+            ["{harnessPort}", String(derived.devPort)],
+            ["{modulePort}", String(derived.moduleDevPort)],
+            // The template `clean` script prepends a call to gdc-ui's
+            // `common/scripts/clean-command-state.sh` — that helper exists only
+            // inside the gdc-ui monorepo. For client scaffolds, strip the helper
+            // call entirely; the trailing `rm -rf …` cleans the dirs that matter
+            // and is self-contained.
+            ["../../../../common/scripts/clean-command-state.sh && ", ""],
+        ];
+    },
+    transformPackageJson(pkg, ctx) {
+        const version = buildClientDepVersion();
+        // Brand-new sibling packages we just scaffolded — they have no published
+        // version yet, so `workspace:*` must stay for the client repo's
+        // workspace machinery (Rush / pnpm / yarn workspaces) to resolve them.
+        const siblings = new Set([
+            `${ctx.answers.appName}-module`,
+            `${ctx.answers.appName}-harness`,
+        ]);
+        const out = { ...pkg };
+        out.dependencies = rewriteWorkspaceDeps(pkg.dependencies, version, siblings);
+        out.devDependencies = rewriteWorkspaceDeps(pkg.devDependencies, version, siblings);
+        out.peerDependencies = rewriteWorkspaceDeps(pkg.peerDependencies, version, siblings);
+        // Drop _phase:* scripts — those are Rush-specific build phases and would
+        // break npm/yarn/pnpm install in a client repo.
+        if (out.scripts && typeof out.scripts === "object") {
+            const filtered = {};
+            for (const [k, v] of Object.entries(out.scripts)) {
+                if (!k.startsWith("_phase:"))
+                    filtered[k] = v;
+            }
+            out.scripts = filtered;
+        }
+        return out;
+    },
+    registrations(repo) {
+        if (repo.packageManager !== "rush") {
+            // Client repos without a Rush workspace have nothing to register;
+            // the scaffold is purely additive (new files only).
+            return [];
+        }
+        // Inside a Rush workspace, still register in rush.json so `rush update`
+        // picks up the new packages. Doesn't touch the host (none in client repos).
+        return [
+            {
+                file: "rush.json",
+                preInsertTransform: ensureTrailingCommaBeforeAnchor,
+                emit: (ctx) => emitRushJsonEntries(ctx.answers.appName, "    "),
+            },
+        ];
+    },
+    async postCopy(ctx) {
+        const { command, args } = installCommand(ctx.packageManager);
+        console.log(`\n  Running ${command} ${args.join(" ")} ...\n`);
+        const ok = runCommand(command, args, ctx.repoRoot);
+        printClientNextSteps(ctx, command, args, ok);
+    },
+};
+function emitRushJsonEntries(appName, indent) {
+    return [
+        `${indent}{`,
+        `${indent}    "packageName": "${appName}-module",`,
+        `${indent}    "projectFolder": "modules/${appName}/module"`,
+        `${indent}},`,
+        `${indent}{`,
+        `${indent}    "packageName": "${appName}-harness",`,
+        `${indent}    "projectFolder": "modules/${appName}/harness"`,
+        `${indent}},`,
+    ];
+}
+function printClientNextSteps(ctx, installCmd, installArgs, installOk) {
+    const { answers, derived, destRoot, repoRoot } = ctx;
+    const relativeDest = destRoot.startsWith(repoRoot)
+        ? destRoot.slice(repoRoot.length).replace(/^[\\/]/, "")
+        : destRoot;
+    const harnessDir = `${relativeDest}/harness`;
+    const moduleDir = `${relativeDest}/module`;
+    const nextSteps = [];
+    if (!installOk)
+        nextSteps.push(`${installCmd} ${installArgs.join(" ")}`);
+    nextSteps.push(`cd ${harnessDir}`);
+    nextSteps.push("# Local harness dev loop (imports module source directly — no federation):");
+    nextSteps.push("cp .env.template .env   # and fill in TIGER_API_TOKEN");
+    nextSteps.push("npm run dev");
+    nextSteps.push(`# Run the module as a federation remote (rebuild on change + preview at :${derived.moduleDevPort}):`);
+    nextSteps.push(`cd ${moduleDir} && npm run dev`);
+    const numbered = nextSteps.map((step, i) => `    ${i + 1}. ${step}`).join("\n");
+    const header = installOk
+        ? "Done! Your new application has been scaffolded and dependencies installed."
+        : "Your new application has been scaffolded, but the dependency install failed — re-run it before continuing.";
+    console.log(`
+  ${header}
+
+  Next steps:
+${numbered}
+
+  Summary:
+    - ID:              ${answers.appName}
+    - Route:           ${derived.route}
+    - Federation name: ${derived.federationName}
+    - Remote URL env:  ${derived.remoteUrlEnvVar} (set in harness .env to point at a federation preview)
+    - Dev default:     https://localhost:${derived.moduleDevPort}/remoteEntry.js
+`);
+    // Sanity check — print a warning if .env.template doesn't exist where we expect.
+    if (!existsSync(join(destRoot, "harness", ".env.template"))) {
+        console.warn(`  Warning: ${harnessDir}/.env.template not found. Expected one from the template subtree.`);
+    }
+}