@vendure-platform/create 0.2.1 → 0.2.3-nightly.202605260835

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.2.2 (2026-05-22)
+
+### 🚀 Features
+
+- publish CLI publicly with two-token onboarding flow ([#322](https://github.com/vendurehq/vendure-platform/pull/322))
+- Add 'add to existing project' onboarding flow ([#318](https://github.com/vendurehq/vendure-platform/pull/318))
+
 ## 0.2.1 (2026-05-20)
 
 _Initial release._

package/README.md

@@ -23,6 +23,8 @@ npx @vendure-platform/create my-project \
 |------|-------------|---------|
 | `--plugins <list>` | Comma-separated optional plugin keys | (interactive prompt) |
 | `--company <name>` | Company name for branding | (derived from project name) |
+| `--registry-token <token>` | Vendure private-registry npm auth token (baked into `.npmrc`) | (interactive prompt) |
+| `--license-token <token>` | Vendure Platform server-side license token (written to `.env`) | (interactive prompt) |
 | `--no-storefront` | Skip the Next.js storefront | included |
 | `--github` | Create a private GitHub repo via `gh` CLI | no |
 | `--github-org <org>` | GitHub organization for the repo (only used with `--github`) | `vendurehq` |
@@ -32,6 +34,15 @@ npx @vendure-platform/create my-project \
 
 When `--plugins` and `--company` are both provided, the CLI runs in non-interactive mode.
 
+## Tokens: registry vs license
+
+The Vendure Enterprise Portal issues **two distinct tokens** with different purposes — keep them straight:
+
+- **Registry token** — npm auth token for the private registry. Lets `${pm} install` download `@vendure-platform/*` packages. The CLI writes it into the project `.npmrc` as `_authToken`. `.npmrc` is gitignored.
+- **License token** — checked at server boot by the License Guard plugin. The CLI writes it into `.env` as `VENDURE_PLATFORM_LICENSE_TOKEN`.
+
+They are not interchangeable. Pass each via its dedicated flag (`--registry-token`, `--license-token`) or paste each at its own interactive prompt. Either can be skipped (blank input) if you want to add it later.
+
 ## Plugin Tiers
 
 Plugins fall into three tiers (mirroring `@vendure-platform/plugin-meta`):

package/dist/add-to-existing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Options for the `add` subcommand. Mirrors the create CLI's `ScaffoldOptions`
+ * but minimal — we only need the plugin selection. Everything else is derived
+ * from the project we're patching.
+ */
+export interface AddToExistingOptions {
+    /** Directory of the existing Vendure project. Defaults to cwd. */
+    projectDir: string;
+    /** Plugin keys to include (optional/requires-config). Core plugins are always added. */
+    selectedPlugins: string[];
+    /** Print actions without writing files. */
+    dryRun: boolean;
+    /**
+     * Vendure private-registry npm auth token. When supplied, written as
+     * `_authToken` into the project `.npmrc` (literal value) so
+     * `${pm} install` can pull `@vendure-platform/*` packages without any
+     * pre-existing `~/.npmrc` setup. The project `.gitignore` is updated to
+     * ignore `.npmrc` so the literal token never gets committed.
+     *
+     * Distinct from `licenseToken`. When omitted, only the scope mapping is
+     * written and the user is expected to have `~/.npmrc` set up, or to
+     * re-run with `--registry-token` later.
+     */
+    registryToken?: string;
+    /**
+     * Vendure Platform server-side license token. When supplied, written as
+     * `VENDURE_PLATFORM_LICENSE_TOKEN` into `.env` (filling an empty
+     * existing value, never overwriting a non-empty one). Read at boot by
+     * the License Guard plugin.
+     *
+     * Distinct from `registryToken`.
+     */
+    licenseToken?: string;
+}
+interface DetectedProject {
+    projectDir: string;
+    /** Path to `package.json` of the project we'll patch. */
+    packageJsonPath: string;
+    /** Resolved path to `vendure-config.ts`, or `null` if we can't find one. */
+    vendureConfigPath: string | null;
+    /** Whether `@vendure/core` was found in `package.json` dependencies. */
+    hasVendureCore: boolean;
+    /** Resolved path to `.env`, may not exist yet. */
+    envPath: string;
+    /** Resolved path to `.npmrc`, may not exist yet. */
+    npmrcPath: string;
+    /** Resolved path to `.gitignore`, may not exist yet. */
+    gitignorePath: string;
+}
+/**
+ * Detect the layout of an existing Vendure project.
+ *
+ * We look for `@vendure/core` in `package.json` and a `vendure-config.ts` file
+ * somewhere under `src/`. We don't enforce a specific layout — if we can't
+ * find the config we still write the installation guide, just to the root.
+ */
+export declare function detectExistingProject(projectDir: string): Promise<DetectedProject>;
+/**
+ * Apply the safe-to-modify changes:
+ *   1. Add `@vendure-platform/platform` and any selected requires-config
+ *      plugin packages to `package.json` dependencies.
+ *   2. Append missing env vars to `.env` (idempotent — never overwrite values).
+ *   3. Ensure `.npmrc` declares the `@vendure-platform` scope.
+ *   4. Write a `vendure-platform-installation-guide.md` in the project root
+ *      containing the exact import + spread to paste into `vendure-config.ts`.
+ *
+ * Returns a checklist of next steps to print at the end.
+ */
+export declare function applyAddToExisting(detected: DetectedProject, options: AddToExistingOptions): Promise<string[]>;
+export declare function runAddToExistingCli(flags: {
+    plugins?: string;
+    dryRun?: boolean;
+    registryToken?: string;
+    licenseToken?: string;
+}): Promise<AddToExistingOptions>;
+/**
+ * Top-level entry point — wired up from `bin/run.ts`.
+ */
+export declare function addToExisting(options: AddToExistingOptions): Promise<void>;
+export {};

package/dist/add-to-existing.js

@@ -0,0 +1,539 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectExistingProject = detectExistingProject;
+exports.applyAddToExisting = applyAddToExisting;
+exports.runAddToExistingCli = runAddToExistingCli;
+exports.addToExisting = addToExisting;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const p = __importStar(require("@clack/prompts"));
+const plugin_registry_1 = require("./plugin-registry");
+const registry_1 = require("./registry");
+const template_renderer_1 = require("./template-renderer");
+const INSTALLATION_GUIDE_FILENAME = 'vendure-platform-installation-guide.md';
+/**
+ * Detect the layout of an existing Vendure project.
+ *
+ * We look for `@vendure/core` in `package.json` and a `vendure-config.ts` file
+ * somewhere under `src/`. We don't enforce a specific layout — if we can't
+ * find the config we still write the installation guide, just to the root.
+ */
+async function detectExistingProject(projectDir) {
+    var _a, _b;
+    const packageJsonPath = path.join(projectDir, 'package.json');
+    if (!(await fs.pathExists(packageJsonPath))) {
+        throw new Error(`No package.json found at ${packageJsonPath}. Run this from your Vendure project root.`);
+    }
+    const pkg = await fs.readJson(packageJsonPath);
+    const deps = { ...((_a = pkg.dependencies) !== null && _a !== void 0 ? _a : {}), ...((_b = pkg.devDependencies) !== null && _b !== void 0 ? _b : {}) };
+    const hasVendureCore = '@vendure/core' in deps;
+    // Search a few likely locations for vendure-config.ts. Customers vary —
+    // some use src/, some use server/src/. We try the common spots; if we
+    // can't find one we surface that to the user but keep going.
+    const configCandidates = [
+        path.join(projectDir, 'src', 'vendure-config.ts'),
+        path.join(projectDir, 'server', 'src', 'vendure-config.ts'),
+        path.join(projectDir, 'src', 'vendure-config.js'),
+    ];
+    let vendureConfigPath = null;
+    for (const candidate of configCandidates) {
+        if (await fs.pathExists(candidate)) {
+            vendureConfigPath = candidate;
+            break;
+        }
+    }
+    return {
+        projectDir,
+        packageJsonPath,
+        vendureConfigPath,
+        hasVendureCore,
+        envPath: path.join(projectDir, '.env'),
+        npmrcPath: path.join(projectDir, '.npmrc'),
+        gitignorePath: path.join(projectDir, '.gitignore'),
+    };
+}
+/**
+ * Apply the safe-to-modify changes:
+ *   1. Add `@vendure-platform/platform` and any selected requires-config
+ *      plugin packages to `package.json` dependencies.
+ *   2. Append missing env vars to `.env` (idempotent — never overwrite values).
+ *   3. Ensure `.npmrc` declares the `@vendure-platform` scope.
+ *   4. Write a `vendure-platform-installation-guide.md` in the project root
+ *      containing the exact import + spread to paste into `vendure-config.ts`.
+ *
+ * Returns a checklist of next steps to print at the end.
+ */
+async function applyAddToExisting(detected, options) {
+    const { selectedPlugins, dryRun, registryToken, licenseToken } = options;
+    const resolvedKeys = (0, plugin_registry_1.resolveActivePluginKeys)(selectedPlugins);
+    const resolvedPlugins = resolvedKeys.map((k) => (0, plugin_registry_1.getPlugin)(k));
+    const versionSpec = (0, template_renderer_1.resolvePluginVersionSpec)();
+    const checklist = [];
+    // 1. package.json — add `@vendure-platform/platform` AND each resolved
+    //    plugin's package as a direct dep. Listing only `platform` would
+    //    work on npm/bun (which hoist transitives) but break under
+    //    pnpm strict mode, and would also leave the user's snippet
+    //    imports like `import { SqlAnalyticsStrategy } from
+    //    '@vendure-platform/advanced-search'` looking at an undeclared
+    //    dependency. This matches what the fresh-scaffold flow writes.
+    //
+    //    We intentionally do NOT add `@vendure-platform/data-populator`,
+    //    `integration`, or `scenario-default` here — those are
+    //    scaffold-specific (used by the generated populate.ts boot code)
+    //    and irrelevant to an existing project the user is patching.
+    const pluginPackageNames = resolvedPlugins.map((p) => p.packageName);
+    const addedDeps = await patchPackageJson(detected.packageJsonPath, versionSpec, pluginPackageNames, dryRun);
+    if (addedDeps.length > 0) {
+        const summary = addedDeps.length === 1
+            ? addedDeps[0]
+            : `${addedDeps.length} packages (${addedDeps[0]}, …)`;
+        checklist.push(`Added ${summary} at ${versionSpec} to package.json — run \`npm install\` (or your package manager equivalent).`);
+    }
+    // 2. .env — append missing env vars from selected plugins. If we have a
+    //    license token, seed it as the default value for VENDURE_PLATFORM_LICENSE_TOKEN
+    //    so the user doesn't have to paste it twice.
+    const envAdditions = collectEnvAdditions(resolvedPlugins, licenseToken);
+    const appendedCount = await appendMissingEnvVars(detected.envPath, envAdditions, dryRun);
+    if (appendedCount > 0) {
+        checklist.push(`Appended ${appendedCount} env var(s) to .env — fill in real values before booting.`);
+    }
+    // 2a. Recovery path: if the user previously ran `create add` without a
+    //     token (leaving `VENDURE_PLATFORM_LICENSE_TOKEN=` empty in .env)
+    //     and is now re-running with a token, fill that empty value in.
+    //     Never overwrite a non-empty value — that's still the user's
+    //     intentional setting.
+    if (licenseToken) {
+        const filled = await fillEmptyLicenseTokenInEnv(detected.envPath, licenseToken, dryRun);
+        if (filled) {
+            checklist.push(`Filled in the empty VENDURE_PLATFORM_LICENSE_TOKEN value in .env.`);
+        }
+    }
+    // 3. .npmrc — declare the @vendure-platform scope, and (if a registry
+    //    token was provided) the `_authToken` line so `${pm} install` works
+    //    without any `~/.npmrc` setup. The token is the literal value, not
+    //    env-var indirection — npm cannot read `.env` during install, so
+    //    indirection would only work when the user manually exports the env
+    //    var. The project `.gitignore` is updated below to keep this file
+    //    untracked.
+    const npmrcResult = await ensureNpmrcScopeAndAuth(detected.npmrcPath, registryToken, dryRun);
+    if (npmrcResult.scopeAdded || npmrcResult.authAdded) {
+        const bits = [];
+        if (npmrcResult.scopeAdded)
+            bits.push('scope');
+        if (npmrcResult.authAdded)
+            bits.push('auth token');
+        checklist.push(`Updated .npmrc (${bits.join(' + ')}).`);
+    }
+    // 3a. .gitignore — make sure .npmrc never gets committed. We do this
+    //     unconditionally (even without a token) so future runs that add a
+    //     token to the existing scope-only .npmrc don't accidentally commit
+    //     it. Without a token in play the entry is harmless either way.
+    const gitignoreAdded = await ensureGitignoreEntry(detected.gitignorePath, '.npmrc', dryRun);
+    if (gitignoreAdded) {
+        checklist.push(`Added .npmrc to .gitignore so any future registry token never gets committed.`);
+    }
+    // 4. vendure-platform-installation-guide.md — generate paste-in
+    //    instructions. Always written to the project root (not next to the
+    //    config) so it's easy to find regardless of project layout.
+    const guide = renderInstallationGuide(resolvedPlugins, resolvedKeys);
+    const guidePath = path.join(detected.projectDir, INSTALLATION_GUIDE_FILENAME);
+    if (!dryRun) {
+        await fs.writeFile(guidePath, guide);
+    }
+    checklist.push(`Wrote ${path.relative(detected.projectDir, guidePath)} — follow it to wire up your vendure-config.ts.`);
+    // 5. Downstream reminders (not automated)
+    // Bootstrap-import swap is the gate: without it, every platform plugin fails
+    // at startup with LICENSE_GUARD_NONCE_MISMATCH. Surface it as its own line so
+    // it can't be missed by anyone who only skims the next-steps printout.
+    checklist.push(`Swap \`import { bootstrap } from '@vendure/core'\` for \`'@vendure-platform/platform'\` in your server entry file (and \`bootstrapWorker\` if you have a worker). See the installation guide's "Bootstrap import" section.`);
+    checklist.push('Generate and run a migration for the new platform entities.');
+    checklist.push('Rebuild the dashboard if you serve a pre-built artefact.');
+    checklist.push('Grant new permissions to existing admin roles via Settings → Roles.');
+    return checklist;
+}
+/**
+ * Add `@vendure-platform/platform` plus each resolved plugin package to
+ * `package.json` dependencies (idempotent — already-present packages are
+ * left at their existing version, never downgraded). Returns the list of
+ * packages we actually added so the caller can report a useful checklist
+ * line and skip the message entirely when nothing changed.
+ */
+async function patchPackageJson(packageJsonPath, versionSpec, pluginPackageNames, dryRun) {
+    var _a;
+    const pkg = await fs.readJson(packageJsonPath);
+    (_a = pkg.dependencies) !== null && _a !== void 0 ? _a : (pkg.dependencies = {});
+    // Sort so the checklist message is deterministic and the platform
+    // meta-package always lands first (it's the "headline" dep).
+    const allPackages = ['@vendure-platform/platform', ...pluginPackageNames]
+        .filter((name, i, arr) => arr.indexOf(name) === i);
+    const added = [];
+    for (const name of allPackages) {
+        if (!pkg.dependencies[name]) {
+            pkg.dependencies[name] = versionSpec;
+            added.push(name);
+        }
+    }
+    if (added.length > 0 && !dryRun) {
+        await fs.writeJson(packageJsonPath, pkg, { spaces: 2 });
+    }
+    return added;
+}
+function collectEnvAdditions(plugins, licenseToken) {
+    // Always include the license guard vars even if the plugin isn't selected
+    // — they're required for boot.
+    const additions = [
+        { name: 'VENDURE_PLATFORM_LICENSE_TOKEN', defaultValue: licenseToken !== null && licenseToken !== void 0 ? licenseToken : '' },
+        { name: 'VENDURE_PLATFORM_LICENSE_GUARD_LOCAL_DEV', defaultValue: '1' },
+    ];
+    for (const pl of plugins) {
+        for (const v of pl.envVars) {
+            if (!additions.some((a) => a.name === v.name)) {
+                additions.push(v);
+            }
+        }
+    }
+    return additions;
+}
+/**
+ * Find a `VENDURE_PLATFORM_LICENSE_TOKEN=` line with an empty value and
+ * fill it in with `token`. Used to recover from a previous `create add` run
+ * that didn't have a token to hand.
+ *
+ *   - `VENDURE_PLATFORM_LICENSE_TOKEN=`           → updated to `=<token>`
+ *   - `VENDURE_PLATFORM_LICENSE_TOKEN=preexisting`→ left alone
+ *   - `# VENDURE_PLATFORM_LICENSE_TOKEN=`         → left alone (commented out)
+ *
+ * Returns `true` if the file was modified.
+ */
+async function fillEmptyLicenseTokenInEnv(envPath, token, dryRun) {
+    if (!(await fs.pathExists(envPath)))
+        return false;
+    const existing = await fs.readFile(envPath, 'utf8');
+    const lines = existing.split('\n');
+    let modified = false;
+    const TOKEN_KEY = 'VENDURE_PLATFORM_LICENSE_TOKEN';
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith('#'))
+            continue;
+        if (trimmed === `${TOKEN_KEY}=`) {
+            lines[i] = `${TOKEN_KEY}=${token}`;
+            modified = true;
+            // Only fill the first occurrence — dotenv reads top-down and any
+            // subsequent line would be a duplicate the user authored deliberately.
+            break;
+        }
+    }
+    if (modified && !dryRun) {
+        await fs.writeFile(envPath, lines.join('\n'));
+    }
+    return modified;
+}
+/**
+ * Append any env vars from `additions` that aren't already declared in
+ * `.env`. Idempotent — never overwrites or duplicates an existing key.
+ * Returns the count of keys actually appended, so callers can decide
+ * whether to surface a "we did something" message.
+ */
+async function appendMissingEnvVars(envPath, additions, dryRun) {
+    let existing = '';
+    if (await fs.pathExists(envPath)) {
+        existing = await fs.readFile(envPath, 'utf8');
+    }
+    const existingKeys = new Set(existing
+        .split('\n')
+        .map((line) => { var _a; return (_a = line.split('=')[0]) === null || _a === void 0 ? void 0 : _a.trim(); })
+        .filter((k) => Boolean(k) && !k.startsWith('#')));
+    const toAdd = additions.filter((a) => !existingKeys.has(a.name));
+    if (toAdd.length === 0)
+        return 0;
+    const header = '\n# Added by @vendure-platform/create add\n';
+    const block = toAdd.map((a) => `${a.name}=${a.defaultValue}`).join('\n') + '\n';
+    if (!dryRun) {
+        const trailing = existing.endsWith('\n') || existing === '' ? '' : '\n';
+        await fs.writeFile(envPath, existing + trailing + header + block);
+    }
+    return toAdd.length;
+}
+/**
+ * Ensure the project-level `.npmrc` declares both the `@vendure-platform`
+ * scope and (when a registry token is supplied) a registry-scoped
+ * `_authToken` line. The registry token is the npm auth token from the
+ * Enterprise Portal — distinct from the server-side license token, which
+ * lives in `.env` and is handled by the env-writing path.
+ *
+ * The auth line uses the **literal token value**, not env-var indirection.
+ * npm reads `.npmrc` at install time and only resolves `${VAR}` against the
+ * process environment — it doesn't load `.env` files. Env-var indirection
+ * would therefore only work when the user has manually exported the var,
+ * which defeats the point of bundling the token at scaffold time. Project
+ * `.gitignore` is updated separately to keep this file untracked.
+ *
+ * Idempotent: lines that already exist are left alone.
+ */
+async function ensureNpmrcScopeAndAuth(npmrcPath, registryToken, dryRun) {
+    const registryUrl = (0, registry_1.getRegistryUrl)();
+    const registryHost = (0, registry_1.getRegistryHostname)();
+    const scopeLine = `@vendure-platform:registry=${registryUrl}`;
+    // `npm login` writes the auth-token line with a leading `//` and a
+    // trailing slash before `:_authToken`. We match that convention so a
+    // subsequent `npm login` / `npm logout` rewrite cleanly.
+    const authLineKey = `//${registryHost}/:_authToken=`;
+    let existing = '';
+    if (await fs.pathExists(npmrcPath)) {
+        existing = await fs.readFile(npmrcPath, 'utf8');
+    }
+    const hasScope = existing.includes('@vendure-platform:registry=');
+    const hasAuth = existing.includes(authLineKey);
+    const linesToAdd = [];
+    if (!hasScope)
+        linesToAdd.push(scopeLine);
+    if (registryToken && !hasAuth)
+        linesToAdd.push(`${authLineKey}${registryToken}`);
+    if (linesToAdd.length === 0) {
+        return { scopeAdded: false, authAdded: false };
+    }
+    const trailing = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    if (!dryRun) {
+        await fs.writeFile(npmrcPath, existing + trailing + linesToAdd.join('\n') + '\n');
+    }
+    return {
+        scopeAdded: !hasScope,
+        authAdded: Boolean(registryToken) && !hasAuth,
+    };
+}
+/**
+ * Ensure `entry` appears as its own line in `.gitignore`. Skips if the entry
+ * (or a less-specific glob that would match it) is already present. Creates
+ * the file when missing.
+ */
+async function ensureGitignoreEntry(gitignorePath, entry, dryRun) {
+    let existing = '';
+    if (await fs.pathExists(gitignorePath)) {
+        existing = await fs.readFile(gitignorePath, 'utf8');
+    }
+    const lines = existing.split('\n').map((l) => l.trim());
+    if (lines.includes(entry) || lines.includes(`/${entry}`)) {
+        return false;
+    }
+    const trailing = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    if (!dryRun) {
+        await fs.writeFile(gitignorePath, existing + trailing + entry + '\n');
+    }
+    return true;
+}
+function renderInstallationGuide(plugins, resolvedKeys) {
+    const imports = [`import { VendurePlatform } from '@vendure-platform/platform';`];
+    const optionsBlocks = [];
+    for (const pl of plugins) {
+        if (pl.platformImports)
+            imports.push(...pl.platformImports);
+        if (pl.platformOptionsBlock) {
+            optionsBlocks.push(`            ${pl.platformOptionsBlock},`);
+        }
+    }
+    // Plugins that are optional but the user didn't pick → emit `key: false`
+    const disabledKeys = plugin_registry_1.pluginRegistry
+        .filter((pl) => pl.tier === 'optional' && !resolvedKeys.includes(pl.key))
+        .map((pl) => pl.key);
+    for (const key of disabledKeys) {
+        const platformKey = (0, plugin_registry_1.getPlugin)(key).platformKey;
+        optionsBlocks.push(`            ${platformKey}: false,`);
+    }
+    const importsText = imports.join('\n');
+    const optionsText = optionsBlocks.length === 0
+        ? '            // All optional plugins enabled with default config'
+        : optionsBlocks.join('\n');
+    return `# Vendure Platform installation guide
+
+Paste these changes into your existing project. Step 1 is the most important —
+without it, every Vendure Platform plugin refuses to start with
+\`LICENSE_GUARD_NONCE_MISMATCH\`.
+
+## 1. Bootstrap import (server entry point)
+
+In your server entry file (typically \`src/index.ts\` or wherever you call
+\`bootstrap()\`), swap the bootstrap import from \`@vendure/core\` to
+\`@vendure-platform/platform\`:
+
+\`\`\`ts
+// before
+import { bootstrap } from '@vendure/core';
+
+// after
+import { bootstrap } from '@vendure-platform/platform';
+\`\`\`
+
+If you also run a separate worker process, swap \`bootstrapWorker\` too:
+
+\`\`\`ts
+import { bootstrapWorker } from '@vendure-platform/platform';
+\`\`\`
+
+The \`@vendure-platform/platform\` bootstrap is a drop-in wrapper around
+\`@vendure/core\`'s \`bootstrap\` that primes the runtime license guard before
+Nest builds the DI container. Without this swap, plugins like \`OrgHierarchyPlugin\`
+fail at startup with \`LICENSE_GUARD_NONCE_MISMATCH\`.
+
+## 2. Imports in vendure-config.ts
+
+Add to the top of the file (after your existing imports):
+
+\`\`\`ts
+${importsText}
+\`\`\`
+
+## 3. Plugins array
+
+Spread \`VendurePlatform.init({...})\` into the \`plugins\` array — typically
+between \`DefaultJobQueuePlugin\` and \`DashboardPlugin\`:
+
+\`\`\`ts
+...VendurePlatform.init({
+${optionsText}
+}),
+\`\`\`
+
+## 4. Order process
+
+If \`approvalWorkflows\` is enabled (default), VendurePlatform will append
+\`approvalOrderProcess\` to your order process chain and override
+\`arrangingPaymentRequiresContents\` and \`checkAllItemsBeforeCancel\`. If you
+have custom order process handlers they are preserved; the flags above are
+not.
+
+See https://docs.vendure.io/current/platform/getting-started/introduction for the full reference.
+`;
+}
+async function runAddToExistingCli(flags) {
+    var _a;
+    const projectDir = process.cwd();
+    const detected = await detectExistingProject(projectDir);
+    if (!detected.hasVendureCore) {
+        p.log.warn('No @vendure/core dependency found in package.json. Continuing anyway — make sure this is the right directory.');
+    }
+    if (!detected.vendureConfigPath) {
+        p.log.warn('No vendure-config.ts found under src/ or server/src/. The installation guide will still be written to the project root.');
+    }
+    else {
+        p.log.info(`Detected vendure-config.ts at ${path.relative(projectDir, detected.vendureConfigPath)}`);
+    }
+    const hasIntro = flags.plugins === undefined ||
+        flags.registryToken === undefined ||
+        flags.licenseToken === undefined;
+    if (hasIntro) {
+        p.intro('Add Vendure Platform to existing project');
+    }
+    let selectedPlugins;
+    if (flags.plugins !== undefined) {
+        selectedPlugins = flags.plugins
+            .split(',')
+            .map((k) => k.trim())
+            .filter(Boolean);
+    }
+    else {
+        const pluginOptions = plugin_registry_1.pluginRegistry
+            .filter((pl) => pl.tier === 'optional' || pl.tier === 'requires-config')
+            .sort((a, b) => {
+            if (a.category !== b.category)
+                return a.category.localeCompare(b.category);
+            return a.displayName.localeCompare(b.displayName);
+        })
+            .map((pl) => ({
+            label: `${pl.displayName} (${pl.category})`,
+            value: pl.key,
+            hint: pl.tier === 'requires-config' ? 'needs configuration' : undefined,
+        }));
+        const initialValues = plugin_registry_1.pluginRegistry.filter((pl) => pl.tier === 'optional').map((pl) => pl.key);
+        const answer = await p.multiselect({
+            message: 'Optional plugins to include (core plugins are always installed):',
+            options: pluginOptions,
+            initialValues,
+            required: false,
+        });
+        if (typeof answer === 'symbol') {
+            p.cancel('Cancelled.');
+            process.exit(0);
+        }
+        selectedPlugins = answer;
+    }
+    // Two separate prompts: registry token (for .npmrc — needed by `${pm}
+    // install`) and license token (for .env — read at server boot). The
+    // Enterprise Portal issues these as two distinct values with different
+    // rotation policies, so we never collapse them.
+    const registryToken = await promptForOptionalToken(flags.registryToken, 'Vendure private-registry npm auth token (from https://enterprise.vendure.io). Used by your package manager (npm/bun/pnpm) at install time. Leave blank to skip:');
+    const licenseToken = await promptForOptionalToken(flags.licenseToken, 'Vendure Platform license token (server-side, written to .env). Leave blank to skip:');
+    return {
+        projectDir,
+        selectedPlugins,
+        dryRun: (_a = flags.dryRun) !== null && _a !== void 0 ? _a : false,
+        registryToken,
+        licenseToken,
+    };
+}
+/**
+ * Pre-resolve from a flag if given, otherwise interactively prompt with a
+ * masked password input. Empty / whitespace-only answers normalise to
+ * `undefined` so downstream "if a token was supplied" checks read cleanly.
+ */
+async function promptForOptionalToken(flagValue, message) {
+    const fromFlag = flagValue === null || flagValue === void 0 ? void 0 : flagValue.trim();
+    if (fromFlag !== undefined) {
+        return fromFlag === '' ? undefined : fromFlag;
+    }
+    const answer = await p.password({ message });
+    if (typeof answer === 'symbol') {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    const trimmed = answer.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Top-level entry point — wired up from `bin/run.ts`.
+ */
+async function addToExisting(options) {
+    const detected = await detectExistingProject(options.projectDir);
+    const alwaysOn = plugin_registry_1.ALWAYS_ACTIVE_KEYS.map((k) => (0, plugin_registry_1.getPlugin)(k).displayName);
+    if (alwaysOn.length > 0) {
+        p.log.info(`Always-on core plugins: ${alwaysOn.join(', ')}`);
+    }
+    const checklist = await applyAddToExisting(detected, options);
+    const numbered = checklist.map((line, i) => `${i + 1}. ${line}`).join('\n');
+    p.note(numbered, options.dryRun ? 'Dry run — would do:' : 'Next steps');
+    p.outro(options.dryRun ? 'Dry run complete — no files written.' : 'Done.');
+}
+//# sourceMappingURL=add-to-existing.js.map