climaybe 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# climaybe
+
+Shopify CI/CD CLI — scaffolds GitHub Actions workflows, branch strategy, and store config for single-store and multi-store theme repositories.
+
+## Install
+
+```bash
+npm install -g climaybe
+```
+
+## Quick Start
+
+```bash
+cd your-shopify-theme-repo
+climaybe init
+```
+
+The interactive setup will ask for your store URL(s) and configure everything automatically.
+
+## Commands
+
+### `climaybe init`
+
+Interactive setup that configures your repo for CI/CD.
+
+1. Prompts for your store URL (e.g., `voldt-staging.myshopify.com`)
+2. Extracts subdomain as alias, lets you override
+3. Asks if you want to add more stores
+4. Based on store count, sets up **single-store** or **multi-store** mode
+5. Writes `package.json` config
+6. Scaffolds GitHub Actions workflows
+7. Creates git branches and store directories (multi-store)
+
+### `climaybe add-store`
+
+Add a new store to an existing setup.
+
+```bash
+climaybe add-store
+```
+
+- Prompts for new store URL + alias
+- Creates `staging-<alias>` and `live-<alias>` branches
+- Creates `stores/<alias>/` directory structure
+- If store count goes from 1 to 2+, automatically migrates from single to multi-store mode
+
+### `climaybe switch <alias>`
+
+Switch your local dev environment to a specific store (multi-store only).
+
+```bash
+climaybe switch voldt-norway
+```
+
+Copies `stores/<alias>/` JSON files to the repo root so you can preview that store locally.
+
+### `climaybe sync [alias]`
+
+Sync root JSON files back to a store directory (multi-store only).
+
+```bash
+climaybe sync voldt-norway
+```
+
+If no alias is given, syncs to the default store.
+
+### `climaybe update-workflows`
+
+Refresh GitHub Actions workflows from the latest bundled templates.
+
+```bash
+climaybe update-workflows
+```
+
+Useful after updating the CLI to get the latest workflow improvements.
+
+## Configuration
+
+The CLI writes config into the `config` field of your `package.json`:
+
+```json
+{
+  "config": {
+    "port": 9295,
+    "default_store": "voldt-staging.myshopify.com",
+    "stores": {
+      "voldt-staging": "voldt-staging.myshopify.com",
+      "voldt-norway": "voldt-norway.myshopify.com"
+    }
+  }
+}
+```
+
+Workflows read this config at runtime — no hardcoded values in YAML files.
+
+## Branch Strategy
+
+### Single-store
+
+```
+staging → main
+```
+
+- `staging` — development branch
+- `main` — production branch
+
+### Multi-store
+
+```
+staging → main → staging-<store> → live-<store>
+```
+
+- `staging` — development branch
+- `main` — shared codebase (not live)
+- `staging-<store>` — per-store staging with store-specific JSON data
+- `live-<store>` — per-store production
+
+## Workflows
+
+### Shared (both modes)
+
+| Workflow | Purpose |
+|----------|---------|
+| `ai-changelog.yml` | Reusable workflow. Sends commits to Gemini API, returns classified changelog. |
+| `version-bump.yml` | Reusable workflow. Bumps version in `settings_schema.json`, creates git tag. |
+
+### Single-store
+
+| 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) | Detects release version from PR title, bumps minor version |
+| `nightly-hotfix.yml` | Cron 02:00 US Eastern | Tags untagged hotfix commits with patch version |
+
+### Multi-store (additional)
+
+| Workflow | Trigger | What it does |
+|----------|---------|-------------|
+| `main-to-staging-stores.yml` | Push to `main` | Opens PRs to each `staging-<alias>` branch |
+| `stores-to-root.yml` | Push to `staging-*` | Copies `stores/<alias>/` JSONs to repo root |
+| `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>/` |
+| `hotfix-backport.yml` | After root-to-stores | Creates backport PR to `main` |
+
+## Versioning
+
+- **Release merge** (`staging` → `main`): Minor bump (e.g., `v3.1.x` → `v3.2.0`)
+- **Hotfix** (direct commit to `main` or `live-*`): Patch bump (e.g., `v3.2.0` → `v3.2.1`)
+- **PR title convention**: `Release v3.2` — the workflow extracts the version from this
+
+All version bumps update `config/settings_schema.json` automatically.
+
+## File Sync Rules (Multi-store)
+
+**Synced between root and `stores/<alias>/`:**
+- `config/settings_data.json`
+- `templates/*.json`
+- `sections/*.json`
+
+**NOT synced (travels via branch history):**
+- `config/settings_schema.json`
+- `locales/*.json`
+
+## Recursive Trigger Prevention
+
+- Hotfix backport commits contain `[hotfix-backport]` in the message
+- Store sync commits contain `[stores-to-root]` or `[root-to-stores]`
+- Version bump commits contain `chore(release): bump version`
+- All workflows check for these flags and skip accordingly
+
+## GitHub Secrets
+
+Add the following secret to your GitHub repository:
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `GEMINI_API_KEY` | Yes | Google Gemini API key for changelog generation |
+
+## Directory Structure (Multi-store)
+
+```
+├── assets/
+├── config/
+├── layout/
+├── locales/
+├── sections/
+├── snippets/
+├── templates/
+├── stores/
+│   ├── voldt-staging/
+│   │   ├── config/settings_data.json
+│   │   ├── templates/*.json
+│   │   └── sections/*.json
+│   └── voldt-norway/
+│       ├── config/settings_data.json
+│       ├── templates/*.json
+│       └── sections/*.json
+├── package.json
+└── .github/workflows/
+```
+
+## License
+
+MIT — Electric Maybe

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run(process.argv);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "climaybe",
+  "version": "1.0.0",
+  "description": "Shopify CI/CD CLI — scaffolds workflows, branch strategy, and store config for single-store and multi-store theme repos",
+  "type": "module",
+  "bin": {
+    "climaybe": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "shopify",
+    "ci",
+    "cd",
+    "theme",
+    "workflow",
+    "github-actions"
+  ],
+  "author": "Electric Maybe",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  }
+}

