@sonarsource/marketing-cli 1.0.0

package/dist/commands/environment.js

@@ -0,0 +1,454 @@
+import { confirm, select, spinner } from '@clack/prompts';
+import { join } from 'node:path';
+import { detectBranch } from '../branch.js';
+import { PROTECTED_BRANCHES } from '../branches.js';
+import { isCI, resolveManagementKey } from '../ci.js';
+import { loadConfig, updateConfig } from '../config.js';
+import { assertNotCancelled, CliError } from '../errors.js';
+import { createKontentClient } from '../kontent.js';
+import { fetchBranchVars, resolveNetlifyToken } from '../netlify.js';
+import { loadStatusJson, writeStatusJson } from '../status.js';
+import { migrationRun } from './migration.js';
+import { setup } from './setup.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Slugify a branch name for use as the Kontent clone name.
+ * Non-alphanumeric characters (except `-`) → `-`, consecutive `-` collapsed,
+ * leading/trailing `-` trimmed.
+ */
+export function slugifyBranch(branch) {
+    return branch
+        .replace(/[^a-zA-Z0-9-]/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+/, '')
+        .replace(/-+$/, '');
+}
+/**
+ * Source resolution — deterministic from the `longLivedBranches` config tree.
+ *
+ * 1. If branch is a child of a key → parent's `environmentId`
+ * 2. If branch is a key (not a child of another key) → production
+ * 3. Not in config at all → production
+ */
+export function resolveSourceEnvironment(branch, config) {
+    const llb = config.kontent.longLivedBranches;
+    for (const [parentBranch, entry] of Object.entries(llb)) {
+        if (entry.children.includes(branch)) {
+            if (!entry.environmentId) {
+                throw new CliError(`Parent branch "${parentBranch}" has no environment. ` +
+                    `Run \`marketing environment create\` on "${parentBranch}" first.`);
+            }
+            return {
+                environmentId: entry.environmentId,
+                isProduction: false,
+                sourceBranch: parentBranch,
+            };
+        }
+    }
+    return {
+        environmentId: config.kontent.productionEnvironmentId,
+        isProduction: true,
+    };
+}
+/**
+ * Resolve the source environment for `environment create`.
+ *
+ * 1. `--source <branch>` → look up in longLivedBranches, hard-error if
+ *    not found or no active environmentId.
+ * 2. No `--source`, ≥1 long-lived branch with active env → interactive
+ *    selector (production is always an option).
+ * 3. No `--source`, no active long-lived branches → production.
+ */
+async function resolveSource(branch, config, opts) {
+    const llb = config.kontent.longLivedBranches;
+    if (opts.source) {
+        if (opts.source === branch) {
+            throw new CliError(`Cannot use "${branch}" as its own source environment.`);
+        }
+        const entry = llb[opts.source];
+        if (!entry) {
+            throw new CliError(`Branch "${opts.source}" is not declared in longLivedBranches. ` +
+                `Available long-lived branches: ${Object.keys(llb).join(', ') || '(none)'}.`);
+        }
+        if (!entry.environmentId) {
+            throw new CliError(`Branch "${opts.source}" has no active environment. ` +
+                `Run \`marketing environment create\` on "${opts.source}" first.`);
+        }
+        return { environmentId: entry.environmentId, isProduction: false, sourceBranch: opts.source };
+    }
+    // Collect long-lived branches with active environments (excluding the current branch)
+    const activeLLBs = Object.entries(llb).filter(([name, entry]) => name !== branch && Boolean(entry.environmentId));
+    if (activeLLBs.length > 0 && !opts.yes) {
+        const PRODUCTION_VALUE = '__production__';
+        const selected = assertNotCancelled(await select({
+            message: 'Select source environment:',
+            options: [
+                { value: PRODUCTION_VALUE, label: 'Production' },
+                ...activeLLBs.map(([name]) => ({ value: name, label: name })),
+            ],
+        }));
+        if (selected !== PRODUCTION_VALUE) {
+            return {
+                environmentId: llb[selected].environmentId,
+                isProduction: false,
+                sourceBranch: selected,
+            };
+        }
+        // Explicit production choice — bypass tree lookup
+        return {
+            environmentId: config.kontent.productionEnvironmentId,
+            isProduction: true,
+        };
+    }
+    return resolveSourceEnvironment(branch, config);
+}
+/**
+ * Human-readable label for a resolved source — `"production"` or the
+ * source branch name. Falls back to the raw environment ID when neither
+ * is available (shouldn't happen in practice).
+ */
+function sourceLabel(source) {
+    if (source.isProduction)
+        return 'production';
+    return source.sourceBranch ?? source.environmentId;
+}
+function requireBranch(opts) {
+    const branch = detectBranch(opts);
+    if (!branch) {
+        throw new CliError('Could not detect the current branch. Pass --branch <name>.');
+    }
+    return branch;
+}
+function guardProtectedBranch(branch) {
+    if (PROTECTED_BRANCHES.includes(branch)) {
+        throw new CliError(`Refusing to operate on protected branch "${branch}". ` + `Switch to a feature branch.`);
+    }
+}
+function requireTTY(yes) {
+    if (!yes && !process.stdin.isTTY) {
+        throw new CliError('No interactive terminal detected. Pass --yes to skip confirmation, ' +
+            'or run in an interactive shell.');
+    }
+}
+// ---------------------------------------------------------------------------
+// environment create
+// ---------------------------------------------------------------------------
+export async function environmentCreate(opts) {
+    const cwd = process.cwd();
+    const config = loadConfig(cwd);
+    const branch = requireBranch(opts);
+    guardProtectedBranch(branch);
+    requireTTY(opts.yes);
+    const token = resolveNetlifyToken();
+    const previewSiteId = config.netlify.previewSiteId;
+    // --- Resolve management key ---
+    const ci = isCI(opts);
+    const envFilePath = join(cwd, '.env.development');
+    const apiKey = resolveManagementKey({
+        ci,
+        netlifyValue: undefined,
+        envFilePath,
+        managementKeyName: config.envVars.managementKey,
+    });
+    // --- Fetch branch vars (single GET, reused throughout) ---
+    const branchVars = await fetchBranchVars(token, previewSiteId);
+    // --- Check for existing branch env var ---
+    const hasExisting = branchVars.has(config.envVars.environmentId, branch);
+    if (hasExisting) {
+        if (opts.yes) {
+            console.log(`Branch "${branch}" already has an environment — keeping existing (--yes).`);
+            return;
+        }
+        const action = assertNotCancelled(await confirm({
+            message: `Branch "${branch}" already has a branch-scoped environment on Netlify. Keep it?`,
+        }));
+        if (action === true) {
+            console.log('Keeping existing environment.');
+            return;
+        }
+        // --- Block if stack branch has children with active environments ---
+        guardActiveChildren(branch, 'recreate', config, branchVars);
+        // Recreate: tear down old environment
+        console.log('Recreating — removing old environment...');
+        // Resolve old clone ID before deleting the Netlify var (delete drops it from cache)
+        const oldResolved = branchVars.resolve(config.envVars.environmentId, branch);
+        const oldCloneEnvId = oldResolved?.isBranchSpecific ? oldResolved.value : undefined;
+        // Delete old Netlify branch var
+        await branchVars.delete(config.envVars.environmentId, branch);
+        // Delete old Kontent environment
+        if (oldCloneEnvId) {
+            try {
+                const oldClient = createKontentClient(oldCloneEnvId, apiKey);
+                await oldClient.deleteEnvironment().toPromise();
+                console.log(`Deleted old Kontent environment (${oldCloneEnvId}).`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`Warning: could not delete old Kontent environment (${oldCloneEnvId}): ${msg}`);
+                console.warn('Continuing with recreation — the old environment may need manual cleanup.');
+            }
+        }
+        // Clean up status.json for the old clone
+        if (oldCloneEnvId) {
+            const status = loadStatusJson(cwd);
+            delete status[oldCloneEnvId];
+            writeStatusJson(cwd, status);
+        }
+        // Remove config entry if applicable
+        const llb = config.kontent.longLivedBranches;
+        if (llb[branch]?.environmentId) {
+            delete llb[branch].environmentId;
+            updateConfig(config, cwd);
+        }
+    }
+    // --- Resolve source (--source flag or selector or default) ---
+    const source = await resolveSource(branch, config, opts);
+    // --- Pre-validate credentials on source env ---
+    console.log('Validating credentials on source environment...');
+    const sourceClient = createKontentClient(source.environmentId, apiKey);
+    await sourceClient.environmentInformation().toPromise();
+    console.log('Credentials valid.');
+    // --- Determine if this is a long-lived branch ---
+    const llb = config.kontent.longLivedBranches;
+    const isLongLived = opts.stack || llb[branch] !== undefined;
+    if (opts.stack && llb[branch] === undefined) {
+        llb[branch] = { children: [] };
+    }
+    // --- Clone the environment ---
+    const cloneName = slugifyBranch(branch);
+    console.log(`Cloning "${sourceLabel(source)}" (${source.environmentId}) as "${cloneName}"...`);
+    const cloneResponse = await sourceClient
+        .cloneEnvironment()
+        .withData({
+        name: cloneName,
+        roles_to_activate: config.kontent.roles,
+    })
+        .toPromise();
+    const cloneEnvId = cloneResponse.data.id;
+    console.log(`Clone initiated: ${cloneEnvId}`);
+    // --- Poll until cloning completes ---
+    const s = spinner();
+    s.start('Waiting for clone to complete...');
+    const cloneClient = createKontentClient(cloneEnvId, apiKey);
+    const startTime = Date.now();
+    let lastLogTime = startTime;
+    let consecutiveFailures = 0;
+    while (true) {
+        await delay(2000);
+        let stateResponse;
+        try {
+            stateResponse = await cloneClient.getEnvironmentCloningState().toPromise();
+            consecutiveFailures = 0;
+        }
+        catch (err) {
+            if (isAuthError(err)) {
+                throw err;
+            }
+            consecutiveFailures++;
+            const backoff = Math.min(2000 * 2 ** (consecutiveFailures - 1), 30_000);
+            s.message(`Poll error (${consecutiveFailures} consecutive), ` + `retrying in ${backoff / 1000}s...`);
+            await delay(backoff);
+            continue;
+        }
+        const state = stateResponse.data.cloningInfo.cloningState;
+        if (state === 'done') {
+            break;
+        }
+        if (state === 'failed') {
+            s.stop('Clone failed.');
+            throw new CliError(`Cloning failed for environment "${cloneEnvId}". Check the Kontent dashboard.`);
+        }
+        const now = Date.now();
+        if (now - lastLogTime >= 30_000) {
+            const elapsed = Math.round((now - startTime) / 1000);
+            s.message(`Still cloning... (${elapsed}s elapsed)`);
+            lastLogTime = now;
+        }
+    }
+    s.stop('Clone complete.');
+    // --- Push env ID to Netlify branch context ---
+    await branchVars.set(config.envVars.environmentId, branch, cloneEnvId);
+    console.log(`Set branch env var on Netlify preview site.`);
+    // --- Seed status.json ---
+    const status = loadStatusJson(cwd);
+    const sourceStatus = status[source.environmentId];
+    if (Array.isArray(sourceStatus)) {
+        status[cloneEnvId] = [...sourceStatus];
+    }
+    else {
+        status[cloneEnvId] = [];
+    }
+    writeStatusJson(cwd, status);
+    console.log('Seeded Migrations/status.json.');
+    // --- Update config: long-lived branch state + children ---
+    // Clean up stale children entries (e.g. branch was previously under a
+    // different parent, or user explicitly chose production)
+    let configDirty = removeBranchFromAllChildren(llb, branch);
+    if (isLongLived) {
+        llb[branch].environmentId = cloneEnvId;
+        configDirty = true;
+    }
+    if (source.sourceBranch) {
+        llb[source.sourceBranch].children.push(branch);
+        configDirty = true;
+    }
+    if (configDirty) {
+        updateConfig(config, cwd);
+        console.log('Updated marketing.config.json.');
+    }
+    // --- Re-run setup ---
+    await setup({ branch: opts.branch, ci: opts.ci });
+    console.log('Re-ran setup.');
+    // --- Run migrations ---
+    await migrationRun({ branch: opts.branch, ci: opts.ci, yes: true });
+    console.log('Migrations complete.');
+    console.log(`\nEnvironment "${branch}" (${cloneEnvId}) is ready.`);
+}
+// ---------------------------------------------------------------------------
+// environment finish
+// ---------------------------------------------------------------------------
+export async function environmentFinish(opts) {
+    const cwd = process.cwd();
+    const config = loadConfig(cwd);
+    const branch = requireBranch(opts);
+    guardProtectedBranch(branch);
+    requireTTY(opts.yes);
+    const token = resolveNetlifyToken();
+    const previewSiteId = config.netlify.previewSiteId;
+    // --- Fetch branch vars (single GET, reused throughout) ---
+    const branchVars = await fetchBranchVars(token, previewSiteId);
+    // --- Resolve clone env ID from cache ---
+    const resolved = branchVars.resolve(config.envVars.environmentId, branch);
+    if (!resolved?.isBranchSpecific) {
+        throw new CliError(`No branch-scoped environment found for "${branch}". ` +
+            `Run \`marketing environment create\` first.`);
+    }
+    const cloneEnvId = resolved.value;
+    // --- Resolve source ---
+    const source = resolveSourceEnvironment(branch, config);
+    const llb = config.kontent.longLivedBranches;
+    const isLongLived = llb[branch] !== undefined;
+    // --- Block if long-lived and children have active envs ---
+    if (isLongLived) {
+        guardActiveChildren(branch, 'finish', config, branchVars);
+    }
+    // --- Confirmation ---
+    if (!opts.yes) {
+        const confirmed = assertNotCancelled(await confirm({
+            message: `Finish environment for branch "${branch}"?\n` +
+                `  • Migrate source "${sourceLabel(source)}"\n` +
+                `  • Delete clone "${branch}"\n` +
+                `  • Remove Netlify branch var`,
+        }));
+        if (confirmed !== true) {
+            throw new CliError('Aborted by user.');
+        }
+    }
+    // --- Resolve management key ---
+    const ci = isCI(opts);
+    const envFilePath = join(cwd, '.env.development');
+    const apiKey = resolveManagementKey({
+        ci,
+        netlifyValue: undefined,
+        envFilePath,
+        managementKeyName: config.envVars.managementKey,
+    });
+    // --- Migrate source environment ---
+    console.log(`Running migrations on "${sourceLabel(source)}" (${source.environmentId})...`);
+    await migrationRun({
+        environmentId: source.environmentId,
+        allowProduction: source.isProduction,
+        yes: true,
+        branch: opts.branch,
+        ci: opts.ci,
+    });
+    console.log('Source migrations complete.');
+    // --- Delete clone ---
+    console.log(`Deleting clone "${branch}" (${cloneEnvId})...`);
+    const cloneClient = createKontentClient(cloneEnvId, apiKey);
+    await cloneClient.deleteEnvironment().toPromise();
+    console.log('Clone deleted.');
+    // --- Delete Netlify branch var ---
+    await branchVars.delete(config.envVars.environmentId, branch);
+    console.log('Removed Netlify branch env var.');
+    // --- Clean up status.json ---
+    const status = loadStatusJson(cwd);
+    delete status[cloneEnvId];
+    writeStatusJson(cwd, status);
+    console.log('Cleaned up Migrations/status.json.');
+    // --- Auto-remove branch from parent's children ---
+    let configDirty = removeBranchFromAllChildren(llb, branch);
+    // --- Clean up config for long-lived branches ---
+    if (isLongLived) {
+        delete llb[branch];
+        configDirty = true;
+    }
+    if (configDirty) {
+        updateConfig(config, cwd);
+        console.log('Updated marketing.config.json.');
+    }
+    // --- Re-run setup ---
+    await setup({ branch: opts.branch, ci: opts.ci });
+    console.log('Re-ran setup.');
+    console.log(`\nEnvironment finished for branch "${branch}".`);
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+/**
+ * Remove `branch` from every parent's `children` array in the long-lived
+ * branches config. Returns `true` if any entry was modified.
+ */
+/**
+ * Throw if `branch` is a long-lived branch whose children still have active
+ * Netlify environments. Used by both `create` (recreate path) and `finish`.
+ */
+function guardActiveChildren(branch, verb, config, branchVars) {
+    const entry = config.kontent.longLivedBranches[branch];
+    if (!entry?.children.length)
+        return;
+    const activeChildren = [];
+    for (const child of entry.children) {
+        if (branchVars.has(config.envVars.environmentId, child)) {
+            activeChildren.push(child);
+        }
+    }
+    if (activeChildren.length > 0) {
+        throw new CliError(`Cannot ${verb} long-lived branch "${branch}" \u2014 ` +
+            `the following children still have active environments:\n` +
+            activeChildren.map((c) => `  \u2022 ${c}`).join('\n') +
+            `\nFinish those branches first.`);
+    }
+}
+function removeBranchFromAllChildren(llb, branch) {
+    let modified = false;
+    for (const [, entry] of Object.entries(llb)) {
+        const idx = entry.children.indexOf(branch);
+        if (idx !== -1) {
+            entry.children.splice(idx, 1);
+            modified = true;
+        }
+    }
+    return modified;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const AUTH_STATUS_CODES = new Set([401, 403]);
+/**
+ * Detect authentication / authorisation errors that should never be retried.
+ * Checks for a numeric `status` property or a nested `response.status`.
+ */
+function isAuthError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const status = err.status;
+    if (typeof status === 'number' && AUTH_STATUS_CODES.has(status))
+        return true;
+    const response = err.response;
+    if (typeof response?.status === 'number' && AUTH_STATUS_CODES.has(response.status))
+        return true;
+    return false;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,12 @@
+export interface InitOptions {
+    dryRun: boolean;
+    force: boolean;
+}
+/**
+ * `marketing init` — one-shot migration from legacy CLI to config-driven model.
+ *
+ * Reads an existing legacy `status.json`, generates `marketing.config.json`,
+ * and rewrites `status.json` to the official format (per-environment migration
+ * arrays only, with `info`/`roles`/`netlify` stripped).
+ */
+export declare function init(opts: InitOptions): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,184 @@
+import { access, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod/v4';
+import { MIGRATIONS_FOLDER } from '../branches.js';
+import { configSchema } from '../config.js';
+import { CliError } from '../errors.js';
+import { MIGRATIONS_PACKAGE_JSON } from '../project.js';
+const STATUS_FILENAME = 'status.json';
+const CONFIG_FILENAME = 'marketing.config.json';
+const TSCONFIG_MIGRATIONS_FILENAME = 'tsconfig.migrations.json';
+/** Canonical tsconfig for compiling Kontent content-model migrations. */
+const TSCONFIG_MIGRATIONS = {
+    compilerOptions: {
+        target: 'ES2022',
+        module: 'Node16',
+        moduleResolution: 'Node16',
+        lib: ['ES2022', 'dom'],
+        rootDir: './Migrations',
+        outDir: './Migrations',
+        strict: true,
+        noUnusedLocals: true,
+        noUnusedParameters: true,
+        noImplicitReturns: true,
+        noFallthroughCasesInSwitch: true,
+        noUncheckedIndexedAccess: true,
+        forceConsistentCasingInFileNames: true,
+        esModuleInterop: true,
+        resolveJsonModule: true,
+        skipLibCheck: true,
+        declaration: false,
+        sourceMap: false,
+        incremental: false,
+    },
+    include: ['./Migrations'],
+    exclude: ['node_modules', 'Migrations/**/*.js'],
+};
+/**
+ * Zod schema for the legacy status.json shape.
+ *
+ * Validates the known keys strictly, using `z.looseObject()` so the dynamic
+ * UUID-keyed migration arrays survive without validation.
+ */
+const legacyStatusSchema = z.looseObject({
+    info: z.looseObject({
+        PRODUCTION_PROJECT: z.string(),
+    }),
+    roles: z.looseObject({
+        PRODUCTION_PROJECT: z.array(z.string()),
+    }),
+    netlify: z.object({
+        PREVIEW: z.string(),
+        PRODUCTION: z.string(),
+    }),
+});
+/** Standard Vite variable names scaffolded for every migration. */
+const STANDARD_ENV_VARS = {
+    environmentId: 'VITE_KONTENT_ENVIRONMENT_ID',
+    secureKey: 'KONTENT_SECURE_KEY',
+    previewKey: 'KONTENT_PREVIEW_KEY',
+    homepage: 'VITE_KONTENT_HOMEPAGE_CODENAME',
+    previewMode: 'VITE_KONTENT_PREVIEW_MODE',
+    managementKey: 'KONTENT_MANAGEMENT_KEY',
+};
+/**
+ * `marketing init` — one-shot migration from legacy CLI to config-driven model.
+ *
+ * Reads an existing legacy `status.json`, generates `marketing.config.json`,
+ * and rewrites `status.json` to the official format (per-environment migration
+ * arrays only, with `info`/`roles`/`netlify` stripped).
+ */
+export async function init(opts) {
+    const cwd = process.cwd();
+    const legacyStatusPath = join(cwd, STATUS_FILENAME);
+    const statusPath = join(cwd, MIGRATIONS_FOLDER, STATUS_FILENAME);
+    const configPath = join(cwd, CONFIG_FILENAME);
+    const tsconfigPath = join(cwd, TSCONFIG_MIGRATIONS_FILENAME);
+    // 1. Read status.json
+    let raw;
+    try {
+        raw = await readFile(legacyStatusPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new CliError(`Could not read ${STATUS_FILENAME} in ${cwd}. ` +
+                `init is a migration tool — a legacy status.json must exist.`);
+        }
+        throw new CliError(`Could not read ${STATUS_FILENAME}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${STATUS_FILENAME} contains invalid JSON.`);
+    }
+    // 2. Check if already official (no legacy keys)
+    if (isOfficialFormat(json)) {
+        throw new CliError(`${STATUS_FILENAME} is already in official format (no info/roles/netlify keys). Nothing to migrate.`);
+    }
+    // 3. Validate legacy schema
+    const result = legacyStatusSchema.safeParse(json);
+    if (!result.success) {
+        const issues = z.prettifyError(result.error);
+        throw new CliError(`Invalid legacy ${STATUS_FILENAME}:\n${issues}`);
+    }
+    // 4. Check if marketing.config.json or tsconfig.migrations.json already exist
+    const configExists = await access(configPath).then(() => true, () => false);
+    if (configExists && !opts.force) {
+        throw new CliError(`${CONFIG_FILENAME} already exists. Use --force to overwrite.`);
+    }
+    const tsconfigExists = await access(tsconfigPath).then(() => true, () => false);
+    if (tsconfigExists && !opts.force) {
+        throw new CliError(`${TSCONFIG_MIGRATIONS_FILENAME} already exists. Use --force to overwrite.`);
+    }
+    // 5. Derive config from legacy status
+    const legacy = result.data;
+    const config = deriveConfig(legacy);
+    // 5b. Validate derived config against configSchema
+    const configResult = configSchema.safeParse(config);
+    if (!configResult.success) {
+        const issues = z.prettifyError(configResult.error);
+        throw new CliError(`Cannot migrate: legacy ${STATUS_FILENAME} has empty or invalid values for fields that ${CONFIG_FILENAME} requires. ` +
+            `Fix ${STATUS_FILENAME} and re-run init.\n${issues}`);
+    }
+    // 6. Build official status (strip info/roles/netlify)
+    const officialStatus = stripLegacyKeys(json);
+    // 7. Write or dry-run
+    if (opts.dryRun) {
+        console.log(`[dry-run] Would write ${CONFIG_FILENAME}:`);
+        console.log(JSON.stringify(config, null, 2));
+        console.log('');
+        console.log(`[dry-run] Would write ${MIGRATIONS_FOLDER}/${STATUS_FILENAME}:`);
+        console.log(JSON.stringify(officialStatus, null, 2));
+        console.log('');
+        console.log(`[dry-run] Would write ${TSCONFIG_MIGRATIONS_FILENAME}:`);
+        console.log(JSON.stringify(TSCONFIG_MIGRATIONS, null, 2));
+        console.log('');
+        console.log(`[dry-run] Would write ${MIGRATIONS_FOLDER}/package.json:`);
+        console.log(JSON.stringify(MIGRATIONS_PACKAGE_JSON, null, 2));
+        console.log('');
+        console.log(`[dry-run] Would delete ./${STATUS_FILENAME}`);
+        return;
+    }
+    await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log(`Wrote ${CONFIG_FILENAME}`);
+    await mkdir(join(cwd, MIGRATIONS_FOLDER), { recursive: true });
+    await writeFile(statusPath, JSON.stringify(officialStatus, null, 2) + '\n');
+    console.log(`Wrote ${MIGRATIONS_FOLDER}/${STATUS_FILENAME}`);
+    await writeFile(tsconfigPath, JSON.stringify(TSCONFIG_MIGRATIONS, null, 2) + '\n');
+    console.log(`Wrote ${TSCONFIG_MIGRATIONS_FILENAME}`);
+    const migrationsPkgPath = join(cwd, MIGRATIONS_FOLDER, 'package.json');
+    const existingPkg = await readFile(migrationsPkgPath, 'utf8').then((raw) => JSON.parse(raw), () => ({}));
+    await writeFile(migrationsPkgPath, JSON.stringify({ ...existingPkg, ...MIGRATIONS_PACKAGE_JSON }, null, 2) + '\n');
+    console.log(`Wrote ${MIGRATIONS_FOLDER}/package.json`);
+    await unlink(legacyStatusPath);
+    console.log(`Deleted ./${STATUS_FILENAME}`);
+    console.log('envVars scaffolded with standard Vite names — verify they match your project.');
+    console.log('Review changes: git diff');
+}
+function isOfficialFormat(json) {
+    if (typeof json !== 'object' || json === null || Array.isArray(json))
+        return false;
+    const obj = json;
+    return !('info' in obj) && !('roles' in obj) && !('netlify' in obj);
+}
+function deriveConfig(legacy) {
+    return {
+        kontent: {
+            productionEnvironmentName: 'PRODUCTION_PROJECT',
+            productionEnvironmentId: legacy.info.PRODUCTION_PROJECT,
+            roles: legacy.roles.PRODUCTION_PROJECT,
+            longLivedBranches: {},
+        },
+        netlify: {
+            previewSiteId: legacy.netlify.PREVIEW,
+            productionSiteId: legacy.netlify.PRODUCTION,
+        },
+        envVars: { ...STANDARD_ENV_VARS },
+    };
+}
+function stripLegacyKeys(obj) {
+    const { info: _, roles: _r, netlify: _n, ...rest } = obj;
+    return rest;
+}

package/dist/commands/migration.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `marketing migration create <name>` — scaffold a new timestamp-ordered
+ * TypeScript migration file.
+ */
+export declare function migrationCreate(name: string, folder?: string): Promise<void>;
+export interface MigrationRunOptions {
+    branch?: string;
+    ci?: boolean;
+    yes?: boolean;
+    /** Internal — never CLI-exposed. Bypasses production guards and prompt. */
+    allowProduction?: boolean;
+    /**
+     * Internal — never CLI-exposed. Override the environment ID instead of
+     * reading it from `.env.development`. Used by `environment finish` to
+     * target the source environment while `.env.development` still points at
+     * the clone.
+     */
+    environmentId?: string;
+}
+/**
+ * `marketing migration run` — compile and execute all pending migrations
+ * against the environment specified in `.env.development`.
+ *
+ * Two-layer production guard:
+ * 1. Refuses on protected branches (`master`/`main`/`develop`)
+ * 2. Refuses when the resolved environment ID matches production
+ *
+ * Both guards are bypassed by `allowProduction: true` (used internally by
+ * `environment finish`).
+ */
+export declare function migrationRun(opts: MigrationRunOptions): Promise<void>;