climaybe 1.8.1 → 1.9.0

package/README.md

@@ -1,38 +1,54 @@
 # climaybe
 
-Shopify CI/CD CLI — scaffolds GitHub Actions workflows, branch strategy, and store config for single-store and multi-store theme repositories.
+Shopify CLI for **theme CI/CD** (GitHub Actions, branches, multi-store config) and light **app repo** setup. Same install works in theme or app repositories.
 
-**Commit linting and AI-assisted commits are available as optional setup steps:**
+**Commit linting and Cursor bundle (optional in both flows):**
 
-- **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 rules + skills:** You can opt in to installing Electric Maybe’s bundled [Cursor](https://cursor.com/) project rules and agent skills under `.cursor/rules/` and `.cursor/skills/` (Liquid, JS, a11y, commits, changelog, Linear, etc.).
+- **Conventional commit linting:** During `climaybe theme init` or `climaybe app init`, you can install [commitlint](https://commitlint.js.org/) and [Husky](https://typicode.github.io/husky) for [Conventional Commits](https://www.conventionalcommits.org/).
+- **Cursor rules + skills:** Opt in to Electric Maybe’s bundled [Cursor](https://cursor.com/) rules and skills under `.cursor/rules/` and `.cursor/skills/` (themes, JS, a11y, commits, changelog, Linear, etc.).
 
-Both options streamline commit message quality and team workflows but are fully optional during setup.
+## Command layout (Shopify CLI–style)
 
-## Install
+- **`climaybe theme <command>`** — canonical commands for theme repos (workflows, stores, branches).
+- **Same commands at the top level** — `climaybe init` is the same as `climaybe theme init` (backward compatible).
+- **`climaybe app init`** — app repos only: writes `project_type: "app"` in `package.json` config, optional commitlint + Cursor bundle. Does **not** install theme GitHub Actions or store/branch setup.
+- **`climaybe setup-commitlint`** and **`climaybe add-cursor`** — always at the top level (stack-agnostic).
+
+Theme-only commands refuse to run when `package.json` → `config.project_type` is **`app`**.
 
-Install in your theme repo (project-only, no global install):
+## Install
 
 ```bash
-cd your-shopify-theme-repo
+cd your-shopify-theme-repo   # or app repo
 npm install -D climaybe
 ```
 
 Run commands with `npx climaybe` (or add scripts to your `package.json`).
 
-## Quick Start
+## Quick Start (theme)
 
 ```bash
 cd your-shopify-theme-repo
 npm install -D climaybe
 npx climaybe init
+# equivalent: npx climaybe theme init
 ```
 
 The interactive setup will ask for your store URL(s) and configure everything automatically.
 
+## Quick Start (app)
+
+```bash
+cd your-shopify-app-repo
+npm install -D climaybe
+npx climaybe app init
+```
+
+Installs optional commitlint/Husky and Cursor rules/skills only. Use [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) for app development and deployment.
+
 ## Commands
 
-### `climaybe init`
+### `climaybe init` / `climaybe theme init`
 
 Interactive setup that configures your repo for CI/CD.
 
@@ -49,7 +65,11 @@ Interactive setup that configures your repo for CI/CD.
 11. Creates git branches and store directories (multi-store)
 12. Optionally installs commitlint, Husky, and the Cursor bundle (rules + skills)
 
-### `climaybe add-store`
+### `climaybe app init`
+
+Interactive setup for a **Shopify app** repository: optional commitlint + Husky, optional Cursor bundle, and `project_type: "app"` in `package.json` `config`. No theme workflows, stores, or staging/live branches.
+
+### `climaybe add-store` / `climaybe theme add-store`
 
 Add a new store to an existing setup.
 
@@ -62,7 +82,7 @@ npx climaybe add-store
 - Creates `stores/<alias>/` directory structure
 - If store count goes from 1 to 2+, automatically migrates from single to multi-store mode
 
-### `climaybe switch <alias>`
+### `climaybe switch <alias>` / `climaybe theme switch`
 
 Switch your local dev environment to a specific store (multi-store only).
 
@@ -72,7 +92,7 @@ npx climaybe switch voldt-norway
 
 Copies `stores/<alias>/` JSON files to the repo root so you can preview that store locally.
 
-### `climaybe sync [alias]`
+### `climaybe sync [alias]` / `climaybe theme sync`
 
 Sync root JSON files back to a store directory (multi-store only).
 
@@ -82,7 +102,7 @@ npx climaybe sync voldt-norway
 
 If no alias is given, syncs to the default store.
 
-### `climaybe ensure-branches`
+### `climaybe ensure-branches` / `climaybe theme ensure-branches`
 
 Create missing `staging` and per-store branches (`staging-<alias>`, `live-<alias>`) from your current branch (usually `main`). Use when the repo only has `main` (e.g. after a fresh clone) so the main → staging-&lt;store&gt; sync can run.
 
@@ -91,7 +111,7 @@ npx climaybe ensure-branches
 git push origin --all
 ```
 
-### `climaybe update-workflows`
+### `climaybe update-workflows` / `climaybe theme update-workflows`
 
 Refresh GitHub Actions workflows from the latest bundled templates.
 
@@ -225,6 +245,7 @@ Enabled via `climaybe init` prompt (`Enable build + Lighthouse workflows?`; defa
 - **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`.
+- **Safety**: The version-bump workflow fails if the new tag would not be **strictly higher** than the latest merged release tag (semver), so the release line cannot step backward.
 
 **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.8.1
+1.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "climaybe",
-  "version": "1.8.1",
-  "description": "Shopify CI/CD CLI — scaffolds workflows, branch strategy, and store config for single-store and multi-store theme repos",
+  "version": "1.9.0",
+  "description": "Shopify CLI — theme CI/CD (workflows, branches, stores) and app repo helpers; also: commitlint and Cursor rules/skills",
   "type": "module",
   "bin": {
     "climaybe": "bin/cli.js"

package/src/commands/add-store.js

@@ -1,6 +1,14 @@
 import pc from 'picocolors';
 import { promptNewStore, promptConfigureCISecrets, promptUpdateExistingSecrets, promptSecretValue, promptTestThemeToken } from '../lib/prompts.js';
-import { readConfig, addStoreToConfig, getStoreAliases, getMode, isPreviewWorkflowsEnabled, isBuildWorkflowsEnabled } from '../lib/config.js';
+import {
+  readConfig,
+  addStoreToConfig,
+  getStoreAliases,
+  getMode,
+  isPreviewWorkflowsEnabled,
+  isBuildWorkflowsEnabled,
+} from '../lib/config.js';
+import { requireThemeProject } from '../lib/theme-guard.js';
 import { createStoreBranches } from '../lib/git.js';
 import { scaffoldWorkflows } from '../lib/workflows.js';
 import { createStoreDirectories } from '../lib/store-sync.js';
@@ -21,10 +29,12 @@ import {
 export async function addStoreCommand() {
   console.log(pc.bold('\n  climaybe — Add Store\n'));
 
+  if (!requireThemeProject()) return;
+
   // Guard: config must exist
   const config = readConfig();
   if (!config?.stores) {
-    console.log(pc.red('  No climaybe config found. Run "climaybe init" first.\n'));
+    console.log(pc.red('  No climaybe config found. Run "climaybe theme init" (or "climaybe init") first.\n'));
     return;
   }
 

package/src/commands/app-init.js

@@ -0,0 +1,89 @@
+import prompts from 'prompts';
+import pc from 'picocolors';
+import { promptCommitlint, promptCursorSkills } from '../lib/prompts.js';
+import {
+  readConfig,
+  writeConfig,
+  getProjectType,
+  isThemeProjectForAppInit,
+} from '../lib/config.js';
+import { ensureGitRepo, ensureInitialCommit } from '../lib/git.js';
+import { scaffoldCommitlint } from '../lib/commit-tooling.js';
+import { scaffoldCursorBundle } from '../lib/cursor-bundle.js';
+
+/**
+ * Minimal Shopify app repo setup: commitlint, Cursor bundle, project_type in config.
+ * No theme stores, branches, or GitHub Actions theme workflows.
+ */
+async function runAppInitFlow() {
+  const enableCommitlint = await promptCommitlint();
+  const enableCursorSkills = await promptCursorSkills();
+
+  const config = {
+    project_type: 'app',
+    commitlint: enableCommitlint,
+    cursor_skills: enableCursorSkills,
+  };
+
+  writeConfig(config, process.cwd(), { defaultPackageName: 'shopify-app' });
+  console.log(pc.green('  Updated package.json config.'));
+
+  ensureGitRepo();
+  ensureInitialCommit();
+
+  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) {
+    const cursorOk = scaffoldCursorBundle();
+    if (cursorOk) {
+      console.log(pc.green('  Electric Maybe Cursor rules + skills → .cursor/rules, .cursor/skills'));
+    } else {
+      console.log(pc.yellow('  Cursor bundle not found in package (skipped).'));
+    }
+  }
+
+  console.log(pc.bold(pc.green('\n  App setup complete!\n')));
+  console.log(pc.dim('  commitlint + Husky: ' + (enableCommitlint ? 'enabled' : 'disabled')));
+  console.log(pc.dim('  Cursor rules + skills: ' + (enableCursorSkills ? 'installed' : 'skipped')));
+  console.log(pc.dim('\n  Next steps:'));
+  console.log(pc.dim('    Use Shopify CLI (`shopify app dev`, etc.) for app development.'));
+  console.log(pc.dim('    Theme CI/CD workflows are not installed; add your own deployment as needed.\n'));
+}
+
+export async function appInitCommand() {
+  console.log(pc.bold('\n  climaybe — Shopify app setup\n'));
+
+  if (isThemeProjectForAppInit()) {
+    console.log(
+      pc.red(
+        '  This repo looks like a theme project (stores in config or project_type: theme).'
+      )
+    );
+    console.log(pc.dim('  Use: npx climaybe theme init   (or: npx climaybe init)\n'));
+    return;
+  }
+
+  const existing = readConfig();
+  const hasConfig = existing != null && typeof existing === 'object';
+
+  if (hasConfig && getProjectType() === 'app') {
+    const { reinit } = await prompts({
+      type: 'confirm',
+      name: 'reinit',
+      message: 'This repo already has climaybe app config. Re-run setup (merge config and reinstall optional tooling)?',
+      initial: false,
+    });
+    if (!reinit) {
+      console.log(pc.dim('  Use "climaybe setup-commitlint" or "climaybe add-cursor" to refresh tooling.\n'));
+      return;
+    }
+  }
+
+  await runAppInitFlow();
+}

package/src/commands/ensure-branches.js

@@ -1,5 +1,6 @@
 import pc from 'picocolors';
 import { readConfig } from '../lib/config.js';
+import { requireThemeProject } from '../lib/theme-guard.js';
 import {
   isGitRepo,
   currentBranch,
@@ -14,9 +15,11 @@ import {
 export async function ensureBranchesCommand() {
   console.log(pc.bold('\n  climaybe — Ensure Branches\n'));
 
+  if (!requireThemeProject()) return;
+
   const config = readConfig();
   if (!config?.stores) {
-    console.log(pc.red('  No climaybe config found. Run "climaybe init" first.\n'));
+    console.log(pc.red('  No climaybe config found. Run "climaybe theme init" (or "climaybe init") first.\n'));
     return;
   }
 

package/src/commands/init.js

@@ -11,7 +11,7 @@ import {
   promptSecretValue,
   promptTestThemeToken,
 } from '../lib/prompts.js';
-import { readConfig, writeConfig } from '../lib/config.js';
+import { readConfig, writeConfig, getProjectType } 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';
@@ -49,6 +49,7 @@ async function runInitFlow() {
 
   // 2. Build config
   const config = {
+    project_type: 'theme',
     port: 9295,
     default_store: stores[0].domain,
     preview_workflows: enablePreviewWorkflows,
@@ -236,7 +237,14 @@ async function runInitFlow() {
 }
 
 export async function initCommand() {
-  console.log(pc.bold('\n  climaybe — Shopify CI/CD Setup\n'));
+  console.log(pc.bold('\n  climaybe — Shopify theme CI/CD setup\n'));
+
+  if (getProjectType() === 'app') {
+    console.log(pc.red('  This repo is configured as a Shopify app (project_type: app).'));
+    console.log(pc.dim('  Use: npx climaybe app init'));
+    console.log(pc.dim('  To switch to theme CI/CD, remove or edit package.json → config first.\n'));
+    return;
+  }
 
   const existing = readConfig();
   const hasConfig = existing != null && typeof existing === 'object';
@@ -249,9 +257,9 @@ export async function initCommand() {
       initial: false,
     });
     if (!reinit) {
-      console.log(pc.dim('  Use "climaybe add-store" to add more stores.'));
-      console.log(pc.dim('  Use "climaybe update-workflows" to refresh workflows.'));
-      console.log(pc.dim('  Use "climaybe reinit" to reinitialize from scratch.\n'));
+      console.log(pc.dim('  Use "climaybe theme add-store" (or "climaybe add-store") to add more stores.'));
+      console.log(pc.dim('  Use "climaybe theme update-workflows" (or "climaybe update-workflows") to refresh workflows.'));
+      console.log(pc.dim('  Use "climaybe theme reinit" (or "climaybe reinit") to reinitialize from scratch.\n'));
       return;
     }
   }
@@ -260,6 +268,13 @@ export async function initCommand() {
 }
 
 export async function reinitCommand() {
-  console.log(pc.bold('\n  climaybe — Reinitialize CI/CD Setup\n'));
+  console.log(pc.bold('\n  climaybe — Reinitialize theme CI/CD setup\n'));
+
+  if (getProjectType() === 'app') {
+    console.log(pc.red('  This repo is a Shopify app (project_type: app).'));
+    console.log(pc.dim('  Use: npx climaybe app init\n'));
+    return;
+  }
+
   await runInitFlow();
 }

package/src/commands/switch.js

@@ -1,10 +1,13 @@
 import pc from 'picocolors';
 import { getStoreAliases, getMode } from '../lib/config.js';
 import { storesToRoot } from '../lib/store-sync.js';
+import { requireThemeProject } from '../lib/theme-guard.js';
 
 export async function switchCommand(alias) {
   console.log(pc.bold('\n  climaybe — Switch Store\n'));
 
+  if (!requireThemeProject()) return;
+
   const mode = getMode();
   if (mode !== 'multi') {
     console.log(pc.yellow('  Switch is only available in multi-store mode.\n'));
@@ -22,6 +25,6 @@ export async function switchCommand(alias) {
   if (ok) {
     console.log(pc.bold(pc.green(`\n  Switched to store: ${alias}\n`)));
     console.log(pc.dim('  Root JSON files now reflect this store\'s data.'));
-    console.log(pc.dim('  Use "climaybe sync" to write changes back.\n'));
+    console.log(pc.dim('  Use "climaybe theme sync" (or "climaybe sync") to write changes back.\n'));
   }
 }

package/src/commands/sync.js

@@ -1,10 +1,13 @@
 import pc from 'picocolors';
 import { getStoreAliases, getMode, readConfig } from '../lib/config.js';
 import { rootToStores } from '../lib/store-sync.js';
+import { requireThemeProject } from '../lib/theme-guard.js';
 
 export async function syncCommand(alias) {
   console.log(pc.bold('\n  climaybe — Sync to Store\n'));
 
+  if (!requireThemeProject()) return;
+
   const mode = getMode();
   if (mode !== 'multi') {
     console.log(pc.yellow('  Sync is only available in multi-store mode.\n'));
@@ -22,7 +25,7 @@ export async function syncCommand(alias) {
 
     if (!alias) {
       console.log(pc.red('  No alias provided and no default store found.'));
-      console.log(pc.dim(`  Usage: climaybe sync <alias>`));
+      console.log(pc.dim(`  Usage: climaybe theme sync <alias>`));
       console.log(pc.dim(`  Available: ${aliases.join(', ')}\n`));
       return;
     }

package/src/commands/update-workflows.js

@@ -1,13 +1,16 @@
 import pc from 'picocolors';
 import { getMode, isBuildWorkflowsEnabled, isPreviewWorkflowsEnabled, readConfig } from '../lib/config.js';
 import { scaffoldWorkflows } from '../lib/workflows.js';
+import { requireThemeProject } from '../lib/theme-guard.js';
 
 export async function updateWorkflowsCommand() {
   console.log(pc.bold('\n  climaybe — Update Workflows\n'));
 
+  if (!requireThemeProject()) return;
+
   const config = readConfig();
   if (!config?.stores) {
-    console.log(pc.red('  No climaybe config found. Run "climaybe init" first.\n'));
+    console.log(pc.red('  No climaybe config found. Run "climaybe theme init" (or "climaybe init") first.\n'));
     return;
   }
 

package/src/cursor/skills/changelog-release/SKILL.md

@@ -18,7 +18,7 @@ Use the same type labels and emoji for changelog sections so the output matches
 
 ## Workflow
 
-1. **Determine range** — Since last tag (e.g. `git describe --tags --abbrev=0` then `git log TAG..HEAD`), or since a branch/commit the user specifies. If unclear, default to "since last tag".
+1. **Determine range** — Since last tag: use the **highest semver** among tags merged into `HEAD` (merged-into + `sort -V`), then `git log TAG..HEAD`. Do not rely on `git describe` alone after branch merges—it can return a **lower** version that is graph-closer on the merged branch. Or use a branch/commit the user specifies. If unclear, default to "since last tag".
 2. **Get commits** — Run `git log --oneline [range]` (or with `--pretty=format:...` for message + body). Parse commit messages.
 3. **Group by type** — Map each commit to a type from commit-rules.mdc (fix, feat, refactor, style, remove, wip, docs, ai, chore, upgrade). Ignore merge commits. Put "unknown" or "other" for non-matching messages.
 4. **Format** — Output markdown:

package/src/index.js

@@ -7,57 +7,79 @@ 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';
+import { appInitCommand } from './commands/app-init.js';
 
 /**
- * Create the CLI program (for testing and for run).
- * @param {string} [version] - Version string (from bin/cli.js when run as CLI; from package.json in tests).
- * @param {string} [packageDir] - Package root dir (shown with --version so user can see which install is running).
+ * Register theme CI/CD commands on a Commander instance (root or `theme` subgroup).
+ * @param {import('commander').Command} cmd
  */
-export function createProgram(version = '0.0.0', packageDir = '') {
-  const program = new Command();
-  const versionDisplay = packageDir ? `${version}\n  from: ${packageDir}` : version;
-
-  program
-    .name('climaybe')
-    .description('Shopify CI/CD CLI — scaffolds workflows, branch strategy, and store config')
-    .version(versionDisplay);
-
-  program
+function registerThemeCommands(cmd) {
+  cmd
     .command('init')
     .description('Initialize CI/CD setup for a Shopify theme repo')
     .action(initCommand);
 
-  program
+  cmd
     .command('reinit')
-    .description('Reinitialize CI/CD setup (removes existing config and re-scaffolds workflows)')
+    .description('Reinitialize theme CI/CD (re-scaffold workflows from templates)')
     .action(reinitCommand);
 
-  program
+  cmd
     .command('add-store')
     .description('Add a new store to an existing multi-store config')
     .action(addStoreCommand);
 
-  program
+  cmd
     .command('switch')
     .argument('<alias>', 'Store alias to switch to')
     .description('Switch local dev environment to a specific store')
     .action(switchCommand);
 
-  program
+  cmd
     .command('sync')
     .argument('[alias]', 'Store alias to sync to (defaults to active store)')
     .description('Sync root JSON files back to a store directory')
     .action(syncCommand);
 
-  program
+  cmd
     .command('update-workflows')
     .description('Refresh GitHub Actions workflows from latest bundled templates')
     .action(updateWorkflowsCommand);
 
-  program
+  cmd
     .command('ensure-branches')
     .description('Create missing staging and per-store branches from current HEAD (then push)')
     .action(ensureBranchesCommand);
+}
+
+/**
+ * Create the CLI program (for testing and for run).
+ * @param {string} [version] - Version string (from bin/cli.js when run as CLI; from package.json in tests).
+ * @param {string} [packageDir] - Package root dir (shown with --version so user can see which install is running).
+ */
+export function createProgram(version = '0.0.0', packageDir = '') {
+  const program = new Command();
+  const versionDisplay = packageDir ? `${version}\n  from: ${packageDir}` : version;
+
+  program
+    .name('climaybe')
+    .description(
+      'Shopify CLI — theme CI/CD (workflows, branches, stores) and app repo helpers (commitlint, Cursor bundle)'
+    )
+    .version(versionDisplay);
+
+  const theme = program
+    .command('theme')
+    .description('Shopify theme CI/CD: workflows, branches, and multi-store config');
+
+  registerThemeCommands(theme);
+  registerThemeCommands(program);
+
+  const app = program.command('app').description('Shopify app repo helpers (no theme workflows)');
+  app
+    .command('init')
+    .description('Set up commitlint, Cursor rules/skills, and project_type: app in package.json')
+    .action(appInitCommand);
 
   program
     .command('setup-commitlint')

package/src/lib/config.js

@@ -39,11 +39,20 @@ export function readConfig(cwd = process.cwd()) {
   return pkg?.config ?? null;
 }
 
+/**
+ * @typedef {object} WriteConfigOptions
+ * @property {string} [defaultPackageName] - When creating package.json, set `name` (default: shopify-theme).
+ */
+
 /**
  * Write/merge the climaybe config section into package.json.
  * Creates package.json if it doesn't exist.
+ * @param {object} config
+ * @param {string} [cwd]
+ * @param {WriteConfigOptions} [options]
  */
-export function writeConfig(config, cwd = process.cwd()) {
+export function writeConfig(config, cwd = process.cwd(), options = {}) {
+  const defaultPackageName = options.defaultPackageName ?? 'shopify-theme';
   let pkg = readPkg(cwd);
   if (!pkg) {
     let version = '1.0.0';
@@ -54,7 +63,7 @@ export function writeConfig(config, cwd = process.cwd()) {
       // not a git repo or no tags
     }
     pkg = {
-      name: 'shopify-theme',
+      name: defaultPackageName,
       version,
       private: true,
       config: {},
@@ -64,6 +73,34 @@ export function writeConfig(config, cwd = process.cwd()) {
   writePkg(pkg, cwd);
 }
 
+/**
+ * Resolved project kind for guards and init flows.
+ * - `app` only when config explicitly sets project_type: app.
+ * - Otherwise `theme` (including missing config and legacy theme repos without project_type).
+ * @param {string} [cwd]
+ * @returns {'theme' | 'app'}
+ */
+export function getProjectType(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  if (config?.project_type === 'app') return 'app';
+  return 'theme';
+}
+
+/**
+ * True if this repo is clearly a theme project (explicit project_type or legacy stores).
+ * Used to refuse `app init` on theme repos.
+ * @param {string} [cwd]
+ */
+export function isThemeProjectForAppInit(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  if (!config) return false;
+  if (config.project_type === 'theme') return true;
+  if (config.stores && typeof config.stores === 'object' && Object.keys(config.stores).length > 0) {
+    return true;
+  }
+  return false;
+}
+
 /**
  * Get the list of store aliases from config.
  */

package/src/lib/theme-guard.js

@@ -0,0 +1,13 @@
+import pc from 'picocolors';
+import { getProjectType } from './config.js';
+
+/**
+ * @param {string} [cwd]
+ * @returns {boolean} false if the repo is an app project (caller should return early).
+ */
+export function requireThemeProject(cwd = process.cwd()) {
+  if (getProjectType(cwd) !== 'app') return true;
+  console.log(pc.red('  This command is for theme repos only. This project has project_type: app.'));
+  console.log(pc.dim('  Use climaybe app init for app setup; theme stores and workflows do not apply here.\n'));
+  return false;
+}

package/src/workflows/shared/version-bump.yml

@@ -61,9 +61,15 @@ jobs:
             fi
             NEW_VERSION="v${NEW_VERSION}"
           else
-            # Get latest tag (or theme_version from settings_schema.json when no tags)
-            LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+            # Highest semver among tags reachable from HEAD — not `git describe`, which picks
+            # the graph-nearest tag and can choose an old tag on the merged branch after staging→main.
+            LATEST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+            # Legacy tags without patch (v1.0) if no strict triple match
             if [ -z "$LATEST_TAG" ]; then
+              LATEST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+$' | sort -V | tail -1)
+            fi
+            if [ -z "$LATEST_TAG" ]; then
+              # No semver tags: theme_version from settings_schema.json, else v0.0.0
               SCHEMA="config/settings_schema.json"
               if [ -f "$SCHEMA" ]; then
                 LATEST_TAG=$(node -e "
@@ -100,6 +106,26 @@ jobs:
           echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
           echo "New version: $NEW_VERSION"
 
+      - name: Refuse non-increasing version
+        env:
+          NEW_VERSION: ${{ steps.bump.outputs.new_version }}
+        run: |
+          git fetch --tags origin
+          MAX_EXISTING=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          if [ -z "$MAX_EXISTING" ]; then
+            MAX_EXISTING=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          fi
+          if [ -z "$MAX_EXISTING" ]; then
+            echo "No merged semver tags; skipping monotonic check."
+            exit 0
+          fi
+          HI=$(printf '%s\n' "$MAX_EXISTING" "$NEW_VERSION" | sort -V | tail -1)
+          if [ "$HI" != "$NEW_VERSION" ] || [ "$NEW_VERSION" = "$MAX_EXISTING" ]; then
+            echo "::error::Refusing to release ${NEW_VERSION}: latest merged tag is ${MAX_EXISTING}; new tag must be strictly higher (semver)."
+            exit 1
+          fi
+          echo "OK: ${NEW_VERSION} > ${MAX_EXISTING}"
+
       - name: Update settings_schema.json and package.json
         env:
           NEW_VERSION: ${{ steps.bump.outputs.new_version }}

package/src/workflows/single/nightly-hotfix.yml

@@ -42,7 +42,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          LATEST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          if [ -z "$LATEST_TAG" ]; then
+            LATEST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          fi
           if [ -z "$LATEST_TAG" ]; then
             SCHEMA="config/settings_schema.json"
             if [ -f "$SCHEMA" ]; then

package/src/workflows/single/post-merge-tag.yml

@@ -77,7 +77,10 @@ jobs:
       - name: Get latest tag (or create from settings_schema.json)
         id: tag
         run: |
-          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          LAST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          if [ -z "$LAST_TAG" ]; then
+            LAST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          fi
           if [ -z "$LAST_TAG" ]; then
             SCHEMA="config/settings_schema.json"
             if [ -f "$SCHEMA" ]; then

package/src/workflows/single/release-pr-check.yml

@@ -56,7 +56,10 @@ jobs:
       - name: Create pre-release patch tag
         id: tag
         run: |
-          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          LATEST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          if [ -z "$LATEST_TAG" ]; then
+            LATEST_TAG=$(git tag --merged HEAD | grep -E '^v[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          fi
           if [ -z "$LATEST_TAG" ]; then
             # No tags: use theme_version from config/settings_schema.json and push as initial tag
             SCHEMA="config/settings_schema.json"