package/src/commands/add-store.js

@@ -0,0 +1,55 @@
+import pc from 'picocolors';
+import { promptNewStore } from '../lib/prompts.js';
+import { readConfig, addStoreToConfig, getStoreAliases, getMode } from '../lib/config.js';
+import { createStoreBranches } from '../lib/git.js';
+import { scaffoldWorkflows } from '../lib/workflows.js';
+import { createStoreDirectories } from '../lib/store-sync.js';
+
+export async function addStoreCommand() {
+  console.log(pc.bold('\n  climaybe — Add Store\n'));
+
+  // Guard: config must exist
+  const config = readConfig();
+  if (!config?.stores) {
+    console.log(pc.red('  No climaybe config found. Run "climaybe init" first.\n'));
+    return;
+  }
+
+  const existingAliases = getStoreAliases();
+  const previousMode = getMode();
+
+  // Prompt for new store
+  const store = await promptNewStore(existingAliases);
+  if (!store) return;
+
+  // Add to config
+  addStoreToConfig(store.alias, store.domain);
+  console.log(pc.green(`  Added store: ${store.alias} → ${store.domain}`));
+
+  const newMode = getMode();
+
+  // Create store branches + directories
+  createStoreBranches(store.alias);
+  createStoreDirectories(store.alias);
+
+  // Handle single → multi migration
+  if (previousMode === 'single' && newMode === 'multi') {
+    console.log(pc.cyan('\n  Migrating from single-store to multi-store mode...'));
+
+    // Create branches for the original store too
+    const originalAlias = existingAliases[0];
+    createStoreBranches(originalAlias);
+    createStoreDirectories(originalAlias);
+
+    // Re-scaffold workflows for multi mode
+    scaffoldWorkflows('multi');
+    console.log(pc.green('  Migration complete — workflows updated to multi-store mode.'));
+  } else if (newMode === 'multi') {
+    // Already multi, just make sure workflows are current
+    scaffoldWorkflows('multi');
+  }
+
+  console.log(pc.bold(pc.green('\n  Store added successfully!\n')));
+  console.log(pc.dim(`  New branches: staging-${store.alias}, live-${store.alias}`));
+  console.log(pc.dim(`  Store dir: stores/${store.alias}/\n`));
+}

