feat: add Salesforce release workflow and interactive release script

Author: paustint

.github/workflows/sfdx-release.yml

@@ -0,0 +1,110 @@
+name: Salesforce Release
+
+# Creates a new Salesforce managed package version, optionally promotes it to
+# released, tags `salesforce-vX.Y.Z`, and cuts a GitHub release.
+# Triggered locally via `pnpm release:salesforce`.
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        default: "patch"
+        type: choice
+        options: [patch, minor, major]
+
+      promote:
+        description: "Promote to released (installable in production orgs). False = beta only."
+        required: true
+        type: boolean
+
+concurrency:
+  group: sfdx-release
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  release-salesforce:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    environment: production
+
+    steps:
+      - name: Validate branch
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          if [[ "$REF_NAME" != "main" && ! "$REF_NAME" =~ ^hotfix/ ]]; then
+            echo "Error: This workflow can only run on 'main' or a 'hotfix/*' branch. Current branch: $REF_NAME"
+            exit 1
+          fi
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          # Overridden later with a GitHub App installation token so the bump
+          # commit + tag push are made as the App (on the ruleset bypass list).
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Install Salesforce CLI
+        run: npm install -g @salesforce/cli
+
+      - name: Decode JWT key
+        run: echo "${{ secrets.SFDX_JWT_KEY_BASE64 }}" | base64 --decode > server.key
+
+      - name: Authenticate to Dev Hub
+        run: |
+          sf org login jwt \
+            --client-id ${{ secrets.SFDX_CONSUMER_KEY }} \
+            --jwt-key-file server.key \
+            --username ${{ secrets.SFDX_DEVHUB_USERNAME }} \
+            --set-default-dev-hub \
+            --alias devhub
+
+      # Generate a GitHub App installation token for git pushes.
+      # The App's bot account is on the main-branch ruleset bypass list, which a PAT is not.
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ secrets.CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Get GitHub App user ID
+        id: app-user
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+        run: |
+          USER_ID=$(gh api "/users/${APP_SLUG}[bot]" --jq .id)
+          echo "user-id=${USER_ID}" >> "$GITHUB_OUTPUT"
+
+      - name: Configure git for release
+        env:
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+          USER_ID: ${{ steps.app-user.outputs.user-id }}
+          APP_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          git config user.name "${APP_SLUG}[bot]"
+          git config user.email "${USER_ID}+${APP_SLUG}[bot]@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${APP_TOKEN}@github.com/${REPO}.git"
+
+      - name: Create package version and release
+        env:
+          BUMP: ${{ inputs.bump }}
+          PROMOTE: ${{ inputs.promote }}
+          SFDX_INSTALLATION_PASSWORD: ${{ secrets.SFDX_INSTALLATION_PASSWORD }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+        run: node apps-sfdx/scripts/sfdx/release.mjs
+
+      - name: Remove key file
+        if: always()
+        run: rm -f server.key

apps-sfdx/README.md

@@ -81,8 +81,7 @@ apps-sfdx/
 
 ## Permissions
 
-Access to the canvas app is gated by the **Jetstream** permission set. The External Client App's OAuth policy pre-authorizes this
-permission set (`AdminApprovedPreAuthorized`), so assigning it both grants UI access and authorizes the OAuth connection:
+Access to the canvas app is gated by the **Jetstream** permission set.
 
 ```bash
 sf org assign permset --name Jetstream --target-org <org-alias>

apps-sfdx/scripts/sfdx/release.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * In-workflow Salesforce managed package release worker.
+ *
+ * Runs inside the `sfdx-release.yml` GitHub Action after the Dev Hub auth and
+ * git identity have been configured. It:
+ *   1. Bumps `versionName` / `versionNumber` in sfdx-project.json
+ *   2. Creates a new package version (`sf package version create`)
+ *   3. Optionally promotes it to "released"
+ *   4. Commits the bump, tags `salesforce-vX.Y.Z`, and cuts a GitHub release
+ *   5. Writes a rich job summary including the install URL
+ *
+ * Uses only Node built-ins so CI does not need to install apps-sfdx dependencies.
+ *
+ * Required env: BUMP (patch|minor|major), PROMOTE (true|false), SFDX_INSTALLATION_PASSWORD.
+ * Optional env: REPO, GITHUB_STEP_SUMMARY, DRY_RUN (true skips all sf/git/gh side effects).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+// apps-sfdx root – sf commands must run here so they can locate sfdx-project.json
+const sfdxProjectDir = path.resolve(scriptDir, '../..');
+const sfdxProjectFile = path.join(sfdxProjectDir, 'sfdx-project.json');
+
+const PACKAGE_NAME = 'Jetstream for Salesforce';
+const TAG_PREFIX = 'salesforce-v';
+
+const bump = requireEnv('BUMP');
+const promote = process.env.PROMOTE === 'true';
+const isDryRun = process.env.DRY_RUN === 'true';
+const installationKey = isDryRun ? 'dry-run-key' : requireEnv('SFDX_INSTALLATION_PASSWORD');
+const repo = process.env.REPO ?? 'jetstreamapp/jetstream';
+
+if (!['patch', 'minor', 'major'].includes(bump)) {
+  fail(`Invalid BUMP "${bump}". Expected one of: patch, minor, major.`);
+}
+
+// ── 1. Bump version in sfdx-project.json ────────────────────────────────────
+const projectJson = JSON.parse(readFileSync(sfdxProjectFile, 'utf8'));
+const defaultPackage = projectJson.packageDirectories?.find(({ package: pkg }) => pkg === PACKAGE_NAME);
+if (!defaultPackage) {
+  fail(`Could not find package "${PACKAGE_NAME}" in sfdx-project.json.`);
+}
+
+const version = nextVersion(defaultPackage.versionNumber, bump);
+const versionString = `${version.major}.${version.minor}.${version.patch}`;
+const tag = `${TAG_PREFIX}${versionString}`;
+
+console.log(`Releasing ${PACKAGE_NAME} ${versionString} (${bump} bump from ${defaultPackage.versionNumber})`);
+console.log(`Promote to released: ${promote ? 'yes' : 'no (beta)'}`);
+
+defaultPackage.versionName = `v${versionString}`;
+defaultPackage.versionNumber = `${versionString}.NEXT`;
+writeFileSync(sfdxProjectFile, `${JSON.stringify(projectJson, null, 2)}\n`);
+
+// ── 2. Create the package version ───────────────────────────────────────────
+// `--json` keeps output parseable; `--code-coverage` is required to later promote.
+console.log('\nCreating package version (this can take several minutes)...');
+const createResult = isDryRun
+  ? { result: { SubscriberPackageVersionId: '04tXXXXXXXXXXXXXXX' } }
+  : JSON.parse(
+      captureSf([
+        'package',
+        'version',
+        'create',
+        '--package',
+        PACKAGE_NAME,
+        '--installation-key',
+        installationKey,
+        '--code-coverage',
+        '--wait',
+        '90',
+        '--json'
+      ])
+    );
+
+const subscriberPackageVersionId = createResult?.result?.SubscriberPackageVersionId;
+if (!subscriberPackageVersionId) {
+  fail(`Package version create did not return a SubscriberPackageVersionId.\n${JSON.stringify(createResult, null, 2)}`);
+}
+console.log(`Created package version: ${subscriberPackageVersionId}`);
+
+// ── 3. Promote (optional) ───────────────────────────────────────────────────
+if (promote && !isDryRun) {
+  console.log('\nPromoting package version to released...');
+  captureSf(['package', 'version', 'promote', '--package', subscriberPackageVersionId, '--no-prompt', '--json']);
+  console.log('Promoted.');
+}
+
+// ── 4. Commit, tag, push, GitHub release ────────────────────────────────────
+if (!isDryRun) {
+  console.log('\nCommitting version bump and creating tag...');
+  git(['add', 'sfdx-project.json']);
+  git(['commit', '-m', `chore: release salesforce ${tag.replace(TAG_PREFIX, 'v')}`]);
+  git(['tag', tag]);
+  git(['push', 'origin', 'HEAD']);
+  git(['push', 'origin', tag]);
+
+  console.log('Creating GitHub release...');
+  exec('gh', ['release', 'create', tag, '--title', `Jetstream for Salesforce ${versionString}`, '--notes', releaseNotes()], {
+    cwd: sfdxProjectDir
+  });
+}
+
+// ── 5. Job summary ──────────────────────────────────────────────────────────
+writeSummary();
+console.log('\nDone.');
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function installUrl() {
+  return `https://login.salesforce.com/packaging/installPackage.apexp?p0=${subscriberPackageVersionId}`;
+}
+
+function releaseNotes() {
+  return [
+    `**Version:** ${versionString}`,
+    `**Status:** ${promote ? 'Released (installable in production orgs)' : 'Beta (scratch/sandbox only)'}`,
+    `**Package version id:** \`${subscriberPackageVersionId}\``,
+    '',
+    `**Install:** ${installUrl()}`,
+    '',
+    'An installation key is required to install this package (see the `SFDX_INSTALLATION_PASSWORD` secret).'
+  ].join('\n');
+}
+
+function writeSummary() {
+  const lines = [
+    `## 🚀 Salesforce Managed Package Release`,
+    '',
+    `| Field | Value |`,
+    `|-------|-------|`,
+    `| Version | \`${versionString}\` |`,
+    `| Bump | \`${bump}\` |`,
+    `| Status | ${promote ? '✅ Released' : '🧪 Beta'} |`,
+    `| Tag | [${tag}](https://github.com/${repo}/releases/tag/${tag}) |`,
+    `| Package version id | \`${subscriberPackageVersionId}\` |`,
+    '',
+    `**Install URL:** ${installUrl()}`,
+    '',
+    '> An installation key is required to install (the `SFDX_INSTALLATION_PASSWORD` value).',
+    ''
+  ];
+  const summary = lines.join('\n');
+  console.log(`\n${summary}`);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${summary}\n`);
+  }
+}
+
+/** Parse `X.Y.Z.NEXT` (or `X.Y.Z`) and return the bumped components. */
+function nextVersion(versionNumber, bumpType) {
+  const [major, minor, patch] = versionNumber.split('.').map((part) => Number.parseInt(part, 10));
+  if ([major, minor, patch].some((part) => Number.isNaN(part))) {
+    fail(`Could not parse versionNumber "${versionNumber}". Expected "X.Y.Z.NEXT".`);
+  }
+  switch (bumpType) {
+    case 'major':
+      return { major: major + 1, minor: 0, patch: 0 };
+    case 'minor':
+      return { major, minor: minor + 1, patch: 0 };
+    default:
+      return { major, minor, patch: patch + 1 };
+  }
+}
+
+function git(args) {
+  exec('git', args, { cwd: sfdxProjectDir });
+}
+
+/** Run an `sf` command and return its stdout (used for `--json` output). */
+function captureSf(args) {
+  try {
+    return execFileSync('sf', args, {
+      cwd: sfdxProjectDir,
+      encoding: 'utf8',
+      stdio: ['inherit', 'pipe', 'inherit'],
+      maxBuffer: 64 * 1024 * 1024
+    });
+  } catch (error) {
+    // sf emits the JSON error payload on stdout even on failure
+    const details = error.stdout || error.message;
+    fail(`sf ${args[0]} ${args[1]} failed:\n${details}`);
+  }
+}
+
+function exec(command, args, options = {}) {
+  execFileSync(command, args, { stdio: 'inherit', maxBuffer: 64 * 1024 * 1024, ...options });
+}
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    fail(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+function fail(message) {
+  console.error(`\nError: ${message}`);
+  process.exit(1);
+}

apps/jetstream-canvas/src/controllers/preferences.canvas.controller.ts

@@ -18,11 +18,13 @@ const FIELD = {
 
 const ALL_FIELDS = Object.values(FIELD).join(', ');
 
+const COLOR_SCHEMES = ['light', 'dark', 'system'] as const;
+
 const PreferencesBodySchema = z.object({
   preferences: z.object({
     skipFrontdoorLogin: z.boolean().optional(),
     recordSyncEnabled: z.boolean().optional(),
-    colorScheme: z.enum(['light', 'dark', 'system']).optional(),
+    colorScheme: z.enum(COLOR_SCHEMES).optional(),
     soqlQueryFormatOptions: SoqlQueryFormatOptionsSchema.optional(),
   }),
 });
@@ -48,12 +50,17 @@ interface CustomSettingRecord {
   [key: string]: unknown;
 }
 
+/** The custom setting field is free text, so guard against unexpected values (manual edits, legacy data) */
+function toColorScheme(value: unknown): ColorScheme | undefined {
+  return COLOR_SCHEMES.includes(value as ColorScheme) ? (value as ColorScheme) : undefined;
+}
+
 /** Maps a Salesforce custom setting record to our app preferences shape */
 function recordToPreferences(record: CustomSettingRecord) {
   return {
     skipFrontdoorLogin: record[FIELD.skipFrontdoorLogin] as boolean | undefined,
     recordSyncEnabled: record[FIELD.recordSyncEnabled] as boolean | undefined,
-    colorScheme: (record[FIELD.colorScheme] as ColorScheme | undefined) || undefined,
+    colorScheme: toColorScheme(record[FIELD.colorScheme]),
     soqlQueryFormatOptions: {
       numIndent: record[FIELD.numIndent] as number | undefined,
       fieldMaxLineLength: record[FIELD.fieldMaxLineLength] as number | undefined,