@sonarsource/marketing-cli 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# @sonarsource/marketing-cli
+
+CLI tooling for Sonar marketing sites — manages Kontent.ai environments, content-model migrations, and assembles local `.env` files from Netlify.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) ≥ 22
+- A **Netlify auth token** — run `netlify login` or set `NETLIFY_AUTH_TOKEN` ([docs](https://docs.netlify.com/cli/get-started/#obtain-a-token-in-the-netlify-ui))
+- A **Kontent.ai management API key** — generate one in your project's [API keys settings](https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#section/Authentication)
+
+## Installation
+
+```sh
+yarn add -D @sonarsource/marketing-cli
+```
+
+## Configuration
+
+Every consuming repo needs a `marketing.config.json` at its root. If you're migrating from the legacy CLI, `marketing init` generates it for you. Otherwise, create one manually:
+
+```jsonc
+{
+  "kontent": {
+    // Display name shown in Kontent dashboard for the production environment
+    "productionEnvironmentName": "PRODUCTION_PROJECT",
+    // UUID of the production Kontent environment
+    "productionEnvironmentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    // Role IDs to activate on cloned environments
+    "roles": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"],
+    // Optional — declare long-lived branches (epics) and their children
+    "longLivedBranches": {},
+  },
+  "netlify": {
+    // Site ID for the preview/branch-deploy Netlify site
+    "previewSiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    // Site ID for the production Netlify site
+    "productionSiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  },
+  "envVars": {
+    // Env var names as they appear on Netlify and in .env files
+    "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",
+  },
+}
+```
+
+## Workflows
+
+### First-time repo onboarding
+
+```sh
+# 1. Clone the repo and install dependencies
+git clone <repo-url> && cd <repo>
+yarn
+
+# 2. Set your Netlify token (if not already) in your global profile (zshrc for example)
+export NETLIFY_AUTH_TOKEN=<token>
+
+# 3. Assemble .env files from Netlify
+marketing setup
+```
+
+`setup` fetches env vars from both the production and preview Netlify sites, resolves branch-scoped values when applicable, and writes `.env.development` and `.env.production`. A marker-delimited section inside each file is managed by the CLI — any keys you add outside the markers are left untouched.
+
+### Feature branch with content-model changes
+
+When your work requires changes to the Kontent.ai content model (adding types, modifying snippets, etc.), clone a dedicated environment so your changes are isolated from production.
+
+```sh
+# 1. Create a branch and clone a Kontent environment for it
+git checkout -b feat/my-feature
+marketing environment create
+
+# 2. Scaffold a migration
+marketing migration create add-hero-snippet
+
+# 3. Edit the generated file in Migrations/, then run it
+marketing migration run
+
+# 4. Develop, iterate, run more migrations as needed
+# ...
+
+# 5. When the branch is ready to merge — migrate production and clean up
+marketing environment finish
+```
+
+`environment create` clones the source Kontent environment, pushes the clone's ID to Netlify as a branch-scoped env var, seeds `Migrations/status.json`, re-runs `setup`, and runs any pending migrations.
+
+`environment finish` runs migrations on the source environment, deletes the clone, removes the Netlify branch var, and re-runs `setup`.
+
+### Long-lived branches (epics)
+
+For work that spans multiple branches (an epic), declare the parent as a long-lived branch so child branches can clone from it instead of production.
+
+```sh
+# 1. Create the epic branch with --stack
+git checkout -b epic/redesign
+marketing environment create --stack
+```
+
+This clones from production, registers the branch in `longLivedBranches` in `marketing.config.json`, and records the environment ID. Commit this config change — the team needs to see it.
+
+```sh
+# 2. Create child branches — the CLI asks which source to clone from
+git checkout -b feat/new-nav
+marketing environment create
+# ? Select source environment:
+# ❯ Production
+#   epic/redesign
+```
+
+When you select a long-lived branch as the source, the CLI automatically adds the current branch to that source's `children` in config. No manual config editing is required — branch names are free.
+
+You can also skip the selector with `--source`:
+
+```sh
+marketing environment create --source epic/redesign
+```
+
+Children are automatically removed from the parent's `children` on finish. Children must be finished before the parent:
+
+```sh
+git checkout feat/new-nav
+marketing environment finish    # migrates back to the epic environment
+
+git checkout epic/redesign
+marketing environment finish    # migrates back to production
+```
+
+## CI
+
+All commands respect `--ci` (or the `CI` environment variable). In CI mode, interactive prompts are skipped — commands that need confirmation require `--yes`. Auth tokens and API keys are resolved from environment variables rather than local dotenv files.
+
+## Command reference
+
+### Global options
+
+| Flag               | Description                                                                               |
+| ------------------ | ----------------------------------------------------------------------------------------- |
+| `--branch <name>`  | Override the detected branch (defaults to `git` or `GITHUB_HEAD_REF` / `GITHUB_REF_NAME`) |
+| `--ci` / `--no-ci` | Force CI mode on or off (defaults to the `CI` env var)                                    |
+| `--yes`            | Skip confirmation prompts                                                                 |
+
+### `marketing setup`
+
+Assemble `.env.development` and `.env.production` from Netlify env vars. Headless — no prompts, safe to run repeatedly.
+
+### `marketing init`
+
+One-time migration from the legacy CLI. Reads an existing `status.json`, generates `marketing.config.json`, and rewrites `status.json` to the new format.
+
+| Flag        | Description                                   |
+| ----------- | --------------------------------------------- |
+| `--dry-run` | Print proposed output without writing files   |
+| `--force`   | Overwrite an existing `marketing.config.json` |
+
+### `marketing environment create`
+
+Clone a Kontent.ai environment for the current branch.
+
+| Flag                | Description                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `--stack`           | Declare this branch as a long-lived branch in config                           |
+| `--source <branch>` | Clone from a specific long-lived branch instead of production (skips selector) |
+
+### `marketing environment finish`
+
+Migrate the source environment, delete the clone, and clean up Netlify vars and status.
+
+### `marketing migration create <name>`
+
+Scaffold a new timestamp-ordered TypeScript migration in `Migrations/`.
+
+### `marketing migration run`
+
+Compile and run all pending migrations against the current branch's environment. Refuses to target production directly — use `environment finish` for that.

package/dist/branch.d.ts

@@ -0,0 +1,14 @@
+export interface BranchOptions {
+    branch?: string;
+}
+/**
+ * Detect the current branch. Precedence:
+ * 1. `--branch <name>` CLI option
+ * 2. `GITHUB_HEAD_REF` (PR builds)
+ * 3. `GITHUB_REF_NAME` (push builds)
+ * 4. `git symbolic-ref --short HEAD`
+ *
+ * Returns `undefined` on detached HEAD / unresolvable — callers decide how to
+ * handle that (e.g. fall back to global/production vars).
+ */
+export declare function detectBranch(opts: BranchOptions): string | undefined;

package/dist/branch.js

@@ -0,0 +1,27 @@
+import { execSync } from 'node:child_process';
+/**
+ * Detect the current branch. Precedence:
+ * 1. `--branch <name>` CLI option
+ * 2. `GITHUB_HEAD_REF` (PR builds)
+ * 3. `GITHUB_REF_NAME` (push builds)
+ * 4. `git symbolic-ref --short HEAD`
+ *
+ * Returns `undefined` on detached HEAD / unresolvable — callers decide how to
+ * handle that (e.g. fall back to global/production vars).
+ */
+export function detectBranch(opts) {
+    if (opts.branch)
+        return opts.branch;
+    const headRef = process.env['GITHUB_HEAD_REF'];
+    if (headRef)
+        return headRef;
+    const refName = process.env['GITHUB_REF_NAME'];
+    if (refName)
+        return refName;
+    try {
+        return execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/branches.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Branches that are considered protected (i.e. associated with production).
+ * Used by `migration run` and `environment` commands to guard against
+ * accidental production mutations.
+ */
+export declare const PROTECTED_BRANCHES: readonly ["master", "main", "develop"];
+/** Hardcoded folder name for Kontent.ai content-model migrations. */
+export declare const MIGRATIONS_FOLDER = "Migrations";

package/dist/branches.js

@@ -0,0 +1,8 @@
+/**
+ * Branches that are considered protected (i.e. associated with production).
+ * Used by `migration run` and `environment` commands to guard against
+ * accidental production mutations.
+ */
+export const PROTECTED_BRANCHES = ['master', 'main', 'develop'];
+/** Hardcoded folder name for Kontent.ai content-model migrations. */
+export const MIGRATIONS_FOLDER = 'Migrations';

package/dist/ci.d.ts

@@ -0,0 +1,25 @@
+export interface CIOptions {
+    ci?: boolean;
+}
+/**
+ * Determine whether we're running in CI. The `--ci`/`--no-ci` flag overrides
+ * the environment variable when provided.
+ */
+export declare function isCI(opts: CIOptions): boolean;
+export interface ResolveManagementKeyOptions {
+    ci: boolean;
+    /** Value fetched from the Netlify preview site, if available */
+    netlifyValue: string | undefined;
+    /** Path to .env.development for local reads */
+    envFilePath: string;
+    /** The env var name for the management key (from config) */
+    managementKeyName: string;
+}
+/**
+ * Resolve the Kontent management API key by precedence:
+ * 1. `process.env.KONTENT_MANAGEMENT_KEY` (escape hatch)
+ * 2. CI → Netlify preview site value
+ * 3. Non-CI → read from local `.env.development`
+ * 4. Throw with actionable guidance
+ */
+export declare function resolveManagementKey(opts: ResolveManagementKeyOptions): string;

package/dist/ci.js

@@ -0,0 +1,37 @@
+import { readEnvValue } from './dotenv.js';
+import { CliError } from './errors.js';
+/**
+ * Determine whether we're running in CI. The `--ci`/`--no-ci` flag overrides
+ * the environment variable when provided.
+ */
+export function isCI(opts) {
+    if (opts.ci !== undefined)
+        return opts.ci;
+    const ci = process.env['CI'];
+    return ci !== undefined && ci !== '' && ci !== 'false' && ci !== '0';
+}
+/**
+ * Resolve the Kontent management API key by precedence:
+ * 1. `process.env.KONTENT_MANAGEMENT_KEY` (escape hatch)
+ * 2. CI → Netlify preview site value
+ * 3. Non-CI → read from local `.env.development`
+ * 4. Throw with actionable guidance
+ */
+export function resolveManagementKey(opts) {
+    // 1. Explicit env var always wins
+    const fromEnv = process.env['KONTENT_MANAGEMENT_KEY'];
+    if (fromEnv)
+        return fromEnv;
+    // 2. CI → Netlify preview site
+    if (opts.ci && opts.netlifyValue)
+        return opts.netlifyValue;
+    // 3. Local .env.development (non-CI, or CI fallback when Netlify value absent)
+    const fromFile = readEnvValue(opts.envFilePath, opts.managementKeyName);
+    if (fromFile)
+        return fromFile;
+    // 4. Nothing resolved
+    throw new CliError('Could not resolve the Kontent management API key.\n' +
+        '  • Set KONTENT_MANAGEMENT_KEY in your environment, or\n' +
+        `  • Add ${opts.managementKeyName}=<key> to ${opts.envFilePath}, or\n` +
+        '  • Run in CI with the key configured on the Netlify preview site.');
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+/**
+ * Build the fully-configured commander program. Kept separate from execution
+ * (see index.ts) so tests can assert on the command surface without spawning a
+ * process.
+ */
+export declare function buildProgram(): Command;

package/dist/cli.js

@@ -0,0 +1,102 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { environmentCreate, environmentFinish } from './commands/environment.js';
+import { init } from './commands/init.js';
+import { migrationCreate, migrationRun } from './commands/migration.js';
+import { setup } from './commands/setup.js';
+import { CliError } from './errors.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+/**
+ * Wrap a command action so that {@link CliError} is printed without a stack
+ * trace and sets a non-zero exit code, while unexpected errors propagate with
+ * their full stack.
+ */
+function wrapAction(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            if (err instanceof CliError) {
+                process.stderr.write(`Error: ${err.message}\n`);
+                process.exitCode = 1;
+            }
+            else {
+                throw err;
+            }
+        }
+    };
+}
+/**
+ * Build the fully-configured commander program. Kept separate from execution
+ * (see index.ts) so tests can assert on the command surface without spawning a
+ * process.
+ */
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('marketing')
+        .description(pkg.description ?? 'Sonar marketing CLI')
+        .version(pkg.version)
+        .option('--branch <name>', 'Override the detected branch name')
+        .option('--ci', 'Force CI mode')
+        .option('--no-ci', 'Force non-CI mode')
+        .option('--yes', 'Skip confirmation prompts');
+    // --- setup (real) ---
+    program
+        .command('setup')
+        .description('Assemble .env.* files from Netlify (headless).')
+        .action(wrapAction(async () => {
+        const globalOpts = program.opts();
+        await setup(globalOpts);
+    }));
+    // --- init (real) ---
+    const initCmd = program
+        .command('init')
+        .description('Migrate a repo from the legacy CLI to marketing.config.json.')
+        .option('--dry-run', 'Print proposed outputs without writing files')
+        .option('--force', 'Overwrite existing marketing.config.json');
+    initCmd.action(wrapAction(async () => {
+        const opts = initCmd.opts();
+        await init({ dryRun: opts.dryRun ?? false, force: opts.force ?? false });
+    }));
+    // --- migration (real) ---
+    const migration = program
+        .command('migration')
+        .description('Create and run Kontent.ai content-model migrations.');
+    migration
+        .command('create <name>')
+        .description('Scaffold a new timestamp-ordered TypeScript migration.')
+        .action(wrapAction(async (name) => {
+        await migrationCreate(name);
+    }));
+    migration
+        .command('run')
+        .description('Compile and run all pending migrations.')
+        .action(wrapAction(async () => {
+        const globalOpts = program.opts();
+        await migrationRun(globalOpts);
+    }));
+    // --- environment (real) ---
+    const environment = program
+        .command('environment')
+        .description('Create and finish per-branch Kontent.ai environments.');
+    const envCreate = environment
+        .command('create')
+        .description('Clone a Kontent.ai environment for the current branch.')
+        .option('--stack', 'Declare this branch as a long-lived branch in config')
+        .option('--source <branch>', 'Clone from a specific long-lived branch instead of production');
+    envCreate.action(wrapAction(async () => {
+        const globalOpts = program.opts();
+        const localOpts = envCreate.opts();
+        await environmentCreate({ ...globalOpts, stack: localOpts.stack, source: localOpts.source });
+    }));
+    environment
+        .command('finish')
+        .description('Migrate source, delete clone, and clean up.')
+        .action(wrapAction(async () => {
+        const globalOpts = program.opts();
+        await environmentFinish(globalOpts);
+    }));
+    return program;
+}

package/dist/commands/environment.d.ts

@@ -0,0 +1,36 @@
+import { type MarketingConfig } from '../config.js';
+export interface EnvironmentCreateOptions {
+    branch?: string;
+    ci?: boolean;
+    yes?: boolean;
+    stack?: boolean;
+    source?: string;
+}
+export interface EnvironmentFinishOptions {
+    branch?: string;
+    ci?: boolean;
+    yes?: boolean;
+}
+interface ResolvedSource {
+    environmentId: string;
+    isProduction: boolean;
+    /** The long-lived branch key this was resolved from, if any. */
+    sourceBranch?: string;
+}
+/**
+ * Slugify a branch name for use as the Kontent clone name.
+ * Non-alphanumeric characters (except `-`) → `-`, consecutive `-` collapsed,
+ * leading/trailing `-` trimmed.
+ */
+export declare function slugifyBranch(branch: string): string;
+/**
+ * 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 declare function resolveSourceEnvironment(branch: string, config: MarketingConfig): ResolvedSource;
+export declare function environmentCreate(opts: EnvironmentCreateOptions): Promise<void>;
+export declare function environmentFinish(opts: EnvironmentFinishOptions): Promise<void>;
+export {};