package/src/commands/init.js

@@ -0,0 +1,78 @@
+import pc from 'picocolors';
+import { promptStoreLoop } from '../lib/prompts.js';
+import { readConfig, writeConfig } from '../lib/config.js';
+import { ensureGitRepo, ensureInitialCommit, ensureStagingBranch, createStoreBranches } from '../lib/git.js';
+import { scaffoldWorkflows } from '../lib/workflows.js';
+import { createStoreDirectories } from '../lib/store-sync.js';
+
+export async function initCommand() {
+  console.log(pc.bold('\n  climaybe — Shopify CI/CD Setup\n'));
+
+  // Guard: check if already initialized
+  const existing = readConfig();
+  if (existing?.stores && Object.keys(existing.stores).length > 0) {
+    console.log(pc.yellow('  This repo already has a climaybe config.'));
+    console.log(pc.dim('  Use "climaybe add-store" to add more stores.'));
+    console.log(pc.dim('  Use "climaybe update-workflows" to refresh workflows.\n'));
+    return;
+  }
+
+  // 1. Collect stores from user
+  const stores = await promptStoreLoop();
+  const mode = stores.length > 1 ? 'multi' : 'single';
+
+  console.log(pc.dim(`\n  Mode: ${mode}-store (${stores.length} store(s))`));
+
+  // 2. Build config
+  const config = {
+    port: 9295,
+    default_store: stores[0].domain,
+    stores: {},
+  };
+
+  for (const s of stores) {
+    config.stores[s.alias] = s.domain;
+  }
+
+  // 3. Write package.json config
+  writeConfig(config);
+  console.log(pc.green('  Updated package.json config.'));
+
+  // 4. Ensure git repo
+  ensureGitRepo();
+  ensureInitialCommit();
+
+  // 5. Create branches
+  if (mode === 'single') {
+    ensureStagingBranch();
+  } else {
+    // Multi-store: staging branch + per-store branches
+    ensureStagingBranch();
+    for (const s of stores) {
+      createStoreBranches(s.alias);
+      createStoreDirectories(s.alias);
+    }
+  }
+
+  // 6. Scaffold workflows
+  scaffoldWorkflows(mode);
+
+  // Done
+  console.log(pc.bold(pc.green('\n  Setup complete!\n')));
+
+  if (mode === 'single') {
+    console.log(pc.dim('  Branches: main, staging'));
+    console.log(pc.dim('  Workflow: staging → main with versioning + nightly hotfix tagging'));
+  } else {
+    console.log(pc.dim('  Branches: main, staging'));
+    for (const s of stores) {
+      console.log(pc.dim(`    staging-${s.alias}, live-${s.alias}`));
+    }
+    console.log(pc.dim('  Workflow: staging → main → staging-<store> → live-<store>'));
+  }
+
+  console.log(pc.dim('\n  Next steps:'));
+  console.log(pc.dim('    1. Add GEMINI_API_KEY to your GitHub repo secrets'));
+  console.log(pc.dim('    2. Push to GitHub and start using the branching workflow'));
+  console.log(pc.dim('    3. Tag your first release: git tag v1.0.0\n'));
+}

package/src/commands/switch.js

@@ -0,0 +1,27 @@
+import pc from 'picocolors';
+import { getStoreAliases, getMode } from '../lib/config.js';
+import { storesToRoot } from '../lib/store-sync.js';
+
+export async function switchCommand(alias) {
+  console.log(pc.bold('\n  climaybe — Switch Store\n'));
+
+  const mode = getMode();
+  if (mode !== 'multi') {
+    console.log(pc.yellow('  Switch is only available in multi-store mode.\n'));
+    return;
+  }
+
+  const aliases = getStoreAliases();
+  if (!aliases.includes(alias)) {
+    console.log(pc.red(`  Unknown store alias: "${alias}"`));
+    console.log(pc.dim(`  Available: ${aliases.join(', ')}\n`));
+    return;
+  }
+
+  const ok = storesToRoot(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'));
+  }
+}

