climaybe 2.4.2 → 3.0.1

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'));
+  }
+}
+

package/src/index.js

@@ -9,6 +9,10 @@ import { setupCommitlintCommand } from './commands/setup-commitlint.js';
 import { addCursorSkillCommand } from './commands/add-cursor-skill.js';
 import { addDevKitCommand } from './commands/add-dev-kit.js';
 import { appInitCommand } from './commands/app-init.js';
+import { migrateLegacyConfigCommand } from './commands/migrate-legacy-config.js';
+import { buildScriptsCommand } from './commands/build-scripts.js';
+import { createEntrypointsCommand } from './commands/create-entrypoints.js';
+import { serveAll, serveAssets, serveShopify, lintAll, buildAll } from './lib/dev-runtime.js';
 
 /**
  * Register theme CI/CD commands on a Commander instance (root or `theme` subgroup).
@@ -44,9 +48,38 @@ function registerThemeCommands(cmd) {
 
   cmd
     .command('add-dev-kit')
-    .description('Install/update local theme dev kit files (scripts, lint, ignores, optional VS Code tasks)')
+    .description('Install/update local theme dev kit files (configs, ignores, optional VS Code tasks)')
     .action(addDevKitCommand);
 
+  cmd
+    .command('migrate-legacy-config')
+    .description('Migrate legacy package.json config to climaybe.config.json (optional workflow refresh)')
+    .option('--overwrite', 'Overwrite existing climaybe.config.json')
+    .option('-y, --yes', 'Non-interactive; assume "yes" for prompts')
+    .option('--no-update-workflows', 'Do not refresh workflows after migrating')
+    .action(migrateLegacyConfigCommand);
+
+  cmd
+    .command('serve')
+    .description('Run local theme dev (Shopify + assets + Theme Check)')
+    .option('--no-theme-check', 'Disable Theme Check watcher')
+    .action((opts) => serveAll({ includeThemeCheck: opts.themeCheck !== false }));
+  cmd.command('serve:shopify').description('Run Shopify theme dev server').action(() => serveShopify());
+  cmd
+    .command('serve:assets')
+    .description('Run assets watch (Tailwind + scripts + Theme Check)')
+    .option('--no-theme-check', 'Disable Theme Check watcher')
+    .action((opts) => serveAssets({ includeThemeCheck: opts.themeCheck !== false }));
+
+  cmd.command('lint').description('Run theme linting (liquid, js, css)').action(() => lintAll());
+
+  cmd.command('build').description('Build assets (Tailwind + scripts build)').action(() => buildAll());
+  cmd.command('build-scripts').description('Build _scripts → assets/index.js').action(buildScriptsCommand);
+  cmd
+    .command('create-entrypoints')
+    .description('Create _scripts/main.js and _styles/main.css (optional)')
+    .action(createEntrypointsCommand);
+
   cmd
     .command('update-workflows')
     .description('Refresh GitHub Actions workflows from latest bundled templates')
@@ -84,7 +117,7 @@ export function createProgram(version = '0.0.0', packageDir = '') {
   const app = program.command('app').description('Shopify app repo helpers (no theme workflows)');
   app
     .command('init')
-    .description('Set up commitlint, Cursor bundle (rules/skills/agents), and project_type: app in package.json')
+    .description('Set up commitlint, Cursor bundle (rules/skills/agents), and project_type: app in climaybe.config.json')
     .action(appInitCommand);
 
   program
@@ -104,5 +137,7 @@ export function createProgram(version = '0.0.0', packageDir = '') {
 }
 
 export function run(argv, version, packageDir = '') {
+  if (packageDir) process.env.CLIMAYBE_PACKAGE_DIR = packageDir;
+  if (version) process.env.CLIMAYBE_PACKAGE_VERSION = version;
   createProgram(version, packageDir).parse(argv);
 }

package/src/lib/build-scripts.js

@@ -0,0 +1,153 @@
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { join, basename, dirname, normalize } from 'node:path';
+
+function extractImports(content) {
+  const imports = [];
+  // Supports compact imports (import{a}from"./x"), multiline forms,
+  // and import attributes (with { type: "json" }).
+  const fromImportRegex =
+    /(^|\n)\s*import(?:\s+type)?\s*[\s\S]*?\s*\bfrom\b\s*['"]([^'"]+)['"](?:\s+with\s*\{[\s\S]*?\})?\s*;?/g;
+  const sideEffectImportRegex = /(^|\n)\s*import\s*['"]([^'"]+)['"](?:\s+with\s*\{[\s\S]*?\})?\s*;?/g;
+  let match;
+
+  while ((match = fromImportRegex.exec(content)) !== null) {
+    imports.push(match[2]);
+  }
+  while ((match = sideEffectImportRegex.exec(content)) !== null) {
+    imports.push(match[2]);
+  }
+
+  return imports;
+}
+
+function stripModuleSyntax(content) {
+  // Remove import statements (including multiline/compact forms and import attributes).
+  let cleaned = content.replace(
+    /(^|\n)\s*import(?:\s+type)?\s*[\s\S]*?\s*\bfrom\b\s*['"][^'"]+['"](?:\s+with\s*\{[\s\S]*?\})?\s*;?/g,
+    '$1'
+  );
+  cleaned = cleaned.replace(/(^|\n)\s*import\s*['"][^'"]+['"](?:\s+with\s*\{[\s\S]*?\})?\s*;?/g, '$1');
+
+  // Fallback: ensure no standalone import declarations leak into bundle output.
+  cleaned = cleaned.replace(/^[ \t]*import\s*['"][^'"]+['"][ \t]*;?[ \t]*$/gm, '');
+  cleaned = cleaned.replace(
+    /^[ \t]*import(?:\s+type)?[ \t]*[^;\n\r]*\bfrom\b[ \t]*['"][^'"]+['"][ \t]*(?:with[ \t]*\{[^}\n\r]*\})?[ \t]*;?[ \t]*$/gm,
+    ''
+  );
+
+  cleaned = cleaned.replace(/^\s*export\s+default\s+/gm, '');
+  cleaned = cleaned.replace(/^\s*export\s+\{[^}]*\}\s*;?\s*$/gm, '');
+  cleaned = cleaned.replace(/^\s*export\s+(?=(const|let|var|function|class)\b)/gm, '');
+  return cleaned;
+}
+
+function processScriptFile({ scriptsDir, filePath, processedFiles }) {
+  if (processedFiles.has(filePath)) return '';
+  processedFiles.add(filePath);
+
+  const fullPath = join(scriptsDir, filePath);
+  if (!existsSync(fullPath)) {
+    // Keep going; missing optional imports shouldn't hard fail local dev
+    // (CI will still fail later if output is invalid).
+    // eslint-disable-next-line no-console
+    console.warn(`Warning: File ${filePath} not found`);
+    return '';
+  }
+
+  let content = readFileSync(fullPath, 'utf8');
+  const imports = extractImports(content);
+
+  let importedContent = '';
+  for (const importPath of imports) {
+    const resolvedImport = resolveImportPath(filePath, importPath);
+    if (!resolvedImport) continue;
+    importedContent += processScriptFile({ scriptsDir, filePath: resolvedImport, processedFiles });
+  }
+
+  content = stripModuleSyntax(content);
+
+  if (process.env.NODE_ENV === 'production') {
+    content = content.replace(/\/\*\*[\s\S]*?\*\//g, '');
+    content = content.replace(/^\s*\*.*$/gm, '');
+    content = content.replace(/console\.(log|warn|error)\([^)]*\);?\s*/g, '');
+    content = content.replace(/^\s*\n/gm, '');
+  }
+
+  return importedContent + '\n' + content;
+}
+
+function resolveImportPath(fromFilePath, importPath) {
+  // Only bundle local relative imports from _scripts.
+  if (!importPath || (!importPath.startsWith('./') && !importPath.startsWith('../'))) {
+    return null;
+  }
+  const fromDir = dirname(fromFilePath);
+  const resolved = normalize(join(fromDir, importPath)).replace(/\\/g, '/');
+  return resolved.startsWith('./') ? resolved.slice(2) : resolved;
+}
+
+function collectImportedFiles({ scriptsDir, entryFile, seen = new Set() }) {
+  if (seen.has(entryFile)) return seen;
+  seen.add(entryFile);
+
+  const fullPath = join(scriptsDir, entryFile);
+  if (!existsSync(fullPath)) return seen;
+  const content = readFileSync(fullPath, 'utf8');
+  const imports = extractImports(content);
+  for (const importPath of imports) {
+    const resolved = resolveImportPath(entryFile, importPath);
+    if (!resolved) continue;
+    collectImportedFiles({ scriptsDir, entryFile: resolved, seen });
+  }
+  return seen;
+}
+
+function listTopLevelEntrypoints(scriptsDir) {
+  if (!existsSync(scriptsDir)) return [];
+  return readdirSync(scriptsDir, { withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith('.js'))
+    .map((d) => d.name)
+    .sort();
+}
+
+function outputNameForEntrypoint(entryFile) {
+  if (entryFile === 'main.js') return 'index.js';
+  return basename(entryFile);
+}
+
+function buildSingleEntrypoint({ cwd, entryFile }) {
+  const scriptsDir = join(cwd, '_scripts');
+  const entryPath = join(scriptsDir, entryFile);
+  if (!existsSync(entryPath)) {
+    throw new Error(`Missing required file: _scripts/${entryFile}`);
+  }
+
+  const processedFiles = new Set();
+  let finalContent = processScriptFile({ scriptsDir, filePath: entryFile, processedFiles });
+  finalContent = stripModuleSyntax(finalContent);
+
+  const assetsDir = join(cwd, 'assets');
+  mkdirSync(assetsDir, { recursive: true });
+
+  const outFile = outputNameForEntrypoint(entryFile);
+  const outputPath = join(assetsDir, outFile);
+  writeFileSync(outputPath, finalContent.trim() + '\n', 'utf-8');
+
+  return { entryFile, fileCount: processedFiles.size, outputPath };
+}
+
+export function buildScripts({ cwd = process.cwd(), entry = null } = {}) {
+  const scriptsDir = join(cwd, '_scripts');
+  let entrypoints = entry ? [entry.endsWith('.js') ? entry : `${entry}.js`] : listTopLevelEntrypoints(scriptsDir);
+  if (!entry && entrypoints.includes('main.js')) {
+    const importedByMain = collectImportedFiles({ scriptsDir, entryFile: 'main.js' });
+    importedByMain.delete('main.js');
+    entrypoints = entrypoints.filter((ep) => ep === 'main.js' || !importedByMain.has(ep));
+  }
+  if (entrypoints.length === 0) {
+    return { bundles: [] };
+  }
+  const bundles = entrypoints.map((entryFile) => buildSingleEntrypoint({ cwd, entryFile }));
+  return { bundles };
+}
+

package/src/lib/build-workflows.js

@@ -1,20 +1,5 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const SCRIPT_SOURCE = fileURLToPath(new URL('../workflows/build/build-scripts.js', import.meta.url));
-const SCRIPT_TARGET = '.climaybe/build-scripts.js';
-const SCRIPT_SHIM_TARGET = 'build-scripts.js';
-const SCRIPT_SHIM_CONTENT = `// Auto-generated by climaybe. Keep for npm scripts compatibility.
-// Delegates to the bundled implementation in .climaybe/.
-const { buildScripts } = require('./.climaybe/build-scripts.js');
-
-if (require.main === module) {
-  buildScripts();
-}
-
-module.exports = { buildScripts };
-`;
 
 const REQUIRED_PATHS = [
   { path: '_scripts/main.js', kind: 'file' },
@@ -25,32 +10,6 @@ const DEFAULTS = [
   { path: 'assets', kind: 'dir' },
 ];
 
-function targetScriptPath(cwd = process.cwd()) {
-  return join(cwd, SCRIPT_TARGET);
-}
-
-export function installBuildScript(cwd = process.cwd()) {
-  const target = targetScriptPath(cwd);
-  mkdirSync(join(cwd, '.climaybe'), { recursive: true });
-  copyFileSync(SCRIPT_SOURCE, target);
-  const shimTarget = join(cwd, SCRIPT_SHIM_TARGET);
-  if (!existsSync(shimTarget)) {
-    writeFileSync(shimTarget, SCRIPT_SHIM_CONTENT, 'utf-8');
-  }
-  return target;
-}
-
-export function removeBuildScript(cwd = process.cwd()) {
-  const target = targetScriptPath(cwd);
-  if (existsSync(target)) rmSync(target);
-  const shimTarget = join(cwd, SCRIPT_SHIM_TARGET);
-  if (!existsSync(shimTarget)) return;
-  const content = readFileSync(shimTarget, 'utf-8');
-  if (content === SCRIPT_SHIM_CONTENT) {
-    rmSync(shimTarget);
-  }
-}
-
 export function getMissingBuildWorkflowRequirements(cwd = process.cwd()) {
   const missing = [];
   for (const req of REQUIRED_PATHS) {
@@ -75,5 +34,6 @@ export function ensureBuildWorkflowDefaults(cwd = process.cwd()) {
 }
 
 export function getBuildScriptRelativePath() {
-  return SCRIPT_TARGET;
+  // Legacy; build-scripts are now part of climaybe runtime.
+  return 'n/a';
 }

package/src/lib/config.js

@@ -1,8 +1,22 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { getLatestTagVersion } from './git.js';
 
 const PKG = 'package.json';
+const CLIMAYBE_CONFIG = 'climaybe.config.json';
+const LEGACY_CLIMAYBE_DIR = '.climaybe';
+const LEGACY_CLIMAYBE_CONFIG = 'config.json';
+
+/**
+ * Resolve absolute path to root climaybe config file.
+ */
+function climaybeConfigPath(cwd = process.cwd()) {
+  return join(cwd, CLIMAYBE_CONFIG);
+}
+
+function legacyClimaybeConfigPath(cwd = process.cwd()) {
+  return join(cwd, LEGACY_CLIMAYBE_DIR, LEGACY_CLIMAYBE_CONFIG);
+}
 
 /**
  * Resolve absolute path to the target repo's package.json.
@@ -12,6 +26,15 @@ function pkgPath(cwd = process.cwd()) {
   return join(cwd, PKG);
 }
 
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function writeJson(path, obj) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
 /**
  * Read the full package.json from a target repo.
  * Returns null if it doesn't exist.
@@ -20,21 +43,46 @@ function pkgPath(cwd = process.cwd()) {
 export function readPkg(cwd = process.cwd()) {
   const p = pkgPath(cwd);
   if (!existsSync(p)) return null;
-  return JSON.parse(readFileSync(p, 'utf-8'));
+  return readJson(p);
 }
 
 /**
  * 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');
+  writeJson(pkgPath(cwd), pkg);
+}
+
+/**
+ * Read the climaybe config from root file (with legacy fallback).
+ * Returns null if neither exists.
+ */
+export function readClimaybeConfig(cwd = process.cwd()) {
+  const p = climaybeConfigPath(cwd);
+  if (existsSync(p)) return readJson(p);
+  const legacy = legacyClimaybeConfigPath(cwd);
+  if (existsSync(legacy)) return readJson(legacy);
+  return null;
 }
 
 /**
- * Read the climaybe config section from package.json.
- * Returns null if package.json or config section doesn't exist.
+ * Write/merge climaybe config into root config file.
+ */
+export function writeClimaybeConfig(config, cwd = process.cwd()) {
+  const current = readClimaybeConfig(cwd) || {};
+  const next = { ...current, ...config };
+  writeJson(climaybeConfigPath(cwd), next);
+}
+
+/**
+ * Read the climaybe config (source of truth).
+ * - Primary: climaybe.config.json
+ * - Back-compat: .climaybe/config.json
+ * - Legacy fallback: package.json → config
  */
 export function readConfig(cwd = process.cwd()) {
+  const cfg = readClimaybeConfig(cwd);
+  if (cfg) return cfg;
   const pkg = readPkg(cwd);
   return pkg?.config ?? null;
 }
@@ -42,17 +90,24 @@ export function readConfig(cwd = process.cwd()) {
 /**
  * @typedef {object} WriteConfigOptions
  * @property {string} [defaultPackageName] - When creating package.json, set `name` (default: shopify-theme).
+ * @property {boolean} [alsoWriteLegacyPackageConfig] - Also write package.json config (default: false).
  */
 
 /**
- * Write/merge the climaybe config section into package.json.
- * Creates package.json if it doesn't exist.
+ * Write/merge the climaybe config (source of truth: climaybe.config.json).
+ * Optionally writes legacy package.json config for transitional repos.
  * @param {object} config
  * @param {string} [cwd]
  * @param {WriteConfigOptions} [options]
  */
 export function writeConfig(config, cwd = process.cwd(), options = {}) {
   const defaultPackageName = options.defaultPackageName ?? 'shopify-theme';
+  const alsoWriteLegacyPackageConfig = options.alsoWriteLegacyPackageConfig ?? false;
+
+  writeClimaybeConfig(config, cwd);
+
+  if (!alsoWriteLegacyPackageConfig) return;
+
   let pkg = readPkg(cwd);
   if (!pkg) {
     let version = '1.0.0';
@@ -73,6 +128,21 @@ export function writeConfig(config, cwd = process.cwd(), options = {}) {
   writePkg(pkg, cwd);
 }
 
+/**
+ * Migrate legacy package.json config into climaybe.config.json.
+ * Returns true if migration wrote a config file.
+ */
+export function migrateLegacyPackageConfigToClimaybe({ cwd = process.cwd(), overwrite = false } = {}) {
+  const legacy = readPkg(cwd)?.config ?? null;
+  if (!legacy || typeof legacy !== 'object') return false;
+
+  const existing = readClimaybeConfig(cwd);
+  if (existing && !overwrite) return false;
+
+  writeJson(climaybeConfigPath(cwd), legacy);
+  return true;
+}
+
 /**
  * Resolved project kind for guards and init flows.
  * - `app` only when config explicitly sets project_type: app.