vibecarbon 0.1.0

package/src/configure.js

@@ -0,0 +1,967 @@
+/**
+ * Vibecarbon Configure Command
+ * Interactive wizard for configuring external services (billing, OAuth, SMTP, etc.)
+ *
+ * Guides the user through selecting which features to enable and entering
+ * the required credentials. Writes all values to .env.local and .env.
+ *
+ * Usage:
+ *   vibecarbon configure                # Interactive configuration wizard
+ *   vibecarbon configure cicd <env>     # Layer GitOps (Flux + GHA) on a deployed k8s cluster
+ *   vibecarbon configure -h             # Show help
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+
+import { renderHelp } from './lib/cli/help.js';
+import { parseFlags } from './lib/cli/parse-flags.js';
+import { c, printBanner } from './lib/colors.js';
+import { loadCredentials, loadProjectConfig } from './lib/config.js';
+import { requireLicense } from './lib/licensing/index.js';
+import { buildGitAddArgv, loadEnvVariables, setEnvVar } from './lib/project.js';
+import { assertInProjectDir } from './lib/project-guard.js';
+import { VERSION } from './lib/version.js';
+
+/** @type {import('./lib/cli/parse-flags.js').CommandSpec & { summary?: string, description?: string, examples?: Array<{ command: string, description?: string }> }} */
+const SPEC = {
+  name: 'configure',
+  summary: 'Configure external services (billing, OAuth, SMTP, CI/CD)',
+  description: [
+    'Interactive wizard for configuring external services in your Vibecarbon',
+    'project. Walks you through enabling features and entering API keys,',
+    'then writes everything to .env.local and .env.',
+    '',
+    'Configured credentials are deployed automatically when you run',
+    '`vibecarbon deploy`.',
+    '',
+    'SUBCOMMAND',
+    '  cicd <env>   Layer Flux + GitHub Actions wiring onto a deployed',
+    '               k8s/k8s-ha cluster. Diamond/Fullerene only.',
+    '',
+    'CONFIGURABLE FEATURES',
+    '  CI/CD                GitHub Actions build + deploy workflows',
+    '  Billing              Stripe, Paddle, or Polar payment processing',
+    '  Google OAuth         Sign in with Google',
+    '  Microsoft OAuth      Sign in with Microsoft',
+    '  SMTP / Email         Transactional emails (Resend, Mailgun, SES, etc.)',
+    '  Plausible Analytics  Privacy-friendly web analytics',
+  ].join('\n'),
+  flags: [
+    { name: 'h', boolean: true, description: 'Show this help' },
+    { name: 'v', boolean: true, description: 'Show version' },
+  ],
+  examples: [
+    {
+      command: 'vibecarbon configure',
+      description: 'Configure a new project after creation',
+    },
+    {
+      command: 'vibecarbon configure cicd prod',
+      description: 'Layer GitOps onto a deployed k8s cluster',
+    },
+  ],
+};
+
+// ============================================================================
+// FEATURE PROMPT FUNCTIONS
+// ============================================================================
+
+/**
+ * Helper: prompt for a text value, showing current value as placeholder.
+ * Returns the entered value, or the current value if user pressed Enter on a non-empty placeholder.
+ */
+async function promptText(message, currentValue, options = {}) {
+  const placeholder = currentValue || options.placeholder || '';
+  const defaultValue = currentValue || options.defaultValue || undefined;
+  const result = await p.text({
+    message,
+    placeholder: placeholder ? `${placeholder}` : undefined,
+    defaultValue,
+    validate: options.validate,
+  });
+  if (p.isCancel(result)) return null;
+  return result;
+}
+
+function requireNonEmpty(label) {
+  return (value) => {
+    if (!value?.trim()) return `${label} is required`;
+    return undefined;
+  };
+}
+
+/**
+ * Helper: prompt for a secret value (masked input).
+ */
+async function promptSecret(message, currentValue) {
+  const result = await p.password({
+    message: currentValue ? `${message} ${c.dim('(press Enter to keep current)')}` : message,
+    validate: (v) => {
+      if (!v && !currentValue) return 'This field is required';
+    },
+  });
+  if (p.isCancel(result)) return null;
+  // If user pressed Enter with no input and there's a current value, keep it
+  return result || currentValue || '';
+}
+
+// ---- Billing ----
+
+// Webhook endpoint that all billing providers point at. The unified handler
+// (carbon/src/server/routes/webhooks/billing.ts) dispatches based on the
+// active provider; Stripe also keeps /api/webhooks/stripe for back-compat.
+const BILLING_WEBHOOK_PATH = '/api/webhooks/billing';
+
+async function promptBilling(env) {
+  p.log.info(c.bold('Billing Configuration'));
+  p.log.info(c.dim('Choose your payment provider and enter API credentials.'));
+
+  const currentProvider = env.BILLING_PROVIDER || 'stripe';
+  const provider = await p.select({
+    message: 'Billing provider',
+    options: [
+      { value: 'stripe', label: 'Stripe', hint: 'most popular' },
+      { value: 'paddle', label: 'Paddle', hint: 'merchant of record' },
+      { value: 'polar', label: 'Polar', hint: 'open-source focused' },
+    ],
+    initialValue: currentProvider,
+  });
+  if (p.isCancel(provider)) return null;
+
+  const vars = { BILLING_PROVIDER: provider };
+
+  if (provider === 'stripe') {
+    p.note(
+      [
+        `${c.bold('1. Secret key')}`,
+        `   ${c.info('https://dashboard.stripe.com/apikeys')}`,
+        `   Use ${c.dim('sk_test_...')} for testing or ${c.dim('sk_live_...')} in production.`,
+        '',
+        `${c.bold('2. Webhook')} (Workbench → Webhooks → Create an event destination)`,
+        `   ${c.info('https://dashboard.stripe.com/webhooks')}`,
+        `   • Endpoint URL: ${c.dim(`https://<your-domain>${BILLING_WEBHOOK_PATH}`)}`,
+        '   • Events to send:',
+        '       checkout.session.completed',
+        '       customer.subscription.created',
+        '       customer.subscription.updated',
+        '       customer.subscription.deleted',
+        '       invoice.payment_failed',
+        `   • After creating, click ${c.dim('Reveal')} to copy the ${c.dim('whsec_...')} signing secret.`,
+        '',
+        `${c.bold('3. Price IDs')}`,
+        `   ${c.info('https://dashboard.stripe.com/products')}`,
+        '   Create a Startup and Pro product, then copy each recurring',
+        `   price's ${c.dim('price_...')} ID.`,
+      ].join('\n'),
+      'Stripe setup',
+    );
+
+    const secretKey = await promptSecret('Stripe secret key (sk_...)', env.STRIPE_SECRET_KEY);
+    if (secretKey === null) return null;
+    vars.STRIPE_SECRET_KEY = secretKey;
+
+    const webhookSecret = await promptSecret(
+      'Stripe webhook secret (whsec_...)',
+      env.STRIPE_WEBHOOK_SECRET,
+    );
+    if (webhookSecret === null) return null;
+    vars.STRIPE_WEBHOOK_SECRET = webhookSecret;
+
+    const priceStarter = await promptText(
+      'Stripe price ID for Startup plan (price_...)',
+      env.STRIPE_PRICE_STARTER,
+    );
+    if (priceStarter === null) return null;
+    vars.STRIPE_PRICE_STARTER = priceStarter;
+
+    const pricePro = await promptText(
+      'Stripe price ID for Pro plan (price_...)',
+      env.STRIPE_PRICE_PRO,
+    );
+    if (pricePro === null) return null;
+    vars.STRIPE_PRICE_PRO = pricePro;
+  } else if (provider === 'paddle') {
+    p.note(
+      [
+        `${c.bold('1. API key')} (Developer Tools → Authentication → API keys → New API key)`,
+        `   ${c.info('https://vendors.paddle.com')}`,
+        '   Generate a new key with read + write scope.',
+        '',
+        `${c.bold('2. Webhook')} (Developer Tools → Notifications → New destination)`,
+        `   ${c.info('https://vendors.paddle.com')}`,
+        `   • Endpoint URL: ${c.dim(`https://<your-domain>${BILLING_WEBHOOK_PATH}`)}`,
+        '   • Events to send:',
+        '       transaction.completed',
+        '       transaction.payment_failed',
+        '       subscription.created',
+        '       subscription.updated',
+        '       subscription.canceled',
+        '       subscription.past_due',
+        '   • Copy the secret key shown after creating the destination.',
+        '',
+        `${c.bold('3. Price IDs')} (Catalog → Products → pick product → Prices)`,
+        `   ${c.info('https://vendors.paddle.com')}`,
+        '   Create a Startup and Pro product, then copy each recurring',
+        `   price's ${c.dim('pri_...')} ID.`,
+      ].join('\n'),
+      'Paddle setup',
+    );
+
+    const apiKey = await promptSecret('Paddle API key', env.PADDLE_API_KEY);
+    if (apiKey === null) return null;
+    vars.PADDLE_API_KEY = apiKey;
+
+    const webhookSecret = await promptSecret('Paddle webhook secret', env.PADDLE_WEBHOOK_SECRET);
+    if (webhookSecret === null) return null;
+    vars.PADDLE_WEBHOOK_SECRET = webhookSecret;
+
+    const environment = await p.select({
+      message: 'Paddle environment',
+      options: [
+        { value: 'sandbox', label: 'Sandbox', hint: 'for testing' },
+        { value: 'production', label: 'Production', hint: 'live payments' },
+      ],
+      initialValue: env.PADDLE_ENVIRONMENT || 'sandbox',
+    });
+    if (p.isCancel(environment)) return null;
+    vars.PADDLE_ENVIRONMENT = environment;
+
+    const priceStarter = await promptText(
+      'Paddle price ID for Startup plan',
+      env.PADDLE_PRICE_STARTER,
+    );
+    if (priceStarter === null) return null;
+    vars.PADDLE_PRICE_STARTER = priceStarter;
+
+    const pricePro = await promptText('Paddle price ID for Pro plan', env.PADDLE_PRICE_PRO);
+    if (pricePro === null) return null;
+    vars.PADDLE_PRICE_PRO = pricePro;
+  } else if (provider === 'polar') {
+    p.note(
+      [
+        `${c.bold('1. Access token')} (Settings → Developers → New access token)`,
+        `   ${c.info('https://polar.sh/dashboard/<org>/settings')}`,
+        '',
+        `${c.bold('2. Webhook')} (Settings → Webhooks → Add Endpoint)`,
+        `   ${c.info('https://polar.sh/dashboard/<org>/settings/webhooks')}`,
+        `   • Endpoint URL: ${c.dim(`https://<your-domain>${BILLING_WEBHOOK_PATH}`)}`,
+        '   • Events to send:',
+        '       checkout.created',
+        '       subscription.created',
+        '       subscription.updated',
+        '       subscription.canceled',
+        '       subscription.revoked',
+        '   • Copy the secret shown after creating the endpoint.',
+        '',
+        `${c.bold('3. Organization ID')}`,
+        `   Shown in the dashboard URL after ${c.dim('/dashboard/')}.`,
+        '',
+        `${c.bold('4. Price IDs')}`,
+        `   ${c.info('https://polar.sh/dashboard/<org>/products')}`,
+      ].join('\n'),
+      'Polar setup',
+    );
+
+    const accessToken = await promptSecret('Polar access token', env.POLAR_ACCESS_TOKEN);
+    if (accessToken === null) return null;
+    vars.POLAR_ACCESS_TOKEN = accessToken;
+
+    const webhookSecret = await promptSecret('Polar webhook secret', env.POLAR_WEBHOOK_SECRET);
+    if (webhookSecret === null) return null;
+    vars.POLAR_WEBHOOK_SECRET = webhookSecret;
+
+    const orgId = await promptText('Polar organization ID', env.POLAR_ORGANIZATION_ID);
+    if (orgId === null) return null;
+    vars.POLAR_ORGANIZATION_ID = orgId;
+
+    const priceStarter = await promptText(
+      'Polar price ID for Startup plan',
+      env.POLAR_PRICE_STARTER,
+    );
+    if (priceStarter === null) return null;
+    vars.POLAR_PRICE_STARTER = priceStarter;
+
+    const pricePro = await promptText('Polar price ID for Pro plan', env.POLAR_PRICE_PRO);
+    if (pricePro === null) return null;
+    vars.POLAR_PRICE_PRO = pricePro;
+  }
+
+  return vars;
+}
+
+// ---- Google OAuth ----
+
+// Supabase Auth handles the OAuth dance; providers redirect to its callback,
+// not to your app. Show the user the exact URI to paste so they don't guess.
+function supabaseCallbackUrl(env) {
+  const base = (env.SUPABASE_URL || '').replace(/\/$/, '');
+  if (!base) return c.dim('<SUPABASE_URL>/auth/v1/callback');
+  return c.dim(`${base}/auth/v1/callback`);
+}
+
+async function promptGoogleOAuth(env) {
+  p.log.info(c.bold('Google OAuth'));
+
+  p.note(
+    [
+      `${c.bold('1. Configure consent screen')} (one-time prerequisite)`,
+      `   ${c.info('https://console.cloud.google.com/auth/branding')}`,
+      '   Google Auth Platform → Branding. Add app name + support email.',
+      '',
+      `${c.bold('2. Create OAuth client')} (Clients → Create client)`,
+      `   ${c.info('https://console.cloud.google.com/auth/clients')}`,
+      `   Application type: ${c.dim('Web application')}.`,
+      '',
+      `${c.bold('3. Authorized redirect URI')}`,
+      `   ${supabaseCallbackUrl(env)}`,
+      '   (paste this exact URL — Google must match it character-for-character)',
+      '',
+      `${c.bold('4. Copy the Client ID and Client secret')}`,
+      `   ${c.dim('The secret is only visible at creation — copy it immediately.')}`,
+    ].join('\n'),
+    'Google OAuth setup',
+  );
+
+  const clientId = await promptText('Google Client ID', env.GOOGLE_CLIENT_ID);
+  if (clientId === null) return null;
+
+  const clientSecret = await promptSecret('Google Client Secret', env.GOOGLE_CLIENT_SECRET);
+  if (clientSecret === null) return null;
+
+  return {
+    GOOGLE_ENABLED: 'true',
+    GOOGLE_CLIENT_ID: clientId,
+    GOOGLE_CLIENT_SECRET: clientSecret,
+  };
+}
+
+// ---- Microsoft OAuth ----
+
+async function promptMicrosoftOAuth(env) {
+  p.log.info(c.bold('Microsoft OAuth'));
+
+  p.note(
+    [
+      `${c.bold('1. Register an app')} (App registrations → New registration)`,
+      `   ${c.info('https://entra.microsoft.com')}`,
+      '   Microsoft Entra ID → App registrations → New registration.',
+      '',
+      `${c.bold('2. Redirect URI')} (platform: Web)`,
+      `   ${supabaseCallbackUrl(env)}`,
+      '',
+      `${c.bold('3. Client secret')} (Certificates & secrets → New client secret)`,
+      `   ${c.dim('Copy the Value (not the Secret ID) — Entra only shows it once.')}`,
+      '',
+      `${c.bold('4. Tenant ID')}`,
+      `   Use ${c.dim('common')} to allow any Microsoft account, or paste your`,
+      "   directory's tenant UUID for single-tenant apps.",
+    ].join('\n'),
+    'Microsoft OAuth setup',
+  );
+
+  const clientId = await promptText('Microsoft Client ID', env.MICROSOFT_CLIENT_ID);
+  if (clientId === null) return null;
+
+  const clientSecret = await promptSecret('Microsoft Client Secret', env.MICROSOFT_CLIENT_SECRET);
+  if (clientSecret === null) return null;
+
+  const tenantId = await promptText('Microsoft Tenant ID', env.MICROSOFT_TENANT_ID, {
+    placeholder: 'common',
+    defaultValue: 'common',
+  });
+  if (tenantId === null) return null;
+
+  return {
+    MICROSOFT_ENABLED: 'true',
+    MICROSOFT_CLIENT_ID: clientId,
+    MICROSOFT_CLIENT_SECRET: clientSecret,
+    MICROSOFT_TENANT_ID: tenantId,
+  };
+}
+
+// ---- SMTP / Email ----
+
+async function promptSmtp(env) {
+  p.log.info(c.bold('SMTP / Email'));
+  p.log.info(c.dim('Used for password resets, verification, and transactional emails.'));
+
+  p.note(
+    [
+      'Pick a provider, create an SMTP credential, then paste the values below.',
+      '',
+      `${c.bold('Resend')}`,
+      `   ${c.info('https://resend.com/api-keys')}`,
+      `   host ${c.dim('smtp.resend.com')}  •  port ${c.dim('587')}  •  user ${c.dim('resend')}  •  pass = API key`,
+      '',
+      `${c.bold('Mailgun')}`,
+      `   ${c.info('https://app.mailgun.com/app/sending/domains')}`,
+      `   host ${c.dim('smtp.mailgun.org')}  •  port ${c.dim('587')}`,
+      '',
+      `${c.bold('AWS SES')}`,
+      `   ${c.info('https://console.aws.amazon.com/ses/home#/smtp-settings')}`,
+      `   region-specific host  •  port ${c.dim('587')}`,
+      '',
+      `${c.bold('Postmark')}`,
+      `   ${c.info('https://account.postmarkapp.com/servers')}`,
+      `   host ${c.dim('smtp.postmarkapp.com')}  •  port ${c.dim('587')}`,
+      '',
+      `${c.bold('Verify your sender domain')} in the provider before going live,`,
+      'or production emails will land in spam (or get rejected outright).',
+    ].join('\n'),
+    'SMTP setup',
+  );
+
+  const host = await promptText('SMTP host', env.SMTP_HOST, {
+    placeholder: 'smtp.resend.com',
+    validate: requireNonEmpty('SMTP host'),
+  });
+  if (host === null) return null;
+
+  const port = await promptText('SMTP port', env.SMTP_PORT || '587', {
+    placeholder: '587',
+  });
+  if (port === null) return null;
+
+  const user = await promptText('SMTP username', env.SMTP_USER, {
+    validate: requireNonEmpty('SMTP username'),
+  });
+  if (user === null) return null;
+
+  const pass = await promptSecret('SMTP password', env.SMTP_PASS);
+  if (pass === null) return null;
+
+  const adminEmail = await promptText('Sender email address (from)', env.SMTP_ADMIN_EMAIL, {
+    placeholder: 'noreply@yourdomain.com',
+    validate: requireNonEmpty('Sender email'),
+  });
+  if (adminEmail === null) return null;
+
+  const senderDefault = env.PROJECT_NAME || 'My App';
+  const senderName = await promptText('Sender display name', env.SMTP_SENDER_NAME, {
+    placeholder: senderDefault,
+    defaultValue: senderDefault,
+  });
+  if (senderName === null) return null;
+
+  return {
+    SMTP_HOST: host,
+    SMTP_PORT: port,
+    SMTP_USER: user,
+    SMTP_PASS: pass,
+    SMTP_ADMIN_EMAIL: adminEmail,
+    SMTP_SENDER_NAME: senderName,
+  };
+}
+
+// ---- Plausible Analytics ----
+
+async function promptPlausible(env) {
+  p.log.info(c.bold('Plausible Analytics'));
+
+  p.note(
+    [
+      `${c.bold('1. Add your site')}`,
+      `   ${c.info('https://plausible.io/sites/new')}`,
+      `   Enter your domain ${c.dim('(without https://)')} — this becomes the value below.`,
+      '',
+      `${c.bold('2. Script URL')}`,
+      `   Defaults to ${c.dim('https://plausible.io/js/script.js')}.`,
+      '   Self-hosting Plausible? Point it at your own instance, e.g.',
+      `   ${c.dim('https://analytics.yourdomain.com/js/script.js')}.`,
+    ].join('\n'),
+    'Plausible setup',
+  );
+
+  const domain = await promptText('Your site domain (e.g., myapp.com)', env.VITE_PLAUSIBLE_DOMAIN);
+  if (domain === null) return null;
+
+  const scriptUrl = await promptText(
+    'Plausible script URL',
+    env.VITE_PLAUSIBLE_SCRIPT_URL || 'https://plausible.io/js/script.js',
+  );
+  if (scriptUrl === null) return null;
+
+  return {
+    VITE_PLAUSIBLE_DOMAIN: domain,
+    VITE_PLAUSIBLE_SCRIPT_URL: scriptUrl,
+  };
+}
+
+// (i18n moved to admin Settings → Localization card — language list lives in
+// app_settings.enabled_languages, not .env.local. See migration
+// 00005_localization_languages.sql.)
+
+/**
+ * CI/CD setup — bootstraps the project's GitHub repo (if missing), installs
+ * the canonical GHA workflows, rewrites image references with the real owner,
+ * and records the opt-in flag. Absorbs everything the legacy `vibecarbon add
+ * cicd` did; that command is gone (CI/CD is an external service, so it lives
+ * here in `configure`, not in `add` which is for local containers).
+ *
+ * Flow:
+ *   1. Verify `gh` CLI is installed + authenticated
+ *   2. Resolve owner: existing remote → use it; otherwise prompt + create repo
+ *      via `gh repo create` (with `git init` + initial commit if needed)
+ *   3. Rewrite ghcr.io / github.com image refs in compose + k8s manifests
+ *   4. Install `.github/workflows/vibecarbon-build.yml` + `deploy.yml`
+ *   5. Set `cicdEnabled: true` in `vibecarbon.json`
+ *
+ * After this, `vibecarbon deploy` for compose prompts Direct/Push per-deploy
+ * (push becomes the default once CI/CD is configured). K8s and K8s-HA deploys
+ * are local-first via deployK3s and ignore CI/CD entirely — this feature is
+ * purely additive: it adds the git-push deploy path for compose, and lays
+ * down GHA workflow files in the repo for teams that want them.
+ *
+ * Org-level secret seeding (Hetzner/Cloudflare/S3 tokens) is NOT done here —
+ * the first push-mode compose deploy (or first `-mode k8s` deploy) still runs
+ * `seedOrgSecrets` via `deployK8sGitOps`. Kept that way so secrets only land
+ * in GitHub when the user actually deploys, not when they merely configure.
+ */
+async function promptCicd() {
+  p.log.info(c.bold('CI/CD (GitHub Actions)'));
+  p.log.info(
+    c.dim(
+      'Bootstraps the GitHub repo (if needed) and installs build + deploy workflows so this project can ship via git push. Optional in all modes — k8s/k8s-ha deploys are local-first and never need CI/CD; compose deploys use git-push when configured, otherwise direct.',
+    ),
+  );
+
+  const {
+    detectGitHubUsername,
+    getGitHubRepo,
+    installDeployWorkflowFile,
+    installWorkflowFile,
+    updateImageReferences,
+  } = await import('./lib/ci-setup.js');
+  const { checkDependency, runCommand } = await import('./lib/command.js');
+
+  if (!checkDependency('gh', 'GitHub CLI')) {
+    p.log.error(
+      '`gh` CLI is required. Install from https://cli.github.com/, then run `gh auth login`.',
+    );
+    return null;
+  }
+  try {
+    runCommand(['gh', 'auth', 'status'], { silent: true });
+  } catch {
+    p.log.error(
+      '`gh` is not authenticated. Run `gh auth login` and re-run `vibecarbon configure`.',
+    );
+    return null;
+  }
+
+  const cwd = process.cwd();
+  const projectConfig = loadProjectConfig(cwd);
+  const projectName = projectConfig?.projectName;
+  if (!projectName) {
+    p.log.error('vibecarbon.json missing or has no projectName. Run `vibecarbon create` first.');
+    return null;
+  }
+
+  // Resolve owner: prefer an existing origin remote; otherwise bootstrap one.
+  let { owner: githubOwner, name: repoName } = getGitHubRepo(cwd);
+  const s = p.spinner();
+
+  if (githubOwner && repoName) {
+    p.log.info(`GitHub repo detected: ${c.bold(`${githubOwner}/${repoName}`)}`);
+  } else {
+    p.log.info('No GitHub origin remote — creating one now.');
+    const detected = detectGitHubUsername();
+    const ownerInput = await p.text({
+      message: 'GitHub username or organization:',
+      placeholder: detected || 'your-username',
+      initialValue: detected || '',
+      validate: (value) => {
+        if (!value) return 'GitHub username is required';
+        if (!/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(value))
+          return 'Invalid GitHub username format';
+      },
+    });
+    if (p.isCancel(ownerInput)) return null;
+    githubOwner = ownerInput;
+
+    const visibility = await p.select({
+      message: 'Repository visibility',
+      options: [
+        { value: 'private', label: 'Private', hint: 'recommended' },
+        { value: 'public', label: 'Public' },
+      ],
+      initialValue: 'private',
+    });
+    if (p.isCancel(visibility)) return null;
+
+    if (!existsSync(join(cwd, '.git'))) {
+      s.start('Initializing git repository');
+      runCommand(['git', 'init'], { silent: true, cwd });
+      s.stop('Git repository initialized');
+    }
+    const hasCommits = runCommand(['git', 'rev-parse', 'HEAD'], {
+      silent: true,
+      ignoreError: true,
+      cwd,
+    });
+    if (!hasCommits) {
+      s.start('Creating initial commit');
+      runCommand(buildGitAddArgv(), { silent: true, ignoreError: true, cwd });
+      runCommand(['git', 'commit', '-m', 'Initial commit - Vibecarbon project'], {
+        silent: true,
+        cwd,
+      });
+      s.stop('Initial commit created');
+    }
+
+    s.start(`Creating GitHub repository: ${githubOwner}/${projectName}`);
+    try {
+      // projectName is basename-validated at create time; visibility is a literal.
+      runCommand(
+        ['gh', 'repo', 'create', projectName, `--${visibility}`, '--source=.', '--remote=origin'],
+        { silent: true, timeout: 60000, cwd },
+      );
+      s.stop('GitHub repository created');
+    } catch (err) {
+      s.stop(`Failed to create GitHub repository: ${err.message}`);
+      return null;
+    }
+    repoName = projectName;
+  }
+
+  // Rewrite ghcr.io / github.com refs in compose + k8s manifests so they
+  // point at the real owner. Idempotent — re-running with the same owner
+  // is a no-op.
+  s.start('Updating Docker / Flux image references');
+  updateImageReferences(projectName, githubOwner, cwd);
+  s.stop('Image references updated');
+
+  try {
+    s.start('Installing .github/workflows/vibecarbon-build.yml');
+    const installedBuild = installWorkflowFile(cwd);
+    s.stop(installedBuild ? 'Build workflow installed' : 'Build workflow already present');
+
+    s.start('Installing .github/workflows/deploy.yml');
+    const installedDeploy = installDeployWorkflowFile(cwd);
+    s.stop(installedDeploy ? 'Deploy workflow installed' : 'Deploy workflow already present');
+  } catch (err) {
+    s.stop(`Failed to install workflow files: ${err.message}`);
+    return null;
+  }
+
+  // Record opt-in on the project so `ciAvailable()` detects CI/CD without
+  // shelling out to `gh` on every deploy.
+  const { saveProjectConfig: savePc } = await import('./lib/config.js');
+  if (projectConfig) {
+    savePc({ ...projectConfig, cicdEnabled: true }, cwd);
+    p.log.success('Marked CI/CD as enabled in vibecarbon.json');
+  } else {
+    p.log.warn(
+      'vibecarbon.json not found — workflows installed but the CI/CD flag could not be persisted. Subsequent deploys may require `--push` explicitly.',
+    );
+  }
+
+  p.log.info(
+    c.dim(
+      'Next: `git add .github/workflows && git commit && git push` to register the workflows with GitHub.',
+    ),
+  );
+
+  // No env vars to merge — side-effects only.
+  return {};
+}
+
+// ============================================================================
+// FEATURE DEFINITIONS
+// ============================================================================
+
+const FEATURES = [
+  {
+    value: 'cicd',
+    label: 'CI/CD',
+    hint: 'GitHub Actions build + deploy workflows (optional; enables git-push deploys)',
+    promptFn: promptCicd,
+  },
+  {
+    value: 'billing',
+    label: 'Billing',
+    hint: 'Stripe, Paddle, or Polar',
+    promptFn: promptBilling,
+  },
+  {
+    value: 'google-oauth',
+    label: 'Google OAuth',
+    hint: 'Sign in with Google',
+    promptFn: promptGoogleOAuth,
+  },
+  {
+    value: 'microsoft-oauth',
+    label: 'Microsoft OAuth',
+    hint: 'Sign in with Microsoft',
+    promptFn: promptMicrosoftOAuth,
+  },
+  {
+    value: 'smtp',
+    label: 'SMTP / Email',
+    hint: 'password resets, verification, transactional emails',
+    promptFn: promptSmtp,
+  },
+  {
+    value: 'plausible',
+    label: 'Plausible Analytics',
+    hint: 'privacy-friendly web analytics',
+    promptFn: promptPlausible,
+  },
+];
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+async function main(cliArgs) {
+  const { values, errors } = parseFlags(cliArgs, SPEC);
+
+  if (errors.length > 0) {
+    for (const e of errors) {
+      process.stderr.write(`${c.error('✗')} ${e}\n`);
+    }
+    process.stderr.write(`Run ${c.info('vibecarbon configure -h')} for usage.\n`);
+    process.exit(1);
+  }
+
+  if (values.h) {
+    process.stdout.write(renderHelp(SPEC));
+    process.exit(0);
+  }
+
+  if (values.v) {
+    console.log(`vibecarbon v${VERSION}`);
+    process.exit(0);
+  }
+
+  // Detect vibecarbon project
+  const cwd = process.cwd();
+  assertInProjectDir(cwd);
+
+  printBanner();
+  p.intro(`${c.bold('vibecarbon configure')} ${c.dim(`v${VERSION}`)}`);
+
+  // Load current env values
+  const env = loadEnvVariables(cwd);
+
+  // Feature selection — opt-in: nothing selected by default. Most users only
+  // want to configure one or two features per run; default-on forced them to
+  // uncheck the rest, which was tedious and hid the intent of the prompt.
+  const selected = await p.multiselect({
+    message: 'Which features would you like to configure?',
+    options: FEATURES.map((f) => ({
+      value: f.value,
+      label: f.label,
+      hint: f.hint,
+    })),
+    required: false,
+    initialValues: [],
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  if (selected.length === 0) {
+    p.log.warn('No features selected.');
+    p.outro('Nothing to configure.');
+    return;
+  }
+
+  // Collect credentials for each selected feature
+  const allVars = {};
+  const configuredFeatures = [];
+
+  for (const featureValue of selected) {
+    const feature = FEATURES.find((f) => f.value === featureValue);
+    const result = await feature.promptFn(env);
+
+    if (result === null) {
+      p.log.warn(`Skipped ${feature.label} (cancelled)`);
+      continue;
+    }
+
+    Object.assign(allVars, result);
+    configuredFeatures.push(feature.label);
+  }
+
+  if (configuredFeatures.length === 0) {
+    p.outro('No features configured.');
+    return;
+  }
+
+  // Show summary
+  const summaryLines = configuredFeatures.map((f) => `  ${c.success('+')} ${f}`).join('\n');
+  p.note(summaryLines, 'Features to configure');
+
+  // Write all values
+  const s = p.spinner();
+  s.start('Writing configuration');
+
+  for (const [key, value] of Object.entries(allVars)) {
+    setEnvVar(key, value, cwd);
+  }
+
+  s.stop('Configuration saved to .env.local and .env');
+
+  p.outro(
+    `Configured ${configuredFeatures.length} feature${configuredFeatures.length === 1 ? '' : 's'}. Run ${c.info('vibecarbon deploy')} to push to production.`,
+  );
+}
+
+// ============================================================================
+// `vibecarbon configure cicd <env>` subcommand
+// ============================================================================
+
+/**
+ * Layer GitOps (Flux + GitHub Actions wiring) onto a deployed k8s cluster.
+ *
+ * Pre-PR-5 this was the body of the `--gitops` deploy flag (see
+ * orchestrator.js's now-deleted handover block). PR 7 lifted it into a
+ * standalone subcommand so:
+ *   - The deploy path stays local-first by default (no Flux unless the
+ *     operator explicitly opts in).
+ *   - Operators can layer GitOps onto an existing cluster without
+ *     re-deploying.
+ *   - Tier gating happens at the entry point (Diamond/Fullerene only)
+ *     instead of being a flag-on-deploy concern.
+ *
+ * Pre-conditions:
+ *   - Project is initialized (`.vibecarbon.json` exists).
+ *   - The named environment was deployed via `vibecarbon deploy -mode k8s`
+ *     (the kubeconfig at `.vibecarbon/kubeconfig-<env>` must exist).
+ *   - `gh` CLI is authenticated and the project has a GitHub origin.
+ *   - License is Diamond or higher.
+ */
+export async function runConfigureCicd(envName) {
+  // Project guard runs before banner so an accidental `vibecarbon
+  // configure cicd` from a parent directory emits the canonical message.
+  const cwd = process.cwd();
+  const projectConfig = assertInProjectDir(cwd);
+
+  requireLicense('configure cicd');
+  printBanner();
+  p.intro(`${c.bold('vibecarbon configure cicd')} ${c.dim(`v${VERSION}`)}`);
+
+  if (!envName) {
+    p.log.error('Missing environment argument. Usage: vibecarbon configure cicd <env>');
+    process.exit(1);
+  }
+
+  const envConfig = projectConfig.environments?.[envName];
+  if (!envConfig) {
+    p.log.error(
+      `Environment "${envName}" not found in vibecarbon.json. Deploy it first with \`vibecarbon deploy ${envName} -mode k8s\`.`,
+    );
+    process.exit(1);
+  }
+
+  // GitOps only makes sense for k8s clusters. Compose deploys go through
+  // the build-workflow path that promptCicd already handles via the
+  // interactive wizard's "CI/CD" feature.
+  const isK8s =
+    envConfig.deployMode === 'kubernetes' ||
+    envConfig.deployMode === 'kubernetes-ha' ||
+    envConfig.deployMode === 'k8s' ||
+    envConfig.deployMode === 'k8s-ha';
+  if (!isK8s) {
+    p.log.error(
+      `Environment "${envName}" is ${envConfig.deployMode || 'unknown'} mode. configure cicd only applies to k8s / k8s-ha deploys.`,
+    );
+    p.log.info(
+      'For compose CI/CD, run `vibecarbon configure` (no subcommand) and pick CI/CD from the menu.',
+    );
+    process.exit(1);
+  }
+
+  const kubeconfigPath = join(cwd, '.vibecarbon', `kubeconfig-${envName}`);
+  if (!existsSync(kubeconfigPath)) {
+    p.log.error(
+      `Kubeconfig not found at ${kubeconfigPath}. Deploy the cluster first: vibecarbon deploy ${envName} -mode k8s`,
+    );
+    process.exit(1);
+  }
+
+  // Stage 1: install build + deploy workflow files locally + flip cicdEnabled.
+  // Reuses the same code path that the interactive wizard invokes for the
+  // CI/CD feature so behavior stays consistent across entry points.
+  p.log.step('Stage 1: install GitHub Actions workflows + mark cicdEnabled');
+  const projectSide = await promptCicd();
+  if (projectSide === null) {
+    p.log.error('Workflow installation aborted. Fix the gh-CLI / origin issues above and re-run.');
+    process.exit(1);
+  }
+
+  // Stage 2: layer Flux + GH Environment + workflow trigger onto the live
+  // cluster. This is the body that orchestrator.js used to run inline when
+  // --gitops was passed (deleted in PR 5).
+  p.log.step('Stage 2: install Flux + seed GitHub Environment + trigger first reconcile');
+  const { deployK8sGitOps } = await import('./lib/deploy/k8s/gitops-deploy.js');
+  const { getImageTag } = await import('./lib/ci-setup.js');
+  const creds = loadCredentials();
+  const imageTag = getImageTag(cwd);
+
+  // HA clusters split into <env>-primary and <env>-standby kubeconfigs;
+  // each needs its own GitOps handover. The orchestrator used to iterate
+  // over `[{suffix:'primary'}, {suffix:'standby'}]` in HA, single in non-HA.
+  const isHA = envConfig.deployMode === 'kubernetes-ha' || envConfig.deployMode === 'k8s-ha';
+  const targets = isHA
+    ? [
+        { suffix: 'primary', envName: `${envName}-primary` },
+        { suffix: 'standby', envName: `${envName}-standby` },
+      ]
+    : [{ suffix: null, envName }];
+
+  for (const target of targets) {
+    const targetKubeconfig = join(cwd, '.vibecarbon', `kubeconfig-${target.envName}`);
+    if (!existsSync(targetKubeconfig)) {
+      p.log.warn(
+        `Kubeconfig for ${target.envName} not found at ${targetKubeconfig} — skipping. Re-deploy that cluster with vibecarbon deploy first.`,
+      );
+      continue;
+    }
+    const subEnvConfig = projectConfig.environments?.[target.envName] ?? envConfig;
+    p.log.info(`Configuring GitOps for ${c.bold(target.envName)}`);
+    await deployK8sGitOps({
+      projectDir: cwd,
+      environment: target.envName,
+      domain: subEnvConfig.domain || envConfig.domain,
+      projectName: projectConfig.projectName,
+      kubeconfigPath: targetKubeconfig,
+      networkId: subEnvConfig.networkId || envConfig.networkId,
+      dnsProvider: subEnvConfig.dnsProvider || envConfig.dnsProvider,
+      creds,
+      imageTag,
+      s3BackupBucket: subEnvConfig.backupBucket || envConfig.backupBucket,
+    });
+  }
+
+  p.outro(c.success(`GitOps layered onto ${envName}. Future commits to main reconcile via Flux.`));
+}
+
+// ============================================================================
+// RUN FUNCTION (called by CLI entry point)
+// ============================================================================
+
+export async function run(args) {
+  // Subcommand routing: `vibecarbon configure cicd <env>` skips the
+  // interactive feature menu and runs the GitOps add-on flow directly.
+  // Any other first-positional arg falls through to the wizard's parser
+  // (which currently only handles -h / -v).
+  if (args[0] === 'cicd') {
+    return runConfigureCicd(args[1]);
+  }
+  await main(args);
+}
+
+// ============================================================================
+// TEST EXPORTS
+// ============================================================================
+
+export const __test__ = {
+  FEATURES,
+  SPEC,
+};