package/src/commands/sync.js

@@ -0,0 +1,42 @@
+import pc from 'picocolors';
+import { getStoreAliases, getMode, readConfig } from '../lib/config.js';
+import { rootToStores } from '../lib/store-sync.js';
+
+export async function syncCommand(alias) {
+  console.log(pc.bold('\n  climaybe — Sync to Store\n'));
+
+  const mode = getMode();
+  if (mode !== 'multi') {
+    console.log(pc.yellow('  Sync is only available in multi-store mode.\n'));
+    return;
+  }
+
+  const aliases = getStoreAliases();
+
+  // If no alias provided, use default store
+  if (!alias) {
+    const config = readConfig();
+    const defaultDomain = config?.default_store;
+    // Find alias by domain
+    alias = aliases.find((a) => config.stores[a] === defaultDomain);
+
+    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(`  Available: ${aliases.join(', ')}\n`));
+      return;
+    }
+    console.log(pc.dim(`  Using default store: ${alias}`));
+  }
+
+  if (!aliases.includes(alias)) {
+    console.log(pc.red(`  Unknown store alias: "${alias}"`));
+    console.log(pc.dim(`  Available: ${aliases.join(', ')}\n`));
+    return;
+  }
+
+  const ok = rootToStores(alias);
+  if (ok) {
+    console.log(pc.bold(pc.green(`\n  Synced root → stores/${alias}/\n`)));
+  }
+}

package/src/commands/update-workflows.js

@@ -0,0 +1,18 @@
+import pc from 'picocolors';
+import { getMode, readConfig } from '../lib/config.js';
+import { scaffoldWorkflows } from '../lib/workflows.js';
+
+export async function updateWorkflowsCommand() {
+  console.log(pc.bold('\n  climaybe — Update Workflows\n'));
+
+  const config = readConfig();
+  if (!config?.stores) {
+    console.log(pc.red('  No climaybe config found. Run "climaybe init" first.\n'));
+    return;
+  }
+
+  const mode = getMode();
+  scaffoldWorkflows(mode);
+
+  console.log(pc.bold(pc.green('\n  Workflows updated!\n')));
+}

package/src/index.js

@@ -0,0 +1,44 @@
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { addStoreCommand } from './commands/add-store.js';
+import { switchCommand } from './commands/switch.js';
+import { syncCommand } from './commands/sync.js';
+import { updateWorkflowsCommand } from './commands/update-workflows.js';
+
+export function run(argv) {
+  const program = new Command();
+
+  program
+    .name('climaybe')
+    .description('Shopify CI/CD CLI — scaffolds workflows, branch strategy, and store config')
+    .version('1.0.0');
+
+  program
+    .command('init')
+    .description('Initialize CI/CD setup for a Shopify theme repo')
+    .action(initCommand);
+
+  program
+    .command('add-store')
+    .description('Add a new store to an existing multi-store config')
+    .action(addStoreCommand);
+
+  program
+    .command('switch')
+    .argument('<alias>', 'Store alias to switch to')
+    .description('Switch local dev environment to a specific store')
+    .action(switchCommand);
+
+  program
+    .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
+    .command('update-workflows')
+    .description('Refresh GitHub Actions workflows from latest bundled templates')
+    .action(updateWorkflowsCommand);
+
+  program.parse(argv);
+}

