climaybe 3.4.7 → 3.5.0

package/src/lib/branch-protection.js

@@ -0,0 +1,205 @@
+import { execSync, spawnSync } from 'node:child_process';
+import pc from 'picocolors';
+import { getGitHubRepoSpec, hasGitHubRemote, isGhAvailable } from './github-secrets.js';
+
+export const LIVE_BRANCH_BYPASS_USERS = ['shopify[bot]', 'github-actions[bot]', 'actions-user'];
+
+function runGh(args, cwd = process.cwd(), input = null) {
+  return spawnSync('gh', args, {
+    cwd,
+    input: input == null ? undefined : input,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+function remoteBranchExists(branch, cwd = process.cwd()) {
+  try {
+    execSync(`git ls-remote --exit-code --heads origin ${branch}`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isNotFoundError(result) {
+  const text = `${result?.stdout || ''} ${result?.stderr || ''}`;
+  return /404|not found|branch not found/i.test(text);
+}
+
+export function getBranchProtectionTargets(mode = 'single', aliases = []) {
+  const liveBranches = aliases.map((alias) => `live-${alias}`);
+  if (mode === 'multi') {
+    return {
+      protect: liveBranches,
+      unprotect: ['main'],
+    };
+  }
+  return {
+    protect: ['main'],
+    unprotect: liveBranches,
+  };
+}
+
+export function buildBranchProtectionPayload({ allowShopifyBypass = false } = {}) {
+  return {
+    required_status_checks: null,
+    enforce_admins: true,
+    required_pull_request_reviews: {
+      dismiss_stale_reviews: false,
+      require_code_owner_reviews: false,
+      required_approving_review_count: 0,
+      require_last_push_approval: false,
+      bypass_pull_request_allowances: {
+        users: allowShopifyBypass ? LIVE_BRANCH_BYPASS_USERS : [],
+        teams: [],
+        apps: [],
+      },
+    },
+    restrictions: null,
+    required_linear_history: false,
+    allow_force_pushes: false,
+    allow_deletions: false,
+    block_creations: false,
+    required_conversation_resolution: true,
+    lock_branch: false,
+    allow_fork_syncing: true,
+  };
+}
+
+function protectBranch({ repo, branch, allowShopifyBypass = false, cwd = process.cwd() }) {
+  const path = `repos/${repo}/branches/${branch}/protection`;
+  const payload = JSON.stringify(buildBranchProtectionPayload({ allowShopifyBypass }));
+  const result = runGh(
+    [
+      'api',
+      '--method',
+      'PUT',
+      '-H',
+      'Accept: application/vnd.github+json',
+      path,
+      '--input',
+      '-',
+    ],
+    cwd,
+    payload
+  );
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || `gh api failed for ${branch}`).trim());
+  }
+}
+
+function unprotectBranch({ repo, branch, cwd = process.cwd() }) {
+  const path = `repos/${repo}/branches/${branch}/protection`;
+  const result = runGh(
+    [
+      'api',
+      '--method',
+      'DELETE',
+      '-H',
+      'Accept: application/vnd.github+json',
+      path,
+    ],
+    cwd
+  );
+  if (result.status !== 0 && !isNotFoundError(result)) {
+    throw new Error((result.stderr || result.stdout || `gh api failed for ${branch}`).trim());
+  }
+}
+
+export function syncBranchProtection({ mode = 'single', aliases = [], cwd = process.cwd() } = {}) {
+  if (!hasGitHubRemote(cwd)) {
+    return { skipped: 'no_github_remote', applied: [], removed: [], pending: [], failed: [] };
+  }
+  if (!isGhAvailable()) {
+    return { skipped: 'gh_unavailable', applied: [], removed: [], pending: [], failed: [] };
+  }
+
+  const repo = getGitHubRepoSpec(cwd);
+  if (!repo) {
+    return { skipped: 'repo_parse_failed', applied: [], removed: [], pending: [], failed: [] };
+  }
+
+  const { protect, unprotect } = getBranchProtectionTargets(mode, aliases);
+  const applied = [];
+  const removed = [];
+  const pending = [];
+  const failed = [];
+
+  for (const branch of unprotect) {
+    if (!remoteBranchExists(branch, cwd)) continue;
+    try {
+      unprotectBranch({ repo, branch, cwd });
+      removed.push(branch);
+    } catch (err) {
+      failed.push({ branch, action: 'unprotect', message: err.message });
+    }
+  }
+
+  for (const branch of protect) {
+    if (!remoteBranchExists(branch, cwd)) {
+      pending.push(branch);
+      continue;
+    }
+    try {
+      const isLive = /^live-/.test(branch);
+      protectBranch({
+        repo,
+        branch,
+        allowShopifyBypass: isLive,
+        cwd,
+      });
+      applied.push(branch);
+    } catch (err) {
+      failed.push({ branch, action: 'protect', message: err.message });
+    }
+  }
+
+  return { skipped: null, applied, removed, pending, failed };
+}
+
+export function logBranchProtectionResult(result, mode = 'single') {
+  if (result.skipped === 'no_github_remote') {
+    console.log(pc.dim('  Branch protection: skipped (no GitHub origin remote).'));
+    return;
+  }
+  if (result.skipped === 'gh_unavailable') {
+    console.log(pc.dim('  Branch protection: skipped (gh CLI unavailable or not authenticated).'));
+    return;
+  }
+  if (result.skipped === 'repo_parse_failed') {
+    console.log(pc.dim('  Branch protection: skipped (could not resolve owner/repo from origin).'));
+    return;
+  }
+
+  if (result.removed.length > 0) {
+    console.log(pc.green(`  Branch protection removed: ${result.removed.join(', ')}`));
+  }
+  if (result.applied.length > 0) {
+    console.log(pc.green(`  Branch protection applied: ${result.applied.join(', ')}`));
+  }
+  if (result.pending.length > 0) {
+    console.log(
+      pc.yellow(
+        `  Branch protection pending for non-remote branch(es): ${result.pending.join(', ')} (push branches, then run "climaybe ensure-branches")`
+      )
+    );
+  }
+  if (result.failed.length > 0) {
+    for (const item of result.failed) {
+      console.log(pc.red(`  Branch protection ${item.action} failed for ${item.branch}: ${item.message}`));
+    }
+  }
+  if (
+    result.applied.length === 0 &&
+    result.removed.length === 0 &&
+    result.pending.length === 0 &&
+    result.failed.length === 0
+  ) {
+    console.log(pc.dim(`  Branch protection: no changes needed (${mode}-store mode).`));
+  }
+}

package/src/lib/config.js

@@ -261,13 +261,23 @@ export function isCommitlintEnabled(cwd = process.cwd()) {
 }
 
 /**
- * Whether bundled Cursor rules, skills, and subagents were installed (init or add-cursor).
+ * Whether the bundled AI ruleset (rules, skills, subagents) was installed (init or add-cursor).
  */
 export function isCursorSkillsEnabled(cwd = process.cwd()) {
   const config = readConfig(cwd);
   return config?.cursor_skills === true;
 }
 
+/**
+ * Editors bridged to the .config/ai ruleset. Falls back to ['cursor'] for configs
+ * written before the multi-editor option existed.
+ */
+export function getAiEditors(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  const editors = config?.ai_editors;
+  return Array.isArray(editors) && editors.length > 0 ? editors : ['cursor'];
+}
+
 /**
  * Add a store entry to the config.
  * Returns the updated config.

package/src/lib/cursor-bundle.js

@@ -1,14 +1,64 @@
-import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  lstatSync,
+  rmSync,
+  copyFileSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-/** Bundled Electric Maybe Cursor rules, skills, and subagents (shipped under src/cursor/). */
+/** Bundled Electric Maybe AI rules, skills, and subagents (shipped under src/cursor/). */
 const BUNDLE_ROOT = join(__dirname, '..', 'cursor');
 
 const SKIP_NAMES = new Set(['.DS_Store']);
 
+/** Single source of truth for AI/editor config inside the target repo. */
+export const AI_CONFIG_DIR = '.config/ai';
+
+/** Canonical entry doc that the flat editor files (AGENTS.md, CLAUDE.md, …) point at. */
+export const AI_RULES_ENTRY = `${AI_CONFIG_DIR}/rules.md`;
+
+/**
+ * Editor "bridges" — each maps an editor's expected path to the shared source of truth.
+ * `kind: 'dir'` links a folder (the editor reads rules/skills/agents from it);
+ * `kind: 'file'` links a single instructions file to the combined rules entry doc.
+ */
+export const EDITOR_BRIDGES = {
+  cursor: { label: 'Cursor', bridges: [{ link: '.cursor', target: AI_CONFIG_DIR, kind: 'dir' }] },
+  windsurf: { label: 'Windsurf', bridges: [{ link: '.windsurf', target: AI_CONFIG_DIR, kind: 'dir' }] },
+  cline: { label: 'Cline / Roo Code', bridges: [{ link: '.clinerules', target: AI_CONFIG_DIR, kind: 'dir' }] },
+  claude: { label: 'Claude Code', bridges: [{ link: 'CLAUDE.md', target: AI_RULES_ENTRY, kind: 'file' }] },
+  copilot: {
+    label: 'GitHub Copilot / VS Code',
+    bridges: [{ link: '.github/copilot-instructions.md', target: AI_RULES_ENTRY, kind: 'file' }],
+  },
+  agents: { label: 'Other editors (AGENTS.md)', bridges: [{ link: 'AGENTS.md', target: AI_RULES_ENTRY, kind: 'file' }] },
+};
+
+const RULES_ENTRY_CONTENT = `# Electric Maybe — AI ruleset
+
+This file is the shared entry point for AI/editor assistants working in this repo.
+The real content lives in \`${AI_CONFIG_DIR}/\`; every editor reads it through a bridge
+file or symlink, so there is a single source of truth and nothing to duplicate.
+
+- **Rules:** \`${AI_CONFIG_DIR}/rules/\` — start with \`00-rule-index.mdc\`
+- **Skills:** \`${AI_CONFIG_DIR}/skills/\`
+- **Agents / subagents:** \`${AI_CONFIG_DIR}/agents/\`
+
+Edit files under \`${AI_CONFIG_DIR}/\` only. Bridges (\`.cursor\`, \`.windsurf\`,
+\`.clinerules\`, \`AGENTS.md\`, \`CLAUDE.md\`, \`.github/copilot-instructions.md\`) point back
+here, so a change is picked up by every editor at once.
+`;
+
+const isWindows = process.platform === 'win32';
+
 /**
  * Recursively copy directory tree; skips junk files (e.g. .DS_Store).
  * @param {string} src
@@ -29,21 +79,109 @@ function copyTree(src, dest) {
   }
 }
 
+function removeIfExists(path) {
+  try {
+    lstatSync(path);
+    rmSync(path, { recursive: true, force: true });
+  } catch {
+    // nothing to remove
+  }
+}
+
+/**
+ * Create one editor bridge to the shared source of truth.
+ * Prefers a symlink (so there is zero duplication); falls back to copying when the
+ * platform refuses symlinks (e.g. Windows without privilege).
+ * @returns {{ link: string, mode: 'symlink' | 'copy' }}
+ */
+function createBridge(cwd, { link, target, kind }) {
+  const linkPath = join(cwd, link);
+  const absTarget = join(cwd, target);
+  mkdirSync(dirname(linkPath), { recursive: true });
+  removeIfExists(linkPath);
+
+  try {
+    if (kind === 'dir') {
+      // Junctions on Windows need an absolute target and no privilege; POSIX uses a
+      // relative symlink so the repo stays portable when moved or cloned.
+      const symType = isWindows ? 'junction' : 'dir';
+      const symTarget = isWindows ? absTarget : relative(dirname(linkPath), absTarget);
+      symlinkSync(symTarget, linkPath, symType);
+    } else {
+      const symTarget = relative(dirname(linkPath), absTarget);
+      symlinkSync(symTarget, linkPath, 'file');
+    }
+    return { link, mode: 'symlink' };
+  } catch {
+    // Fallback: copy so the file/folder still exists even without symlink support.
+    if (kind === 'dir') {
+      copyTree(absTarget, linkPath);
+    } else {
+      copyFileSync(absTarget, linkPath);
+    }
+    return { link, mode: 'copy' };
+  }
+}
+
 /**
- * Install bundled `.cursor/rules`, `.cursor/skills`, and `.cursor/agents` into the target repo.
+ * Install the Electric Maybe AI bundle into `.config/ai/` (single source of truth) and
+ * create bridge files/symlinks for the chosen editors.
+ *
  * @param {string} [cwd] - Working directory (default process.cwd())
- * @returns {boolean} - false if bundle source is missing (broken install)
+ * @param {{ editors?: string[] }} [opts] - Editor keys from EDITOR_BRIDGES (default: ['cursor'])
+ * @returns {{ ok: boolean, editors: string[], bridges: Array<{link: string, mode: string}> }}
  */
-export function scaffoldCursorBundle(cwd = process.cwd()) {
+export function scaffoldAiConfig(cwd = process.cwd(), { editors = ['cursor'] } = {}) {
   const rulesSrc = join(BUNDLE_ROOT, 'rules');
   const skillsSrc = join(BUNDLE_ROOT, 'skills');
   const agentsSrc = join(BUNDLE_ROOT, 'agents');
   if (!existsSync(rulesSrc) || !existsSync(skillsSrc) || !existsSync(agentsSrc)) {
-    return false;
+    return { ok: false, editors: [], bridges: [] };
+  }
+
+  const aiRoot = join(cwd, AI_CONFIG_DIR);
+  copyTree(rulesSrc, join(aiRoot, 'rules'));
+  copyTree(skillsSrc, join(aiRoot, 'skills'));
+  copyTree(agentsSrc, join(aiRoot, 'agents'));
+  writeFileSync(join(cwd, AI_RULES_ENTRY), RULES_ENTRY_CONTENT, 'utf-8');
+
+  const selected = editors.filter((key) => EDITOR_BRIDGES[key]);
+  const bridges = [];
+  for (const key of selected) {
+    for (const bridge of EDITOR_BRIDGES[key].bridges) {
+      bridges.push(createBridge(cwd, bridge));
+    }
+  }
+  return { ok: true, editors: selected, bridges };
+}
+
+/**
+ * Pretty-print the outcome of scaffoldAiConfig() with picocolors. Lazily imported so
+ * this module stays usable in non-CLI contexts (tests) without color deps.
+ * @param {ReturnType<typeof scaffoldAiConfig>} result
+ * @param {{ pc: import('picocolors').Picocolors }} deps
+ */
+export function logAiConfigResult(result, { pc }) {
+  if (!result.ok) {
+    console.log(pc.yellow('  AI ruleset not found in this climaybe install (skipped).'));
+    return;
+  }
+  console.log(pc.green(`  Electric Maybe AI ruleset → ${AI_CONFIG_DIR}/ (rules, skills, agents)`));
+  if (result.bridges.length > 0) {
+    const links = result.bridges.map((b) => (b.mode === 'copy' ? `${b.link} (copy)` : b.link));
+    console.log(pc.dim(`  Editor bridges: ${links.join(', ')}`));
+    if (result.bridges.some((b) => b.mode === 'copy')) {
+      console.log(pc.dim('  (Some bridges were copied because this platform blocked symlinks.)'));
+    }
   }
-  const cursorRoot = join(cwd, '.cursor');
-  copyTree(rulesSrc, join(cursorRoot, 'rules'));
-  copyTree(skillsSrc, join(cursorRoot, 'skills'));
-  copyTree(agentsSrc, join(cursorRoot, 'agents'));
-  return true;
+  console.log(pc.dim(`  Edit rules in ${AI_CONFIG_DIR}/ — every bridged editor reads the same files.`));
+}
+
+/**
+ * Back-compat wrapper for callers that only want the Cursor bridge.
+ * @param {string} [cwd]
+ * @returns {boolean} false if bundle source is missing (broken install)
+ */
+export function scaffoldCursorBundle(cwd = process.cwd()) {
+  return scaffoldAiConfig(cwd, { editors: ['cursor'] }).ok;
 }

package/src/lib/git.js

@@ -119,6 +119,18 @@ export function hasOriginRemote(cwd = process.cwd()) {
   }
 }
 
+/**
+ * Add an `origin` remote from an "owner/repo" slug for the given host ('github' | 'gitlab').
+ * No-op (returns the existing URL) if origin already exists. Returns the remote URL on success.
+ */
+export function addOriginRemote(slug, host = 'github', cwd = process.cwd()) {
+  if (hasOriginRemote(cwd)) return exec('git remote get-url origin', cwd);
+  const base = host === 'gitlab' ? 'https://gitlab.com' : 'https://github.com';
+  const url = `${base}/${slug}.git`;
+  exec(`git remote add origin ${url}`, cwd);
+  return url;
+}
+
 /**
  * Push branches to origin if remote exists.
  */

package/src/lib/prompts.js

@@ -142,13 +142,28 @@ export async function promptBuildWorkflows() {
   const { enableBuildWorkflows } = await prompts({
     type: 'confirm',
     name: 'enableBuildWorkflows',
-    message: 'Enable build + Lighthouse workflows?',
+    message: 'Enable build workflows? (bundle _scripts JS + compile Tailwind in CI)',
     initial: true,
   });
 
   return !!enableBuildWorkflows;
 }
 
+/**
+ * Ask whether Lighthouse CI should run as part of the build pipeline.
+ * Only meaningful when build workflows are enabled (Lighthouse runs after the build).
+ */
+export async function promptLighthouseWorkflows() {
+  const { enableLighthouseWorkflows } = await prompts({
+    type: 'confirm',
+    name: 'enableLighthouseWorkflows',
+    message: 'Also run Lighthouse CI on the staging branch? (performance + a11y budget)',
+    initial: true,
+  });
+
+  return !!enableLighthouseWorkflows;
+}
+
 /**
  * Ask whether to scaffold local theme dev-kit files (configs, ignores, editor tasks).
  */
@@ -193,20 +208,61 @@ export async function promptCommitlint() {
 }
 
 /**
- * Ask whether to install bundled Cursor rules, skills, and subagents (.cursor/rules, .cursor/skills, .cursor/agents).
+ * Ask whether to reconcile GitHub branch protection for the configured mode
+ * (protect main in single-store, or each live-<alias> in multi-store).
+ */
+export async function promptBranchProtection() {
+  const { enableBranchProtection } = await prompts({
+    type: 'confirm',
+    name: 'enableBranchProtection',
+    message:
+      'Set up GitHub branch protection? (require PRs on production branches; needs a GitHub origin + authenticated gh CLI)',
+    initial: true,
+  });
+
+  return !!enableBranchProtection;
+}
+
+/**
+ * Ask whether to install the bundled Electric Maybe AI ruleset (rules, skills, subagents)
+ * into a single `.config/ai/` source of truth.
  */
 export async function promptCursorSkills() {
   const { enableCursorSkills } = await prompts({
     type: 'confirm',
     name: 'enableCursorSkills',
-    message:
-      'Install Electric Maybe Cursor bundle? (rules, skills, subagents e.g. theme-translator in .cursor/)',
+    message: 'Install the Electric Maybe AI ruleset? (rules, skills, subagents in .config/ai/)',
     initial: true,
   });
 
   return !!enableCursorSkills;
 }
 
+/**
+ * Ask which editors to bridge to the shared `.config/ai/` ruleset. Returns an array of
+ * editor keys understood by EDITOR_BRIDGES in cursor-bundle.js. Defaults to Cursor.
+ */
+export async function promptAiEditors() {
+  const { editors } = await prompts({
+    type: 'multiselect',
+    name: 'editors',
+    message: 'Which editors should read the ruleset? (bridged to .config/ai/, no duplication)',
+    instructions: false,
+    hint: '- space to toggle, enter to confirm',
+    choices: [
+      { title: 'Cursor', value: 'cursor', selected: true },
+      { title: 'Claude Code (CLAUDE.md)', value: 'claude', selected: true },
+      { title: 'GitHub Copilot / VS Code', value: 'copilot', selected: false },
+      { title: 'Windsurf', value: 'windsurf', selected: false },
+      { title: 'Cline / Roo Code', value: 'cline', selected: false },
+      { title: 'Other editors (AGENTS.md)', value: 'agents', selected: false },
+    ],
+  });
+
+  // `prompts` returns undefined on cancel / non-TTY; fall back to Cursor.
+  return Array.isArray(editors) && editors.length > 0 ? editors : ['cursor'];
+}
+
 /**
  * Prompt for package.json name when creating a new package.json.
  */
@@ -287,6 +343,44 @@ export async function promptConfigureCISecrets() {
   return host ?? 'skip';
 }
 
+/**
+ * When no GitHub/GitLab origin remote exists, ask how to proceed at the CI secrets step.
+ * Returns 'add' (prompt for owner/repo and add origin), or 'skip' (do it later).
+ */
+export async function promptNoRemoteAction(hostName) {
+  const { action } = await prompts({
+    type: 'select',
+    name: 'action',
+    message: `CI secrets need a ${hostName} repo, but this folder has no "origin" remote. What now?`,
+    choices: [
+      { title: `Add an ${hostName} remote now and continue`, value: 'add' },
+      { title: 'Skip for now (add secrets later in repo settings)', value: 'skip' },
+    ],
+    initial: 0,
+  });
+  return action ?? 'skip';
+}
+
+/**
+ * Prompt for an owner/repo slug to wire up as the git origin remote.
+ * Returns a trimmed "owner/repo" string, or null if skipped/invalid.
+ */
+export async function promptOwnerRepo(hostName) {
+  const { slug } = await prompts({
+    type: 'text',
+    name: 'slug',
+    message: `${hostName} repository (owner/repo)`,
+    validate: (v) => {
+      const s = String(v || '').trim();
+      if (!s) return 'Enter owner/repo, or press Esc to skip';
+      if (!/^[^/\s]+\/[^/\s]+$/.test(s)) return 'Use the form owner/repo (e.g. electricmaybe/climaybe)';
+      return true;
+    },
+  });
+  const s = String(slug || '').trim();
+  return /^[^/\s]+\/[^/\s]+$/.test(s) ? s : null;
+}
+
 /**
  * Ask whether to update existing CI secrets (when some are already set). Returns true to update, false to skip.
  */

package/src/lib/theme-dev-kit.js

@@ -17,6 +17,10 @@ _scripts
 .cursor
 .cursorrules
 .config
+.windsurf
+.clinerules
+AGENTS.md
+CLAUDE.md
 .backups
 .github
 .vscode

package/src/workflows/build/build-pipeline.yml

@@ -10,6 +10,11 @@ on:
       - 'docs/**'
       - '.github/**'
       - '.cursor/**'
+      - '.config/**'
+      - '.windsurf/**'
+      - '.clinerules/**'
+      - 'AGENTS.md'
+      - 'CLAUDE.md'
       - '.claude/**'
       - '.eser/**'
       - 'README*'
@@ -43,11 +48,20 @@ jobs:
       SHOP_ACCESS_TOKEN: ${{ secrets.SHOP_ACCESS_TOKEN }}
       LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
     steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
       - name: Check if Lighthouse CI should run
         id: check
         run: |
           SKIP_REASONS=()
           BR="${{ github.ref_name }}"
+          # Lighthouse is opt-in via climaybe.config.json (lighthouse_workflows).
+          # Default to enabled when the flag is absent (older configs).
+          LH_ENABLED=$(node -e "try{process.stdout.write(require('./climaybe.config.json').lighthouse_workflows===false?'false':'true')}catch(e){process.stdout.write('true')}" 2>/dev/null || echo true)
+          if [[ "$LH_ENABLED" != "true" ]]; then
+            SKIP_REASONS+=("Lighthouse disabled in climaybe.config.json (lighthouse_workflows: false)")
+          fi
           if [[ "$BR" == "staging" ]]; then
             :
           else

package/src/workflows/multi/pr-to-live.yml

@@ -124,7 +124,7 @@ jobs:
             if [ -n "$STAGING_THEME_ID" ]; then
               PREVIEW_URL="https://${DOMAIN}?preview_theme_id=${STAGING_THEME_ID}"
               CUSTOMIZE_URL="https://${DOMAIN}/admin/themes/${STAGING_THEME_ID}/editor"
-              BODY="${BODY}"$'\n\n'"**Customize URL (Staging Theme):** ${CUSTOMIZE_URL}"$'\n'"**Preview URL (Staging Theme):** ${PREVIEW_URL}"
+              BODY="${BODY}"$'\n\n'"[${ALIAS} preview](${PREVIEW_URL}) · [customize](${CUSTOMIZE_URL})"
             else
               BODY="${BODY}"$'\n\n'"⚠️ Staging theme link not found for branch \`${STAGING}\`."$'\n'"Expected naming: \`${REPO_NAME}/${STAGING}\` (or suffix match \`/${STAGING}\`)."
             fi

package/src/workflows/preview/reusable-comment-on-pr.yml

@@ -107,7 +107,7 @@ jobs:
                 if (host && tid) {
                   const previewUrl = `https://${host}?preview_theme_id=${tid}`;
                   const customizeUrl = `https://${host}/admin/themes/${tid}/editor`;
-                  parts.push('', `**${alias}**`, `- Customize: ${customizeUrl}`, `- Preview: ${previewUrl}`);
+                  parts.push('', `- [${alias} preview](${previewUrl}) · [customize](${customizeUrl})`);
                 }
               }
             } else if (useFragments) {
@@ -128,8 +128,11 @@ jobs:
                 previewUrl = `https://${storeDomain}?preview_theme_id=${themeId}`;
                 customizeUrl = `https://${storeDomain}/admin/themes/${themeId}/editor`;
               }
-              if (customizeUrl) parts.push('', `**Customize URL:** ${customizeUrl}`);
-              if (previewUrl) parts.push('', `**Preview URL:** ${previewUrl}`);
+              if (previewUrl) {
+                const links = [`[theme preview](${previewUrl})`];
+                if (customizeUrl) links.push(`[customize](${customizeUrl})`);
+                parts.push('', links.join(' · '));
+              }
               if (shareOutput.trim()) {
                 parts.push('', '### Share Output', '```', shareOutput, '```');
               }