@sonarsource/marketing-cli 1.0.0

package/dist/commands/migration.js

@@ -0,0 +1,111 @@
+import { confirm } from '@clack/prompts';
+import { runMigrations } from '@kontent-ai/data-ops';
+import { execSync } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectBranch } from '../branch.js';
+import { MIGRATIONS_FOLDER, PROTECTED_BRANCHES } from '../branches.js';
+import { isCI, resolveManagementKey } from '../ci.js';
+import { loadConfig } from '../config.js';
+import { readEnvValue } from '../dotenv.js';
+import { assertNotCancelled, CliError } from '../errors.js';
+import { ensureMigrationsPackageJson, requireMigrationsEsm } from '../project.js';
+const TEMPLATE_PATH = join(fileURLToPath(import.meta.url), '..', '..', 'migration.template');
+/**
+ * `marketing migration create <name>` — scaffold a new timestamp-ordered
+ * TypeScript migration file.
+ */
+export async function migrationCreate(name, folder = MIGRATIONS_FOLDER) {
+    const now = new Date();
+    const template = await readFile(TEMPLATE_PATH, 'utf-8');
+    const content = template.replace('{{ORDER}}', `new Date('${now.toISOString()}')`);
+    const timestamp = [
+        now.getUTCFullYear(),
+        pad(now.getUTCMonth() + 1),
+        pad(now.getUTCDate()),
+        pad(now.getUTCHours()),
+        pad(now.getUTCMinutes()),
+        pad(now.getUTCSeconds()),
+    ].join('-');
+    const fileName = `${timestamp}-${name}.ts`;
+    await mkdir(folder, { recursive: true });
+    if (ensureMigrationsPackageJson(folder)) {
+        console.log(`Created ${folder}/package.json`);
+    }
+    await writeFile(join(folder, fileName), content, 'utf-8');
+    console.log(`Created migration: ${fileName}`);
+}
+function pad(n) {
+    return n.toString().padStart(2, '0');
+}
+/**
+ * `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 async function migrationRun(opts) {
+    const cwd = process.cwd();
+    requireMigrationsEsm(join(cwd, MIGRATIONS_FOLDER));
+    const config = loadConfig(cwd);
+    // --- Resolve environment ID ---
+    const envFilePath = join(cwd, '.env.development');
+    const environmentId = opts.environmentId ?? readEnvValue(envFilePath, config.envVars.environmentId);
+    if (!environmentId) {
+        throw new CliError(`No environment ID found in .env.development — run \`marketing setup\` first.`);
+    }
+    // --- Production guards + confirmation ---
+    if (!opts.allowProduction) {
+        const branch = detectBranch(opts);
+        if (branch && PROTECTED_BRANCHES.includes(branch)) {
+            throw new CliError(`Refusing to run migrations on protected branch "${branch}". ` +
+                `Switch to a feature branch, or use \`environment finish\` to migrate production.`);
+        }
+        if (environmentId === config.kontent.productionEnvironmentId) {
+            throw new CliError(`Refusing to run migrations against the production environment (${environmentId}). ` +
+                `Use \`environment finish\` to migrate production.`);
+        }
+        if (!opts.yes) {
+            if (!process.stdin.isTTY) {
+                throw new CliError(`No interactive terminal detected. Pass --yes to skip confirmation, ` +
+                    `or run in an interactive shell.`);
+            }
+            const confirmed = assertNotCancelled(await confirm({
+                message: branch
+                    ? `Run all migrations against environment for branch "${branch}" (${environmentId})?`
+                    : `Run all migrations against environment ${environmentId}?`,
+            }));
+            if (confirmed !== true) {
+                throw new CliError('Migration aborted by user.');
+            }
+        }
+    }
+    // --- Resolve management key ---
+    const ci = isCI(opts);
+    const apiKey = resolveManagementKey({
+        ci,
+        netlifyValue: undefined,
+        envFilePath,
+        managementKeyName: config.envVars.managementKey,
+    });
+    // --- Compile → run → clean ---
+    try {
+        execSync('tsc --build tsconfig.migrations.json', { stdio: 'inherit' });
+        await runMigrations({
+            environmentId,
+            apiKey,
+            migrationsFolder: MIGRATIONS_FOLDER,
+            all: true,
+        });
+        console.log('Migrations completed successfully.');
+    }
+    finally {
+        execSync('tsc --build tsconfig.migrations.json --clean', { stdio: 'inherit' });
+    }
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,9 @@
+export interface SetupOptions {
+    branch?: string;
+    ci?: boolean;
+}
+/**
+ * `marketing setup` — assemble `.env.development` and `.env.production` from
+ * Netlify env vars and local config. Fully headless, zero prompts.
+ */
+export declare function setup(opts: SetupOptions): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,73 @@
+import { join } from 'node:path';
+import { detectBranch } from '../branch.js';
+import { isCI, resolveManagementKey } from '../ci.js';
+import { loadConfig } from '../config.js';
+import { upsertEnvFile } from '../dotenv.js';
+import { CliError } from '../errors.js';
+import { fetchBranchVars, fetchProductionVars, resolveNetlifyToken } from '../netlify.js';
+/**
+ * `marketing setup` — assemble `.env.development` and `.env.production` from
+ * Netlify env vars and local config. Fully headless, zero prompts.
+ */
+export async function setup(opts) {
+    const cwd = process.cwd();
+    // 1. Load & validate config
+    const config = loadConfig(cwd);
+    console.log('Loaded config');
+    // 2. Resolve Netlify auth token
+    const token = resolveNetlifyToken();
+    // 3. Detect branch
+    const ci = isCI(opts);
+    const branch = detectBranch(opts);
+    if (!branch && ci) {
+        console.log('No branch detected — using global/production values');
+    }
+    else if (branch) {
+        console.log(`Branch: ${branch}`);
+    }
+    // 4. Fetch production vars
+    const prodVars = await fetchProductionVars(token, config.netlify.productionSiteId, config.envVars);
+    console.log('Fetched vars from production site');
+    // 5. Validate production environment ID
+    if (prodVars.productionEnvironmentId !== config.kontent.productionEnvironmentId) {
+        throw new CliError(`Netlify's production environment ID does not match config — ` +
+            `got "${prodVars.productionEnvironmentId}", expected "${config.kontent.productionEnvironmentId}".`);
+    }
+    // 6. Fetch preview vars (single GET, cached in BranchVars)
+    const branchVars = await fetchBranchVars(token, config.netlify.previewSiteId);
+    console.log('Fetched vars from preview site');
+    // 7. Resolve each env var from preview site
+    const resolvedEnvId = branchVars.resolve(config.envVars.environmentId, branch);
+    const resolvedPreviewKey = branchVars.resolve(config.envVars.previewKey, branch);
+    const resolvedHomepage = branchVars.resolve(config.envVars.homepage, branch);
+    const hasBranchVars = [resolvedEnvId, resolvedPreviewKey, resolvedHomepage].some((r) => r?.isBranchSpecific);
+    if (branch) {
+        console.log(`Branch: ${branch} (branch-scoped vars ${hasBranchVars ? 'found' : 'not found'})`);
+    }
+    // 8. Resolve management key
+    const managementKey = resolveManagementKey({
+        ci,
+        netlifyValue: branchVars.resolve(config.envVars.managementKey, branch)?.value,
+        envFilePath: join(cwd, '.env.development'),
+        managementKeyName: config.envVars.managementKey,
+    });
+    // 9. Build the var sets
+    const sharedVars = {
+        [config.envVars.secureKey]: prodVars.secureKey,
+        [config.envVars.managementKey]: managementKey,
+    };
+    if (resolvedEnvId)
+        sharedVars[config.envVars.environmentId] = resolvedEnvId.value;
+    if (resolvedPreviewKey)
+        sharedVars[config.envVars.previewKey] = resolvedPreviewKey.value;
+    if (resolvedHomepage)
+        sharedVars[config.envVars.homepage] = resolvedHomepage.value;
+    // 10. Write .env.development (preview mode on)
+    const devVars = { ...sharedVars, [config.envVars.previewMode]: 'true' };
+    await upsertEnvFile(join(cwd, '.env.development'), devVars);
+    console.log('Wrote .env.development');
+    // 11. Write .env.production (preview mode off)
+    const prodEnvVars = { ...sharedVars, [config.envVars.previewMode]: 'false' };
+    await upsertEnvFile(join(cwd, '.env.production'), prodEnvVars);
+    console.log('Wrote .env.production');
+}