package/src/lib/config.js

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PKG = 'package.json';
+
+/**
+ * Resolve absolute path to the target repo's package.json.
+ * Defaults to cwd.
+ */
+function pkgPath(cwd = process.cwd()) {
+  return join(cwd, PKG);
+}
+
+/**
+ * Read the full package.json from a target repo.
+ * Returns null if it doesn't exist.
+ */
+export function readPkg(cwd = process.cwd()) {
+  const p = pkgPath(cwd);
+  if (!existsSync(p)) return null;
+  return JSON.parse(readFileSync(p, 'utf-8'));
+}
+
+/**
+ * Write the full package.json object back to disk.
+ */
+export function writePkg(pkg, cwd = process.cwd()) {
+  writeFileSync(pkgPath(cwd), JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Read the climaybe config section from package.json.
+ * Returns null if package.json or config section doesn't exist.
+ */
+export function readConfig(cwd = process.cwd()) {
+  const pkg = readPkg(cwd);
+  return pkg?.config ?? null;
+}
+
+/**
+ * Write/merge the climaybe config section into package.json.
+ * Creates package.json if it doesn't exist.
+ */
+export function writeConfig(config, cwd = process.cwd()) {
+  let pkg = readPkg(cwd);
+  if (!pkg) {
+    pkg = {
+      name: 'shopify-theme',
+      version: '1.0.0',
+      private: true,
+      config: {},
+    };
+  }
+  pkg.config = { ...pkg.config, ...config };
+  writePkg(pkg, cwd);
+}
+
+/**
+ * Get the list of store aliases from config.
+ */
+export function getStoreAliases(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  if (!config?.stores) return [];
+  return Object.keys(config.stores);
+}
+
+/**
+ * Determine the current mode: 'single' or 'multi'.
+ */
+export function getMode(cwd = process.cwd()) {
+  const aliases = getStoreAliases(cwd);
+  return aliases.length > 1 ? 'multi' : 'single';
+}
+
+/**
+ * Add a store entry to the config.
+ * Returns the updated config.
+ */
+export function addStoreToConfig(alias, domain, cwd = process.cwd()) {
+  const config = readConfig(cwd) || { port: 9295, stores: {} };
+  if (!config.stores) config.stores = {};
+
+  config.stores[alias] = domain;
+
+  // Set as default if it's the first store
+  if (!config.default_store) {
+    config.default_store = domain;
+  }
+
+  writeConfig(config, cwd);
+  return readConfig(cwd);
+}

package/src/lib/git.js

@@ -0,0 +1,90 @@
+import { execSync } from 'node:child_process';
+import pc from 'picocolors';
+
+const exec = (cmd, cwd = process.cwd()) =>
+  execSync(cmd, { cwd, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+/**
+ * Check if current directory is a git repo.
+ */
+export function isGitRepo(cwd = process.cwd()) {
+  try {
+    exec('git rev-parse --is-inside-work-tree', cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the current branch name.
+ */
+export function currentBranch(cwd = process.cwd()) {
+  return exec('git rev-parse --abbrev-ref HEAD', cwd);
+}
+
+/**
+ * Check if a local branch exists.
+ */
+export function branchExists(name, cwd = process.cwd()) {
+  try {
+    exec(`git rev-parse --verify ${name}`, cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a new branch from current HEAD (does not checkout).
+ */
+export function createBranch(name, cwd = process.cwd()) {
+  if (branchExists(name, cwd)) {
+    console.log(pc.yellow(`  Branch "${name}" already exists, skipping.`));
+    return false;
+  }
+  exec(`git branch ${name}`, cwd);
+  console.log(pc.green(`  Created branch: ${name}`));
+  return true;
+}
+
+/**
+ * Create staging and live branches for a store alias.
+ */
+export function createStoreBranches(alias, cwd = process.cwd()) {
+  const staging = `staging-${alias}`;
+  const live = `live-${alias}`;
+  createBranch(staging, cwd);
+  createBranch(live, cwd);
+}
+
+/**
+ * Ensure the staging branch exists (for single-store mode).
+ */
+export function ensureStagingBranch(cwd = process.cwd()) {
+  createBranch('staging', cwd);
+}
+
+/**
+ * Create an initial commit if the repo has no commits.
+ */
+export function ensureInitialCommit(cwd = process.cwd()) {
+  try {
+    exec('git rev-parse HEAD', cwd);
+  } catch {
+    // No commits yet — create an initial one
+    exec('git add -A', cwd);
+    exec('git commit -m "chore: initial commit" --allow-empty', cwd);
+    console.log(pc.green('  Created initial commit.'));
+  }
+}
+
+/**
+ * Initialize a git repo if not already one.
+ */
+export function ensureGitRepo(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) {
+    exec('git init', cwd);
+    console.log(pc.green('  Initialized git repository.'));
+  }
+}