climaybe 2.4.2 → 3.0.0

package/README.md

@@ -13,10 +13,10 @@ Built by [Electric Maybe](https://electricmaybe.com) — a Shopify-focused produ
 
 - **`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 app init`** — app repos only: writes `project_type: "app"` in `climaybe.config.json`, 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`**.
+Theme-only commands refuse to run when `climaybe.config.json` → `project_type` is **`app`**.
 
 ## Install
 
@@ -64,7 +64,7 @@ Interactive setup that configures your repo for CI/CD.
 6. Asks whether to enable **commitlint + Husky** (enforce [conventional commits](https://www.conventionalcommits.org/) on `git commit`)
 7. Asks whether to install the **Cursor bundle** (`.cursor/rules/`, `.cursor/skills/`, `.cursor/agents/`) — Electric Maybe conventions for themes and AI workflows
 8. Based on store count, sets up **single-store** or **multi-store** mode
-9. Writes `package.json` config
+9. Writes `climaybe.config.json`
 10. Scaffolds GitHub Actions workflows
 11. Creates git branches and store directories (multi-store)
 12. Optionally installs commitlint, Husky, and the Cursor bundle (rules, skills, agents)
@@ -145,21 +145,19 @@ The previous command name `add-cursor-skill` still works as an alias. Re-running
 
 ## Configuration
 
-The CLI writes config into the `config` field of your `package.json`:
+The CLI writes config into `climaybe.config.json`:
 
 ```json
 {
-  "config": {
-    "port": 9295,
-    "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"
-    }
+  "port": 9295,
+  "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"
   }
 }
 ```
@@ -235,27 +233,28 @@ Enabled via `climaybe init` prompt (`Enable preview + cleanup workflows?`; defau
 
 Enabled via `climaybe init` prompt (`Enable build + Lighthouse workflows?`; default: yes).
 
-When enabled, `init` validates required theme files and exits with an error if any are missing:
-- `_scripts/main.js`
-- `_styles/main.css`
+When enabled, builds are **resilient**:
+- If `_scripts/*.js` or `_styles/main.css` are missing, the build workflow **skips** those steps and continues.
+- `init` may offer to create entrypoints; **default answer is No**.
 
-`init` auto-creates:
-- `assets/`
-
-`climaybe` auto-installs the shared build script at `.climaybe/build-scripts.js` during workflow scaffolding.
+Build workflows run bundling via `npx -y climaybe@latest build-scripts` and Tailwind via `npx -y climaybe@latest build` (no per-repo build script is installed).
 
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
 | `build-pipeline.yml` | Push to any branch | Runs reusable build and Lighthouse checks (when required secrets exist) |
 | `reusable-build.yml` | workflow_call | Runs Node build + Tailwind compile, then commits compiled assets when changed |
-| `create-release.yml` | Push tag `v*`, or **workflow_run** after Post-Merge Tag / Nightly Hotfix Tag succeed on `main` | Builds release archive and creates GitHub Release notes from commits since the previous tag. If commit subjects are low-signal and `GEMINI_API_KEY` exists, it uses Gemini to generate cleaner merchant-facing notes. Also covers tags created by workflows with `GITHUB_TOKEN`, which may not trigger tag-push workflows. |
+| `create-release.yml` | Push tag `v*`, or **workflow_run** after Post-Merge Tag / Nightly Hotfix Tag succeed on `main` | Builds release archive and creates GitHub Release notes from commits since the previous tag. It filters repetitive automation subjects (main→staging syncs, store/root sync chores, bot merge noise) before generating notes. If remaining subjects are low-signal and `GEMINI_API_KEY` exists, it uses Gemini to generate cleaner merchant-facing notes. Also covers tags created by workflows with `GITHUB_TOKEN`, which may not trigger tag-push workflows. |
 
 ### Optional theme dev kit package
 
 During `climaybe init`, you can enable the Electric Maybe theme dev kit (default: yes). This installs local
-dev scripts/config defaults (`nodemon.json`, `.theme-check.yml`, `.shopifyignore`, `.prettierrc`,
-`.lighthouserc.js`), merges matching `package.json` scripts/dependencies, appends a managed `.gitignore` block,
-and optionally adds `.vscode/tasks.json` (default: yes).
+dev config defaults (`.theme-check.yml`, `.shopifyignore`, `.prettierrc`,
+`.lighthouserc.js`), writes `climaybe.config.json`, appends a managed `.gitignore` block, and optionally adds
+`.vscode/tasks.json` (default: yes) wired to run `climaybe` dev commands.
+
+You can create optional build entrypoints later with:
+
+`climaybe create-entrypoints`
 
 If these files already exist, `init` warns that they will be replaced.
 

package/bin/version.txt

@@ -1 +1 @@
-2.4.2
+3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "climaybe",
-  "version": "2.4.2",
+  "version": "3.0.0",
   "description": "Shopify CLI by Electric Maybe for theme CI/CD workflows, branch orchestration, app setup, and dev tooling",
   "type": "module",
   "bin": {
@@ -78,6 +78,14 @@
     ]
   },
   "dependencies": {
+    "@shopify/prettier-plugin-liquid": "^1.6.3",
+    "@tailwindcss/cli": "^4.1.17",
+    "@tailwindcss/typography": "^0.5.16",
+    "eslint": "^9.11.0",
+    "prettier": "^3.4.2",
+    "stylelint": "^16.9.0",
+    "stylelint-config-standard": "^36.0.1",
+    "tailwindcss": "^4.1.18",
     "commander": "^14.0.3",
     "picocolors": "^1.1.1",
     "prompts": "^2.4.2"

package/src/commands/add-dev-kit.js

@@ -1,8 +1,8 @@
 import prompts from 'prompts';
 import pc from 'picocolors';
-import { readConfig, writeConfig } from '../lib/config.js';
+import { readConfig, readPkg, writeConfig } from '../lib/config.js';
 import { getDevKitExistingFiles, scaffoldThemeDevKit } from '../lib/theme-dev-kit.js';
-import { promptVSCodeDevTasks } from '../lib/prompts.js';
+import { promptProjectName, promptVSCodeDevTasks } from '../lib/prompts.js';
 
 export async function addDevKitCommand() {
   console.log(pc.bold('\n  climaybe — Add theme dev kit\n'));
@@ -25,12 +25,14 @@ export async function addDevKitCommand() {
   }
 
   const config = readConfig() || {};
+  const projectName = !readPkg() ? await promptProjectName() : undefined;
   scaffoldThemeDevKit({
     includeVSCodeTasks,
     defaultStoreDomain: config.default_store || '',
+    packageName: projectName || undefined,
   });
   writeConfig({ dev_kit: true, vscode_tasks: includeVSCodeTasks });
 
   console.log(pc.green('  Theme dev kit installed.'));
-  console.log(pc.dim('  Added scripts/configs for local serve/watch/lint and ignore defaults.\n'));
+  console.log(pc.dim('  Added local dev-kit config files and ignore defaults.\n'));
 }

package/src/commands/add-store.js

@@ -1,5 +1,5 @@
 import pc from 'picocolors';
-import { promptNewStore, promptConfigureCISecrets, promptUpdateExistingSecrets, promptSecretValue, promptTestThemeToken } from '../lib/prompts.js';
+import { promptNewStore, promptConfigureCISecrets, promptUpdateExistingSecrets, promptSecretValue } from '../lib/prompts.js';
 import {
   readConfig,
   addStoreToConfig,
@@ -119,23 +119,38 @@ export async function addStoreCommand() {
         console.log(pc.cyan(`\n  Configure ${total} secret(s) for store "${store.alias}" (theme token required).\n`));
         for (let i = 0; i < secretsToPrompt.length; i++) {
           const secret = secretsToPrompt[i];
-          const value = await promptSecretValue(secret, i, total);
-          if (!value) continue;
-
           const isThemeToken = secret.name === 'SHOPIFY_THEME_ACCESS_TOKEN' || secret.name.startsWith('SHOPIFY_THEME_ACCESS_TOKEN_');
           if (isThemeToken && store.domain) {
-            const doTest = await promptTestThemeToken();
-            if (doTest) {
+            // Theme tokens are required and must validate; keep prompting until valid + set.
+            while (true) {
+              const value = await promptSecretValue(secret, i, total);
+              if (!value) {
+                console.log(pc.red('  Theme access token is required.'));
+                continue;
+              }
               const result = await validateThemeAccessToken(store.domain, value);
               if (!result.ok) {
                 console.log(pc.red(`  Token test failed: ${result.error}`));
-                console.log(pc.dim('  Secret not set. You can add it later in repo Settings → Secrets.'));
+                console.log(pc.dim('  Please try again with a valid Theme Access token.'));
                 continue;
               }
               console.log(pc.green('  Token validated against store.'));
+              try {
+                await setter.set(secret.name, value);
+                console.log(pc.green(`  Set ${secret.name}.`));
+                setCount++;
+                break;
+              } catch (err) {
+                console.log(pc.red(`  Failed to set ${secret.name}: ${err.message}`));
+                console.log(pc.dim('  Please try entering the token again.'));
+              }
             }
+            continue;
           }
 
+          const value = await promptSecretValue(secret, i, total);
+          if (!value) continue;
+
           try {
             await setter.set(secret.name, value);
             console.log(pc.green(`  Set ${secret.name}.`));

package/src/commands/app-init.js

@@ -26,7 +26,7 @@ async function runAppInitFlow() {
   };
 
   writeConfig(config, process.cwd(), { defaultPackageName: 'shopify-app' });
-  console.log(pc.green('  Updated package.json config.'));
+  console.log(pc.green('  Updated climaybe config.'));
 
   ensureGitRepo();
   ensureInitialCommit();

package/src/commands/build-scripts.js

@@ -0,0 +1,27 @@
+import pc from 'picocolors';
+import { requireThemeProject } from '../lib/theme-guard.js';
+import { buildScripts } from '../lib/build-scripts.js';
+
+export async function buildScriptsCommand() {
+  console.log(pc.bold('\n  climaybe — Build scripts\n'));
+  if (!requireThemeProject()) return;
+
+  try {
+    if (global.gc) global.gc();
+    const { bundles } = buildScripts({ cwd: process.cwd() });
+    if (!bundles || bundles.length === 0) {
+      console.log(pc.yellow('  No _scripts/*.js entrypoints found; nothing to build.'));
+      return;
+    }
+    const totalFiles = bundles.reduce((sum, b) => sum + (b.fileCount || 0), 0);
+    console.log(pc.green(`  Scripts built (${bundles.length} bundle(s), ${totalFiles} files total)`));
+    for (const b of bundles) {
+      console.log(pc.dim(`  - ${b.entryFile} → ${b.outputPath}`));
+    }
+    if (global.gc) global.gc();
+  } catch (err) {
+    console.log(pc.red(`  Build error: ${err.message}`));
+    process.exitCode = 1;
+  }
+}
+

package/src/commands/create-entrypoints.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { requireThemeProject } from '../lib/theme-guard.js';
+
+const MAIN_JS = `// climaybe entrypoint: global theme JS
+// Add imports here for code you want on every page.
+// Top-level files in _scripts/ (besides main.js) are treated as separate bundles.
+`;
+
+const MAIN_CSS = `@import "tailwindcss";
+`;
+
+export async function createEntrypointsCommand() {
+  console.log(pc.bold('\n  climaybe — Create entrypoints\n'));
+  if (!requireThemeProject()) return;
+
+  const scriptsDir = join(process.cwd(), '_scripts');
+  const stylesDir = join(process.cwd(), '_styles');
+  const assetsDir = join(process.cwd(), 'assets');
+
+  mkdirSync(scriptsDir, { recursive: true });
+  mkdirSync(stylesDir, { recursive: true });
+  mkdirSync(assetsDir, { recursive: true });
+
+  const mainJsPath = join(scriptsDir, 'main.js');
+  const mainCssPath = join(stylesDir, 'main.css');
+
+  if (!existsSync(mainJsPath)) {
+    writeFileSync(mainJsPath, MAIN_JS, 'utf-8');
+    console.log(pc.green('  Created _scripts/main.js'));
+  } else {
+    console.log(pc.dim('  _scripts/main.js already exists (skipped)'));
+  }
+
+  if (!existsSync(mainCssPath)) {
+    writeFileSync(mainCssPath, MAIN_CSS, 'utf-8');
+    console.log(pc.green('  Created _styles/main.css'));
+  } else {
+    console.log(pc.dim('  _styles/main.css already exists (skipped)'));
+  }
+
+  console.log(pc.dim('\n  Next: run `climaybe build` or `climaybe serve`.\n'));
+}
+

package/src/commands/init.js

@@ -6,20 +6,20 @@ import {
   promptBuildWorkflows,
   promptDevKit,
   promptVSCodeDevTasks,
+  promptProjectName,
   promptCommitlint,
   promptCursorSkills,
   promptConfigureCISecrets,
   promptUpdateExistingSecrets,
   promptSecretValue,
-  promptTestThemeToken,
 } from '../lib/prompts.js';
-import { readConfig, writeConfig, getProjectType } from '../lib/config.js';
+import { readConfig, writeConfig, getProjectType, readPkg } 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 } from '../lib/commit-tooling.js';
 import { scaffoldCursorBundle } from '../lib/cursor-bundle.js';
-import { getMissingBuildWorkflowRequirements, getBuildScriptRelativePath, ensureBuildWorkflowDefaults } from '../lib/build-workflows.js';
+import { getMissingBuildWorkflowRequirements, ensureBuildWorkflowDefaults } from '../lib/build-workflows.js';
 import { getDevKitExistingFiles, scaffoldThemeDevKit } from '../lib/theme-dev-kit.js';
 import {
   isGhAvailable,
@@ -48,23 +48,36 @@ async function runInitFlow() {
   const enableBuildWorkflows = await promptBuildWorkflows();
   const enableDevKit = await promptDevKit();
   const enableVSCodeTasks = enableDevKit ? await promptVSCodeDevTasks() : false;
+  const projectName = enableDevKit && !readPkg() ? await promptProjectName() : undefined;
   const enableCommitlint = await promptCommitlint();
   const enableCursorSkills = await promptCursorSkills();
 
   console.log(pc.dim(`\n  Mode: ${mode}-store (${stores.length} store(s))`));
 
+  let missingBuildFiles = [];
   if (enableBuildWorkflows) {
     ensureBuildWorkflowDefaults();
-    const missingBuildFiles = getMissingBuildWorkflowRequirements();
+    missingBuildFiles = getMissingBuildWorkflowRequirements();
     if (missingBuildFiles.length > 0) {
       console.log(pc.red('\n  Build workflows are enabled, but required files are missing:'));
       for (const req of missingBuildFiles) {
         const expected = req.kind === 'dir' ? `${req.path}/` : req.path;
         console.log(pc.red(`    - ${expected}`));
       }
-      console.log(pc.dim(`\n  climaybe will auto-install ${getBuildScriptRelativePath()} during workflow scaffolding.`));
-      console.log(pc.dim('  Add the missing files above, then run init again.\n'));
-      return;
+      console.log(pc.dim('\n  Build workflows will be scaffolded, but build steps will be skipped until entrypoints exist.'));
+      const { createNow } = await prompts({
+        type: 'confirm',
+        name: 'createNow',
+        message: 'Create _scripts/main.js and _styles/main.css now?',
+        initial: false,
+      });
+      if (createNow) {
+        // Lazy import to avoid circular deps and keep init lean.
+        const { createEntrypointsCommand } = await import('./create-entrypoints.js');
+        await createEntrypointsCommand();
+      } else {
+        console.log(pc.dim('  Skipping entrypoint creation (default).'));
+      }
     }
   }
 
@@ -75,6 +88,7 @@ async function runInitFlow() {
     default_store: stores[0].domain,
     preview_workflows: enablePreviewWorkflows,
     build_workflows: enableBuildWorkflows,
+    build_entrypoints_ready: enableBuildWorkflows ? missingBuildFiles?.length === 0 : undefined,
     dev_kit: enableDevKit,
     vscode_tasks: enableVSCodeTasks,
     commitlint: enableCommitlint,
@@ -86,9 +100,9 @@ async function runInitFlow() {
     config.stores[s.alias] = s.domain;
   }
 
-  // 3. Write package.json config
+  // 3. Write climaybe config
   writeConfig(config);
-  console.log(pc.green('  Updated package.json config.'));
+  console.log(pc.green('  Updated climaybe config.'));
 
   // 4. Ensure git repo
   ensureGitRepo();
@@ -141,8 +155,9 @@ async function runInitFlow() {
     scaffoldThemeDevKit({
       includeVSCodeTasks: enableVSCodeTasks,
       defaultStoreDomain: stores[0]?.domain || '',
+      packageName: projectName || undefined,
     });
-    console.log(pc.green('  Theme dev kit installed (scripts/watch/lint + ignore defaults).'));
+    console.log(pc.green('  Theme dev kit installed (local config + ignore defaults).'));
   }
 
   // Done
@@ -245,26 +260,45 @@ async function runInitFlow() {
   console.log(pc.cyan(`\n  Configure ${totalToPrompt} ${setter.name} secret(s)/variable(s). Leave optional ones blank to skip.\n`));
   for (let i = 0; i < toPrompt.length; i++) {
     const secret = toPrompt[i];
-    const value = await promptSecretValue(secret, i, totalToPrompt);
-    if (!value) continue;
-
     const isThemeToken =
       secret.name === 'SHOPIFY_THEME_ACCESS_TOKEN' || secret.name.startsWith('SHOPIFY_THEME_ACCESS_TOKEN_');
     const storeUrl = isThemeToken ? getStoreUrlForThemeTokenSecret(secret.name, stores) : null;
 
-    if (storeUrl) {
-      const doTest = await promptTestThemeToken();
-      if (doTest) {
+    if (isThemeToken) {
+      if (!storeUrl) {
+        console.log(pc.red(`  Could not resolve store URL for required token ${secret.name}.`));
+        continue;
+      }
+      // Theme tokens are required and must validate; keep prompting until valid + set.
+      while (true) {
+        const value = await promptSecretValue(secret, i, totalToPrompt);
+        if (!value) {
+          console.log(pc.red('  Theme access token is required.'));
+          continue;
+        }
         const result = await validateThemeAccessToken(storeUrl, value);
         if (!result.ok) {
           console.log(pc.red(`  Token test failed: ${result.error}`));
-          console.log(pc.dim('  Secret not set. You can add it later in repo Settings → Secrets.'));
+          console.log(pc.dim('  Please try again with a valid Theme Access token.'));
           continue;
         }
         console.log(pc.green('  Token validated against store.'));
+        try {
+          await setter.set(secret.name, value);
+          console.log(pc.green(`  Set ${secret.name}.`));
+          setCount++;
+          break;
+        } catch (err) {
+          console.log(pc.red(`  Failed to set ${secret.name}: ${err.message}`));
+          console.log(pc.dim('  Please try entering the token again.'));
+        }
       }
+      continue;
     }
 
+    const value = await promptSecretValue(secret, i, totalToPrompt);
+    if (!value) continue;
+
     try {
       await setter.set(secret.name, value);
       console.log(pc.green(`  Set ${secret.name}.`));
@@ -284,7 +318,7 @@ export async function initCommand() {
   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'));
+    console.log(pc.dim('  To switch to theme CI/CD, remove or edit climaybe.config.json → project_type first.\n'));
     return;
   }
 

package/src/commands/migrate-legacy-config.js

@@ -0,0 +1,217 @@
+import prompts from 'prompts';
+import pc from 'picocolors';
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { migrateLegacyPackageConfigToClimaybe, readClimaybeConfig, readPkg, writePkg } from '../lib/config.js';
+import { updateWorkflowsCommand } from './update-workflows.js';
+import { requireThemeProject } from '../lib/theme-guard.js';
+import { getDevKitExistingFiles, scaffoldThemeDevKit } from '../lib/theme-dev-kit.js';
+
+const LEGACY_SCRIPT_KEYS = [
+  'shopify:serve',
+  'shopify:serve:sync',
+  'shopify:populate',
+  'scripts:build',
+  'scripts:watch',
+  'tailwind:watch',
+  'tailwind:build',
+  'dev',
+  'dev:theme',
+  'dev:assets',
+  'dev:no-sync',
+  'lint:liquid',
+  'lint:js',
+  'lint:css',
+  'release',
+  'prepare',
+];
+
+const LEGACY_DEP_NAMES = [
+  'concurrently',
+  'nodemon',
+  'tailwindcss',
+  '@tailwindcss/cli',
+  '@tailwindcss/typography',
+  'eslint',
+  '@eslint/js',
+  '@eslint/create-config',
+  'stylelint',
+  'stylelint-config-standard',
+  'prettier',
+  '@shopify/prettier-plugin-liquid',
+  '@commitlint/cli',
+  '@commitlint/config-conventional',
+  'husky',
+];
+
+function cleanupLegacyFiles(cwd) {
+  const candidates = [
+    '.climaybe/build-scripts.js',
+    'build-scripts.js',
+    '.climaybe/dev-with-sync.sh',
+    '.climaybe/dev.sh',
+  ];
+  const removed = [];
+  for (const rel of candidates) {
+    const abs = join(cwd, rel);
+    if (!existsSync(abs)) continue;
+    rmSync(abs, { force: true });
+    removed.push(rel);
+  }
+  return removed;
+}
+
+function cleanupLegacyPackageJson(cwd) {
+  const pkg = readPkg(cwd);
+  if (!pkg || typeof pkg !== 'object') return { removedScripts: [], removedDeps: [] };
+
+  const removedScripts = [];
+  if (pkg.scripts && typeof pkg.scripts === 'object') {
+    for (const key of LEGACY_SCRIPT_KEYS) {
+      if (key in pkg.scripts) {
+        delete pkg.scripts[key];
+        removedScripts.push(key);
+      }
+    }
+    if (Object.keys(pkg.scripts).length === 0) delete pkg.scripts;
+  }
+
+  const removedDeps = [];
+  for (const depField of ['dependencies', 'devDependencies']) {
+    const deps = pkg[depField];
+    if (!deps || typeof deps !== 'object') continue;
+    for (const name of LEGACY_DEP_NAMES) {
+      if (name in deps) {
+        delete deps[name];
+        removedDeps.push(`${depField}:${name}`);
+      }
+    }
+    if (Object.keys(deps).length === 0) delete pkg[depField];
+  }
+
+  writePkg(pkg, cwd);
+  return { removedScripts, removedDeps };
+}
+
+export async function migrateLegacyConfigCommand(options = {}) {
+  const overwrite = options.overwrite === true;
+  const updateWorkflows = options.updateWorkflows !== false;
+  const yes = options.yes === true;
+
+  console.log(pc.bold('\n  climaybe — Migrate legacy config\n'));
+
+  if (!requireThemeProject()) return;
+
+  const legacy = readPkg()?.config ?? null;
+  if (!legacy || typeof legacy !== 'object') {
+    console.log(pc.yellow('  No legacy package.json config found (package.json → config).'));
+    console.log(pc.dim('  Nothing to migrate.\n'));
+    return;
+  }
+
+  const existing = readClimaybeConfig();
+  if (existing && !overwrite) {
+    const ok = yes
+      ? true
+      : (
+          await prompts({
+            type: 'confirm',
+            name: 'ok',
+            message: 'A climaybe.config.json already exists. Overwrite it from package.json config?',
+            initial: false,
+          })
+        ).ok;
+    if (!ok) {
+      console.log(pc.dim('  Cancelled.\n'));
+      return;
+    }
+  }
+
+  const did = migrateLegacyPackageConfigToClimaybe({ overwrite: true });
+  if (!did) {
+    console.log(pc.yellow('  Migration skipped (no legacy config, or config already present).'));
+    console.log(pc.dim('  Tip: run with --overwrite to force rewrite.\n'));
+    return;
+  }
+
+  console.log(pc.green('  Migrated package.json config → climaybe.config.json'));
+
+  // Clean legacy dev system artifacts (sample-style package scripts, shims, old .climaybe scripts).
+  const cleanup = yes
+    ? true
+    : (
+        await prompts({
+          type: 'confirm',
+          name: 'cleanup',
+          message: 'Remove legacy dev scripts/deps from package.json and delete old local shims?',
+          initial: true,
+        })
+      ).cleanup;
+  if (cleanup) {
+    const removedFiles = cleanupLegacyFiles(process.cwd());
+    const { removedScripts, removedDeps } = cleanupLegacyPackageJson(process.cwd());
+    if (removedFiles.length > 0) {
+      console.log(pc.green(`  Removed legacy files: ${removedFiles.join(', ')}`));
+    }
+    if (removedScripts.length > 0) {
+      console.log(pc.green(`  Removed legacy package.json scripts: ${removedScripts.join(', ')}`));
+    }
+    if (removedDeps.length > 0) {
+      console.log(pc.green(`  Removed legacy package.json deps: ${removedDeps.join(', ')}`));
+    }
+  }
+
+  // Reinstall dev kit so tasks/theme-check config match the new climaybe runtime.
+  const reinstallDevKit = yes
+    ? true
+    : (
+        await prompts({
+          type: 'confirm',
+          name: 'reinstallDevKit',
+          message: 'Install/refresh climaybe dev kit files (.vscode/tasks.json, etc.)?',
+          initial: true,
+        })
+      ).reinstallDevKit;
+  if (reinstallDevKit) {
+    const existing = getDevKitExistingFiles({ includeVSCodeTasks: true });
+    if (existing.length > 0) {
+      console.log(pc.yellow('  Some dev kit files already exist and will be replaced:'));
+      for (const path of existing) console.log(pc.yellow(`    - ${path}`));
+      const ok = yes
+        ? true
+        : (
+            await prompts({
+              type: 'confirm',
+              name: 'ok',
+              message: 'Replace these files?',
+              initial: true,
+            })
+          ).ok;
+      if (!ok) {
+        console.log(pc.dim('  Skipped dev kit refresh.\n'));
+      } else {
+        const legacy = readPkg()?.config ?? {};
+        scaffoldThemeDevKit({
+          includeVSCodeTasks: true,
+          defaultStoreDomain: legacy.default_store || legacy.store || '',
+        });
+        console.log(pc.green('  Dev kit refreshed.'));
+      }
+    } else {
+      const legacy = readPkg()?.config ?? {};
+      scaffoldThemeDevKit({
+        includeVSCodeTasks: true,
+        defaultStoreDomain: legacy.default_store || legacy.store || '',
+      });
+      console.log(pc.green('  Dev kit installed.'));
+    }
+  }
+
+  if (updateWorkflows) {
+    console.log(pc.dim('\n  Updating workflows to use climaybe.config.json...\n'));
+    await updateWorkflowsCommand();
+  } else {
+    console.log(pc.dim('  Skipped workflow update (pass --update-workflows to refresh).\n'));
+  }
+}
+