climaybe 1.5.2 → 1.6.1

package/README.md

@@ -2,6 +2,13 @@
 
 Shopify CI/CD CLI — scaffolds GitHub Actions workflows, branch strategy, and store config for single-store and multi-store theme repositories.
 
+**Commit linting and AI-assisted commits are available as optional setup steps:**
+
+- **Conventional commit linting:** During `climaybe init`, you can choose to automatically install and configure [commitlint](https://commitlint.js.org/) and [Husky](https://typicode.github.io/husky) to enforce [Conventional Commits](https://www.conventionalcommits.org/) in your theme repository.
+- **Cursor AI commit skill:** You can also opt-in to installing the [Cursor AI commit skill](https://cursor.so/) (`.cursor/skills/commit/SKILL.md`) for AI-assisted, conventional commit message support in your project.
+
+Both options streamline commit message quality and team workflows but are fully optional during setup.
+
 ## Install
 
 Install in your theme repo (project-only, no global install):
@@ -34,10 +41,13 @@ Interactive setup that configures your repo for CI/CD.
 3. Asks if you want to add more stores
 4. Asks whether to enable optional **preview + cleanup** workflows
 5. Asks whether to enable optional **build + Lighthouse** workflows
-6. Based on store count, sets up **single-store** or **multi-store** mode
-7. Writes `package.json` config
-8. Scaffolds GitHub Actions workflows
-9. Creates git branches and store directories (multi-store)
+6. Asks whether to enable **commitlint + Husky** (enforce [conventional commits](https://www.conventionalcommits.org/) on `git commit`)
+7. Asks whether to add **Cursor commit skill** to the project (`.cursor/skills/commit/SKILL.md`) for AI-assisted conventional commits
+8. Based on store count, sets up **single-store** or **multi-store** mode
+9. Writes `package.json` config
+10. Scaffolds GitHub Actions workflows
+11. Creates git branches and store directories (multi-store)
+12. Optionally installs commitlint, Husky, and the Cursor skill
 
 ### `climaybe add-store`
 
@@ -91,6 +101,22 @@ npx climaybe update-workflows
 
 Useful after updating the CLI to get the latest workflow improvements.
 
+### `climaybe setup-commitlint`
+
+Set up **only** commitlint + Husky (conventional commits enforced on `git commit`). Use this if you skipped it at init or want to add it later.
+
+```bash
+npx climaybe setup-commitlint
+```
+
+### `climaybe add-cursor-skill`
+
+Add **only** the Cursor commit skill to this project (`.cursor/skills/commit/SKILL.md`). Use this if you skipped it at init or want to add it later.
+
+```bash
+npx climaybe add-cursor-skill
+```
+
 ## Configuration
 
 The CLI writes config into the `config` field of your `package.json`:
@@ -102,6 +128,8 @@ The CLI writes config into the `config` field of your `package.json`:
     "default_store": "voldt-staging.myshopify.com",
     "preview_workflows": true,
     "build_workflows": true,
+    "commitlint": true,
+    "cursor_skills": true,
     "stores": {
       "voldt-staging": "voldt-staging.myshopify.com",
       "voldt-norway": "voldt-norway.myshopify.com"
@@ -149,19 +177,19 @@ Direct pushes to `staging-<store>` or `live-<store>` are automatically synced ba
 
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
-| `release-pr-check.yml` | PR from `staging` to `main` | Generates changelog, creates pre-release patch tag, posts PR comment |
-| `post-merge-tag.yml` | Push to `main` (merged PR) | Staging→main: minor bump (e.g. v3.2.0). Hotfix sync: patch bump (e.g. v3.2.1) |
-| `nightly-hotfix.yml` | Cron 02:00 US Eastern | Tags untagged hotfix commits with patch version |
+| `release-pr-check.yml` | PR from `staging` to `main` | Finds latest tag on main, AI changelog to PR head, creates pre-release patch tag (e.g. v3.1.13) to lock state; posts changelog comment |
+| `post-merge-tag.yml` | Push to `main` (merged PR) | Staging→main only: minor bump from latest tag (e.g. v3.1.13 → v3.2.0). No version in PR title |
+| `nightly-hotfix.yml` | Cron 02:00 US Eastern | Collects commits since latest tag (incl. hotfix backports), AI changelog, patch bump and tag |
 
 ### Multi-store (additional)
 
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
-| `main-to-staging-stores.yml` (main-to-staging-&lt;store&gt;) | Push to `main` | Opens PRs from main to each `staging-<alias>` branch |
-| `stores-to-root.yml` | Push to `staging-*` | Copies `stores/<alias>/` JSONs to repo root |
+| `main-to-staging-stores.yml` (main-to-staging-&lt;store&gt;) | Push to `main` | Merges main into each `staging-<alias>`; root JSONs ignored. For hotfix-backport, skips the store that sent the hotfix; other stores get the merge. Skips only on pure store-sync. |
+| `stores-to-root.yml` | Push to `staging-*` | From main merge: stores→root. From elsewhere (e.g. Shopify): root→stores |
 | `pr-to-live.yml` | After stores-to-root | Opens PR from `staging-<alias>` to `live-<alias>` |
-| `root-to-stores.yml` | Push to `live-*` (hotfix) | Syncs root JSONs back to `stores/<alias>/` |
-| `multistore-hotfix-to-main.yml` | Push to `staging-*` or `live-*` (and after root-to-stores) | Automatically merges store branch into main (no PR); everything is synced back to main |
+| `root-to-stores.yml` | Push to `live-*` | From main merge: stores→root. From elsewhere: root→stores (same as stores-to-root on staging-*) |
+| `multistore-hotfix-to-main.yml` | Push to `staging-*` or `live-*` (and after root-to-stores) | Merges store branch into main (no PR). Skips when push is a merge from main (avoids loop) |
 
 ### Optional preview + cleanup package
 
@@ -189,13 +217,12 @@ Enabled via `climaybe init` prompt (`Enable build + Lighthouse workflows?`).
 
 ## Versioning
 
-- **Version format**: Always three-part (e.g. `v3.2.0`). No two-part tags.
-- **Release merge** (`staging` → `main`): Minor bump (e.g. `v3.1.12` → `v3.2.0`)
-- **Hotfix sync** (`staging-<store>` or `live-<store>` → main via multistore-hotfix-to-main): Patch bump runs immediately (e.g. `v3.2.0` → `v3.2.1`)
-- **Other hotfixes** (direct commit to `main`): Patch bump via nightly workflow or manual run
-- **PR title convention**: `Release v3.2` or `Release v3.2.0` — the workflow normalizes to three-part
-
-All version bumps update `config/settings_schema.json` automatically.
+- **Version format**: Always three-part (e.g. `v3.2.0`). No version in code or PR title; the system infers from tags.
+- **No tags yet?** The system uses `theme_version` from `config/settings_schema.json` (`theme_info`), creates that tag on main (e.g. `v1.0.0`), and continues from there.
+- **Staging → main**: On PR, a pre-release patch tag (e.g. v3.1.13) locks the current minor line; on merge, **minor** bump (e.g. v3.1.13 → v3.2.0).
+- **Non-staging to main** (hotfix backports, direct commits): **Patch** bump only, via **nightly workflow** at 02:00 US Eastern (not at commit time).
+- **Version bump runs only on main** (post-merge-tag and nightly-hotfix). Main-to-staging-stores merges main into each `staging-<alias>` on every push (version bumps and hotfixes). When the push is a hotfix from one store (e.g. live-norway), that store’s staging branch is skipped; other stores’ staging branches still get the merge.
+- Version bumps update `config/settings_schema.json` and, when present, `package.json` `version`.
 
 **Full specification:** For detailed versioning rules, local dev flow, hotfix behavior, and alignment with the external CI/CD doc, see **[CI/CD Reference](docs/CI_CD_REFERENCE.md)**.
 

package/bin/version.txt

@@ -1 +1 @@
-1.5.2
+1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "climaybe",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "description": "Shopify CI/CD CLI — scaffolds workflows, branch strategy, and store config for single-store and multi-store theme repos",
   "type": "module",
   "bin": {
@@ -39,7 +39,21 @@
       "main"
     ],
     "plugins": [
-      "@semantic-release/commit-analyzer",
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "releaseRules": [
+            {
+              "type": "ci",
+              "release": "patch"
+            },
+            {
+              "type": "chore",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
       "@semantic-release/release-notes-generator",
       [
         "@semantic-release/npm",

package/src/commands/add-cursor-skill.js

@@ -0,0 +1,17 @@
+import pc from 'picocolors';
+import { writeConfig } from '../lib/config.js';
+import { scaffoldCursorCommitSkill } from '../lib/commit-tooling.js';
+
+/**
+ * Add only the Cursor commit skill to this project (.cursor/skills/commit/SKILL.md).
+ * Can be run standalone or after init without having chosen Cursor skills at init.
+ */
+export async function addCursorSkillCommand() {
+  console.log(pc.bold('\n  climaybe — Add Cursor commit skill\n'));
+
+  writeConfig({ cursor_skills: true });
+
+  scaffoldCursorCommitSkill();
+  console.log(pc.green('  Cursor commit skill added to .cursor/skills/commit/SKILL.md'));
+  console.log(pc.dim('  Use "commit" or "group and commit" in Cursor to get conventional-commit assistance.\n'));
+}

package/src/commands/init.js

@@ -4,6 +4,8 @@ import {
   promptStoreLoop,
   promptPreviewWorkflows,
   promptBuildWorkflows,
+  promptCommitlint,
+  promptCursorSkills,
   promptConfigureCISecrets,
   promptUpdateExistingSecrets,
   promptSecretValue,
@@ -13,6 +15,7 @@ import { readConfig, writeConfig } from '../lib/config.js';
 import { ensureGitRepo, ensureInitialCommit, ensureStagingBranch, createStoreBranches, getSuggestedTagForRelease } from '../lib/git.js';
 import { scaffoldWorkflows } from '../lib/workflows.js';
 import { createStoreDirectories } from '../lib/store-sync.js';
+import { scaffoldCommitlint, scaffoldCursorCommitSkill } from '../lib/commit-tooling.js';
 import {
   isGhAvailable,
   hasGitHubRemote,
@@ -38,6 +41,8 @@ async function runInitFlow() {
   const mode = stores.length > 1 ? 'multi' : 'single';
   const enablePreviewWorkflows = await promptPreviewWorkflows();
   const enableBuildWorkflows = await promptBuildWorkflows();
+  const enableCommitlint = await promptCommitlint();
+  const enableCursorSkills = await promptCursorSkills();
 
   console.log(pc.dim(`\n  Mode: ${mode}-store (${stores.length} store(s))`));
 
@@ -47,6 +52,8 @@ async function runInitFlow() {
     default_store: stores[0].domain,
     preview_workflows: enablePreviewWorkflows,
     build_workflows: enableBuildWorkflows,
+    commitlint: enableCommitlint,
+    cursor_skills: enableCursorSkills,
     stores: {},
   };
 
@@ -80,6 +87,20 @@ async function runInitFlow() {
     includeBuild: enableBuildWorkflows,
   });
 
+  // 7. Optional commitlint + Husky and Cursor commit skill
+  if (enableCommitlint) {
+    console.log(pc.dim('  Setting up commitlint + Husky...'));
+    if (scaffoldCommitlint()) {
+      console.log(pc.green('  commitlint + Husky installed (conventional commits enforced on git commit).'));
+    } else {
+      console.log(pc.yellow('  commitlint setup failed or skipped (run npm install manually).'));
+    }
+  }
+  if (enableCursorSkills) {
+    scaffoldCursorCommitSkill();
+    console.log(pc.green('  Cursor commit skill added to .cursor/skills/commit/SKILL.md'));
+  }
+
   // Done
   console.log(pc.bold(pc.green('\n  Setup complete!\n')));
 
@@ -95,6 +116,8 @@ async function runInitFlow() {
   }
   console.log(pc.dim(`  Preview workflows: ${enablePreviewWorkflows ? 'enabled' : 'disabled'}`));
   console.log(pc.dim(`  Build workflows: ${enableBuildWorkflows ? 'enabled' : 'disabled'}`));
+  console.log(pc.dim(`  commitlint + Husky: ${enableCommitlint ? 'enabled' : 'disabled'}`));
+  console.log(pc.dim(`  Cursor commit skill: ${enableCursorSkills ? 'added' : 'skipped'}`));
 
   const suggestedTag = getSuggestedTagForRelease();
   const tagLabel = suggestedTag === 'v1.0.0' ? 'Tag your first release' : 'Tag your next release';

package/src/commands/setup-commitlint.js

@@ -0,0 +1,21 @@
+import pc from 'picocolors';
+import { writeConfig } from '../lib/config.js';
+import { scaffoldCommitlint } from '../lib/commit-tooling.js';
+
+/**
+ * Set up commitlint + Husky only (conventional commits on git commit).
+ * Can be run standalone or after init without having chosen commitlint at init.
+ */
+export async function setupCommitlintCommand() {
+  console.log(pc.bold('\n  climaybe — Setup commitlint + Husky\n'));
+
+  writeConfig({ commitlint: true });
+
+  console.log(pc.dim('  Installing commitlint + Husky (conventional commits enforced on git commit)...'));
+  const skipInstall = process.env.CLIMAYBE_SKIP_INSTALL === '1';
+  if (scaffoldCommitlint(process.cwd(), skipInstall ? { skipInstall: true } : {})) {
+    console.log(pc.green('\n  commitlint + Husky are set up. Use conventional commits (e.g. feat: add X, fix: resolve Y).\n'));
+  } else {
+    console.log(pc.yellow('\n  Installation failed or skipped. Run npm install in this repo and try again.\n'));
+  }
+}

package/src/index.js

@@ -5,6 +5,8 @@ import { switchCommand } from './commands/switch.js';
 import { syncCommand } from './commands/sync.js';
 import { updateWorkflowsCommand } from './commands/update-workflows.js';
 import { ensureBranchesCommand } from './commands/ensure-branches.js';
+import { setupCommitlintCommand } from './commands/setup-commitlint.js';
+import { addCursorSkillCommand } from './commands/add-cursor-skill.js';
 
 /**
  * Create the CLI program (for testing and for run).
@@ -57,6 +59,16 @@ export function createProgram(version = '0.0.0', packageDir = '') {
     .description('Create missing staging and per-store branches from current HEAD (then push)')
     .action(ensureBranchesCommand);
 
+  program
+    .command('setup-commitlint')
+    .description('Set up only commitlint + Husky (conventional commits on git commit)')
+    .action(setupCommitlintCommand);
+
+  program
+    .command('add-cursor-skill')
+    .description('Add only the Cursor commit skill to this project (.cursor/skills/commit)')
+    .action(addCursorSkillCommand);
+
   return program;
 }
 

package/src/lib/commit-tooling.js

@@ -0,0 +1,110 @@
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { readPkg, writePkg } from './config.js';
+
+const COMMITLINT_DEPS = {
+  '@commitlint/cli': '^20.4.4',
+  '@commitlint/config-conventional': '^20.4.4',
+  husky: '^9.1.7',
+};
+
+const COMMITLINT_CONFIG = `/** @type {import('@commitlint/types').UserConfig} */
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore'],
+    ],
+    'header-max-length': [2, 'always', 100],
+    'body-max-line-length': [2, 'always', 200],
+  },
+};
+`;
+
+const HUSKY_COMMIT_MSG = `npx --no-install commitlint --edit "$1"
+`;
+
+const CURSOR_COMMIT_SKILL = `---
+name: commit
+description: Groups working-tree changes into logical commits and commits them using conventional commit rules (type, optional scope, subject; commitlint). Use when the user asks to commit, group commits, stage and commit, or write conventional commits.
+---
+
+# Commit (group + conventional)
+
+Group changes by purpose, then commit each group with a valid conventional message so commitlint and semantic-release stay happy.
+
+## Workflow
+
+1. **Inspect** — Get full picture of changes (git status, git diff).
+2. **Group** — Partition by type: feat, fix, docs, style, refactor, perf, test, build, ci, chore.
+3. **Commit each group** — type(scope): subject, imperative, lowercase, no period, ≤100 chars.
+4. **Validate** — commit-msg hook will reject invalid messages.
+
+## Message rules (commitlint)
+
+- **Types:** feat, fix, docs, style, refactor, perf, test, build, ci, chore.
+- **Header:** type(scope): subject — subject max 100 chars. Body lines max 200.
+- **Imperative, present tense:** "add feature" not "added feature".
+
+## Examples
+
+feat(init): add store alias prompt
+fix(sync): prevent overwrite of unchanged files
+docs: add conventional commit section to CONTRIBUTING
+`;
+
+/**
+ * Scaffold commitlint config, Husky commit-msg hook, and add deps to package.json.
+ * Runs npm install so husky prepare runs and hooks are installed (unless options.skipInstall).
+ * @param {string} [cwd] - Working directory (default process.cwd())
+ * @param {{ skipInstall?: boolean }} [options] - skipInstall: true to skip npm install (e.g. in tests)
+ * @returns {boolean} - true if scaffolded, false if skipped/failed
+ */
+export function scaffoldCommitlint(cwd = process.cwd(), options = {}) {
+  const pkg = readPkg(cwd);
+  if (!pkg) return false;
+
+  const updated = { ...pkg };
+  updated.scripts = { ...pkg.scripts };
+  if (!updated.scripts.prepare) {
+    updated.scripts.prepare = 'husky';
+  } else if (!updated.scripts.prepare.includes('husky')) {
+    updated.scripts.prepare = `husky && ${updated.scripts.prepare}`;
+  }
+  updated.devDependencies = { ...pkg.devDependencies, ...COMMITLINT_DEPS };
+  writePkg(updated, cwd);
+
+  writeFileSync(join(cwd, 'commitlint.config.js'), COMMITLINT_CONFIG, 'utf-8');
+
+  const huskyDir = join(cwd, '.husky');
+  if (!existsSync(huskyDir)) {
+    mkdirSync(huskyDir, { recursive: true });
+  }
+  writeFileSync(join(huskyDir, 'commit-msg'), HUSKY_COMMIT_MSG, 'utf-8');
+
+  if (options.skipInstall) return true;
+  try {
+    execSync('npm install', { cwd, stdio: 'inherit' });
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Scaffold Cursor commit skill into .cursor/skills/commit/SKILL.md.
+ * @param {string} [cwd] - Working directory (default process.cwd())
+ * @returns {boolean} - true if written
+ */
+export function scaffoldCursorCommitSkill(cwd = process.cwd()) {
+  const skillDir = join(cwd, '.cursor', 'skills', 'commit');
+  if (!existsSync(skillDir)) {
+    mkdirSync(skillDir, { recursive: true });
+  }
+  const skillPath = join(skillDir, 'SKILL.md');
+  writeFileSync(skillPath, CURSOR_COMMIT_SKILL, 'utf-8');
+  return true;
+}

package/src/lib/config.js

@@ -97,6 +97,22 @@ export function isBuildWorkflowsEnabled(cwd = process.cwd()) {
   return config?.build_workflows === true;
 }
 
+/**
+ * Whether commitlint + Husky was enabled at init.
+ */
+export function isCommitlintEnabled(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  return config?.commitlint === true;
+}
+
+/**
+ * Whether Cursor commit skill was added at init.
+ */
+export function isCursorSkillsEnabled(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  return config?.cursor_skills === true;
+}
+
 /**
  * Add a store entry to the config.
  * Returns the updated config.

package/src/lib/prompts.js

@@ -148,6 +148,34 @@ export async function promptBuildWorkflows() {
   return !!enableBuildWorkflows;
 }
 
+/**
+ * Ask whether to set up commitlint + Husky (conventional commits enforced on git commit).
+ */
+export async function promptCommitlint() {
+  const { enableCommitlint } = await prompts({
+    type: 'confirm',
+    name: 'enableCommitlint',
+    message: 'Enable commitlint + Husky? (enforce conventional commits on git commit)',
+    initial: true,
+  });
+
+  return !!enableCommitlint;
+}
+
+/**
+ * Ask whether to add Cursor commit skill to the project (.cursor/skills/commit).
+ */
+export async function promptCursorSkills() {
+  const { enableCursorSkills } = await prompts({
+    type: 'confirm',
+    name: 'enableCursorSkills',
+    message: 'Add Cursor commit skill to this project? (AI-assisted conventional commits)',
+    initial: true,
+  });
+
+  return !!enableCursorSkills;
+}
+
 /**
  * Prompt for a single new store (used by add-store command).
  * Takes existing aliases to prevent duplicates.

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

@@ -10,43 +10,43 @@ jobs:
   build:
     uses: ./.github/workflows/reusable-build.yml
 
-  lighthouse-ci:
+  lighthouse-gate:
     runs-on: ubuntu-latest
     needs: [build]
+    outputs:
+      run_lighthouse: ${{ steps.check.outputs.run_lighthouse }}
     env:
       SHOPIFY_STORE_URL: ${{ secrets.SHOPIFY_STORE_URL }}
       SHOP_ACCESS_TOKEN: ${{ secrets.SHOP_ACCESS_TOKEN }}
       LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
     steps:
-      - name: Check conditions and log skip reason
+      - name: Check if Lighthouse CI should run
+        id: check
         run: |
           SKIP_REASONS=()
-
           if [ "${{ github.ref }}" != "refs/heads/main" ] && [ "${{ github.ref }}" != "refs/heads/staging" ]; then
             SKIP_REASONS+=("Not on main or staging branch (current: ${{ github.ref }})")
           fi
-
           if [ -z "$SHOPIFY_STORE_URL" ] || [ -z "$SHOP_ACCESS_TOKEN" ] || [ -z "$LHCI_GITHUB_APP_TOKEN" ]; then
             SKIP_REASONS+=("Missing required secrets: SHOPIFY_STORE_URL, SHOP_ACCESS_TOKEN, or LHCI_GITHUB_APP_TOKEN")
           fi
-
           if [ ${#SKIP_REASONS[@]} -gt 0 ]; then
-            echo "Lighthouse CI skipped"
-            echo "Reasons:"
-            for reason in "${SKIP_REASONS[@]}"; do
-              echo "  - $reason"
-            done
-            exit 0
+            echo "run_lighthouse=false" >> $GITHUB_OUTPUT
+            echo "Lighthouse CI skipped:"
+            for reason in "${SKIP_REASONS[@]}"; do echo "  - $reason"; done
+          else
+            echo "run_lighthouse=true" >> $GITHUB_OUTPUT
           fi
 
-          echo "All conditions met, proceeding with Lighthouse CI"
-
+  lighthouse-ci:
+    runs-on: ubuntu-latest
+    needs: [build, lighthouse-gate]
+    if: needs.lighthouse-gate.outputs.run_lighthouse == 'true'
+    steps:
       - name: Checkout code
-        if: env.SHOPIFY_STORE_URL != '' && env.SHOP_ACCESS_TOKEN != '' && env.LHCI_GITHUB_APP_TOKEN != '' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
         uses: actions/checkout@v4
 
       - name: Lighthouse
-        if: env.SHOPIFY_STORE_URL != '' && env.SHOP_ACCESS_TOKEN != '' && env.LHCI_GITHUB_APP_TOKEN != '' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
         uses: shopify/lighthouse-ci-action@v1
         with:
           store: ${{ secrets.SHOPIFY_STORE_URL }}