package/dist/config.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod/v4';
+export declare const longLivedBranchSchema: z.ZodObject<{
+    environmentId: z.ZodOptional<z.ZodString>;
+    children: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const configSchema: z.ZodObject<{
+    kontent: z.ZodObject<{
+        productionEnvironmentName: z.ZodString;
+        productionEnvironmentId: z.ZodString;
+        roles: z.ZodArray<z.ZodString>;
+        longLivedBranches: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            environmentId: z.ZodOptional<z.ZodString>;
+            children: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strict>;
+    netlify: z.ZodObject<{
+        previewSiteId: z.ZodString;
+        productionSiteId: z.ZodString;
+    }, z.core.$strict>;
+    envVars: z.ZodObject<{
+        environmentId: z.ZodString;
+        secureKey: z.ZodString;
+        previewKey: z.ZodString;
+        homepage: z.ZodString;
+        previewMode: z.ZodString;
+        managementKey: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type MarketingConfig = z.infer<typeof configSchema>;
+/**
+ * Load and validate `marketing.config.json` from the given directory.
+ * Throws {@link CliError} on missing file, parse errors, or schema violations.
+ */
+export declare function loadConfig(cwd?: string): MarketingConfig;
+/**
+ * Write a mutated config back to `marketing.config.json`. Used by
+ * `environment create --stack` and `environment finish` to persist
+ * long-lived branch state.
+ */
+export declare function updateConfig(config: MarketingConfig, cwd?: string): void;

package/dist/config.js

@@ -0,0 +1,69 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod/v4';
+import { CliError } from './errors.js';
+const CONFIG_FILENAME = 'marketing.config.json';
+export const longLivedBranchSchema = z.object({
+    environmentId: z.string().min(1).optional(),
+    children: z.array(z.string()),
+});
+export const configSchema = z.strictObject({
+    kontent: z.strictObject({
+        productionEnvironmentName: z.string().min(1),
+        productionEnvironmentId: z.string().min(1),
+        roles: z.array(z.string().min(1)),
+        longLivedBranches: z.record(z.string(), longLivedBranchSchema).optional().default({}),
+    }),
+    netlify: z.strictObject({
+        previewSiteId: z.string().min(1),
+        productionSiteId: z.string().min(1),
+    }),
+    envVars: z.strictObject({
+        environmentId: z.string().min(1),
+        secureKey: z.string().min(1),
+        previewKey: z.string().min(1),
+        homepage: z.string().min(1),
+        previewMode: z.string().min(1),
+        managementKey: z.string().min(1),
+    }),
+});
+/**
+ * Load and validate `marketing.config.json` from the given directory.
+ * Throws {@link CliError} on missing file, parse errors, or schema violations.
+ */
+export function loadConfig(cwd = process.cwd()) {
+    const filePath = join(cwd, CONFIG_FILENAME);
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new CliError(`Could not read ${CONFIG_FILENAME} in ${cwd}. ` +
+                `Make sure the file exists and you are running from the project root.`);
+        }
+        throw new CliError(`Could not read ${CONFIG_FILENAME}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${CONFIG_FILENAME} contains invalid JSON.`);
+    }
+    const result = configSchema.safeParse(json);
+    if (!result.success) {
+        const issues = z.prettifyError(result.error);
+        throw new CliError(`Invalid ${CONFIG_FILENAME}:\n${issues}`);
+    }
+    return result.data;
+}
+/**
+ * Write a mutated config back to `marketing.config.json`. Used by
+ * `environment create --stack` and `environment finish` to persist
+ * long-lived branch state.
+ */
+export function updateConfig(config, cwd = process.cwd()) {
+    const filePath = join(cwd, CONFIG_FILENAME);
+    writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}

package/dist/dotenv.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Upsert key-value pairs into a marker-delimited managed section of a dotenv
+ * file. Keys outside the markers are never touched. If the file does not exist
+ * or has no markers yet, the managed block is appended.
+ */
+export declare function upsertEnvFile(filePath: string, vars: Record<string, string>): Promise<void>;
+/**
+ * Read a single key's value from a dotenv file. Returns `undefined` if the
+ * file does not exist or the key is not found. Not marker-aware — scans the
+ * entire file.
+ */
+export declare function readEnvValue(filePath: string, key: string): string | undefined;

package/dist/dotenv.js

@@ -0,0 +1,113 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CliError } from './errors.js';
+const START_MARKER = '# --- managed by @sonarsource/marketing-cli start ---';
+const END_MARKER = '# --- managed by @sonarsource/marketing-cli end ---';
+/**
+ * Upsert key-value pairs into a marker-delimited managed section of a dotenv
+ * file. Keys outside the markers are never touched. If the file does not exist
+ * or has no markers yet, the managed block is appended.
+ */
+export async function upsertEnvFile(filePath, vars) {
+    let existing = '';
+    try {
+        existing = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        // file doesn't exist yet — fine
+    }
+    const startIdx = existing.indexOf(START_MARKER);
+    const endIdx = existing.indexOf(END_MARKER);
+    if (startIdx === -1 || endIdx === -1) {
+        // No managed section yet — append one
+        const block = buildManagedBlock(vars);
+        const sep = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+        const content = existing + sep + block + '\n';
+        ensureWrite(filePath, content);
+        return;
+    }
+    // Extract the managed section lines
+    const before = existing.slice(0, startIdx);
+    const after = existing.slice(endIdx + END_MARKER.length);
+    const sectionContent = existing.slice(startIdx + START_MARKER.length, endIdx);
+    const sectionLines = sectionContent.split('\n');
+    // Upsert within the section: update existing keys, track which are new
+    const remaining = new Map(Object.entries(vars));
+    const updatedLines = [];
+    for (const line of sectionLines) {
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/);
+        if (match?.[1] && remaining.has(match[1])) {
+            updatedLines.push(`${match[1]}=${remaining.get(match[1])}`);
+            remaining.delete(match[1]);
+        }
+        else {
+            updatedLines.push(line);
+        }
+    }
+    // Strip trailing blank lines so new keys sit right before END_MARKER
+    while (updatedLines.length && updatedLines[updatedLines.length - 1] === '') {
+        updatedLines.pop();
+    }
+    for (const [key, value] of remaining) {
+        updatedLines.push(`${key}=${quoteValue(value)}`);
+    }
+    const newSection = updatedLines.join('\n');
+    const content = before + START_MARKER + '\n' + newSection + '\n' + END_MARKER + after;
+    ensureWrite(filePath, content);
+}
+/**
+ * Quote a value for safe dotenv writing. Wraps in double quotes and escapes
+ * embedded double-quotes and backslashes. Rejects embedded newlines since
+ * they would break the marker-delimited section.
+ */
+function quoteValue(value) {
+    if (value.includes('\n') || value.includes('\r')) {
+        throw new CliError(`Cannot write env value containing newlines — this would corrupt the managed section.`);
+    }
+    // Always quote to handle spaces, #, and other special chars
+    const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `"${escaped}"`;
+}
+function buildManagedBlock(vars) {
+    const lines = Object.entries(vars).map(([k, v]) => `${k}=${quoteValue(v)}`);
+    return [START_MARKER, ...lines, END_MARKER].join('\n');
+}
+function ensureWrite(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, 'utf8');
+}
+/**
+ * Read a single key's value from a dotenv file. Returns `undefined` if the
+ * file does not exist or the key is not found. Not marker-aware — scans the
+ * entire file.
+ */
+export function readEnvValue(filePath, key) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let value;
+    for (const line of content.split('\n')) {
+        if (line.startsWith(`${key}=`)) {
+            value = line.slice(key.length + 1);
+        }
+    }
+    return value !== undefined ? stripQuotes(value) : value;
+}
+/**
+ * Strip matching surrounding quotes (single or double) from a dotenv value,
+ * mirroring the behaviour of standard dotenv parsers.
+ */
+function stripQuotes(raw) {
+    if (raw.length >= 2) {
+        const first = raw[0];
+        const last = raw[raw.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return raw.slice(1, -1);
+        }
+    }
+    return raw;
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * User-facing CLI error. Printed without a stack trace because the failure is
+ * expected (bad config, missing token, API mismatch, etc.).
+ */
+export declare class CliError extends Error {
+    name: string;
+}
+/**
+ * Guard for `@clack/prompts` cancel symbols.
+ * Returns the value unchanged if it is not a cancel symbol;
+ * throws {@link CliError} otherwise.
+ */
+export declare function assertNotCancelled<T>(value: T | symbol): T;

package/dist/errors.js

@@ -0,0 +1,18 @@
+/**
+ * User-facing CLI error. Printed without a stack trace because the failure is
+ * expected (bad config, missing token, API mismatch, etc.).
+ */
+export class CliError extends Error {
+    name = 'CliError';
+}
+/**
+ * Guard for `@clack/prompts` cancel symbols.
+ * Returns the value unchanged if it is not a cancel symbol;
+ * throws {@link CliError} otherwise.
+ */
+export function assertNotCancelled(value) {
+    if (typeof value === 'symbol') {
+        throw new CliError('Aborted by user.');
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { buildProgram } from './cli.js';
+buildProgram().parse();

package/dist/kontent.d.ts

@@ -0,0 +1,8 @@
+import { ManagementClient } from '@kontent-ai/management-sdk';
+/**
+ * Create a Kontent.ai Management SDK client scoped to a specific environment.
+ *
+ * Single factory centralises the constructor so the entire SDK surface can be
+ * mocked with one `vi.mock('./kontent.js', …)` target.
+ */
+export declare function createKontentClient(environmentId: string, apiKey: string): ManagementClient;

package/dist/kontent.js

@@ -0,0 +1,10 @@
+import { ManagementClient } from '@kontent-ai/management-sdk';
+/**
+ * Create a Kontent.ai Management SDK client scoped to a specific environment.
+ *
+ * Single factory centralises the constructor so the entire SDK surface can be
+ * mocked with one `vi.mock('./kontent.js', …)` target.
+ */
+export function createKontentClient(environmentId, apiKey) {
+    return new ManagementClient({ environmentId, apiKey });
+}

package/dist/migration.template

@@ -0,0 +1,9 @@
+import type { MigrationModule } from "@sonarsource/marketing-cli";
+
+const migration: MigrationModule = {
+  order: {{ORDER}},
+  run: async _apiClient => {},
+  rollback: async _apiClient => {},
+};
+
+export default migration;

package/dist/migrations.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-exports for consumer migration files. Migrations import from
+ * `@sonarsource/marketing-cli` — they never need to depend on `data-ops` or
+ * `management-sdk` directly.
+ */
+export type { MigrationModule, MigrationOrder } from '@kontent-ai/data-ops';
+export * from '@kontent-ai/management-sdk';

package/dist/migrations.js

@@ -0,0 +1 @@
+export * from '@kontent-ai/management-sdk';

package/dist/netlify.d.ts

@@ -0,0 +1,49 @@
+import type { MarketingConfig } from './config.js';
+/**
+ * Shape of an env var value entry in the Netlify API response.
+ */
+export interface NetlifyEnvValue {
+    id: string;
+    value: string;
+    context: string;
+    context_parameter?: string;
+}
+export interface NetlifyEnvVar {
+    key: string;
+    scopes: string[];
+    values: NetlifyEnvValue[];
+}
+export interface ProductionVars {
+    secureKey: string;
+    productionEnvironmentId: string;
+}
+/**
+ * Fetch env vars from the production Netlify site and extract:
+ * - `secureKey` (the delivery secure key)
+ * - `productionEnvironmentId` (for validation against config)
+ */
+export declare function fetchProductionVars(token: string, siteId: string, envVarNames: MarketingConfig['envVars']): Promise<ProductionVars>;
+export interface BranchVars {
+    /** Whether a branch-scoped value exists for `key` on `branch`. Reads from cache. */
+    has(key: string, branch: string): boolean;
+    /** Resolve a var for a branch (branch-specific → global fallback). Reads from cache. */
+    resolve(key: string, branch: string | undefined): {
+        value: string;
+        isBranchSpecific: boolean;
+    } | undefined;
+    /** Set (or update) a branch-scoped value. Hits the API, then updates the cache. */
+    set(key: string, branch: string, value: string): Promise<void>;
+    /** Delete a branch-scoped value. Hits the API, then updates the cache. */
+    delete(key: string, branch: string): Promise<void>;
+}
+/**
+ * Fetch all env vars for a Netlify site once and return a {@link BranchVars}
+ * object whose read methods operate on the cached snapshot and whose write
+ * methods hit the API then optimistically update the cache.
+ */
+export declare function fetchBranchVars(token: string, siteId: string): Promise<BranchVars>;
+/**
+ * Resolve the Netlify auth token from the environment.
+ * Throws with actionable guidance when missing.
+ */
+export declare function resolveNetlifyToken(): string;