@elliemae/pui-cli 9.0.0-alpha.11 → 9.0.0-alpha.13

package/dist/cjs/babel.config.js

@@ -0,0 +1,124 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var babel_config_exports = {};
+__export(babel_config_exports, {
+  babelConfig: () => babelConfig,
+  default: () => babel_config_default
+});
+module.exports = __toCommonJS(babel_config_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+const isApp = () => import_node_fs.default.existsSync(import_node_path.default.join(process.cwd(), "app"));
+const nodeEnvPreset = {
+  modules: process.env.ES_MODULES === "false" ? "commonjs" : false,
+  targets: {
+    node: "current"
+  }
+};
+const webEnvPreset = {
+  modules: process.env.ES_MODULES === "false" ? "commonjs" : false,
+  useBuiltIns: "usage",
+  corejs: { version: "3.36", proposals: true }
+};
+const presetEnvOptions = process.env.TARGET_ENV === "node" ? nodeEnvPreset : webEnvPreset;
+const config = {
+  ignore: [/\/core-js/],
+  sourceType: "unambiguous",
+  presets: [
+    ["@babel/preset-env", presetEnvOptions],
+    ["@babel/preset-react", { runtime: "automatic" }],
+    "@babel/preset-typescript"
+  ],
+  plugins: [
+    [
+      "babel-plugin-module-resolver",
+      {
+        alias: {
+          "@": isApp() ? "./app" : "./lib"
+        },
+        stripExtensions: []
+      }
+    ],
+    ["babel-plugin-styled-components", { displayName: true }],
+    ["@babel/plugin-transform-runtime", { regenerator: true }],
+    "@babel/plugin-proposal-class-properties",
+    "@babel/plugin-transform-private-methods",
+    "@babel/plugin-transform-private-property-in-object",
+    "@babel/plugin-syntax-dynamic-import",
+    "@babel/plugin-proposal-export-default-from",
+    "lodash",
+    "date-fns"
+  ],
+  env: {
+    development: {
+      plugins: [
+        ["babel-plugin-styled-components", { displayName: true }],
+        "@babel/plugin-transform-react-jsx-source"
+      ]
+    },
+    production: {
+      plugins: [
+        ["babel-plugin-styled-components", { displayName: false, pure: true }],
+        ["transform-remove-console", { exclude: ["error", "warn"] }],
+        "transform-react-remove-prop-types",
+        "@babel/plugin-transform-react-inline-elements",
+        "@babel/plugin-transform-react-constant-elements"
+      ]
+    },
+    test: {
+      plugins: [
+        ["babel-plugin-styled-components", { displayName: true }],
+        "@babel/plugin-transform-modules-commonjs",
+        "dynamic-import-node",
+        [
+          "babel-plugin-transform-strip-block",
+          {
+            requireDirective: true,
+            identifiers: [{ start: "block:start", end: "block:end" }]
+          }
+        ],
+        "babel-plugin-import-remove-resource-query"
+      ]
+    }
+  }
+};
+if (process.env.STORYBOOK_BUILD !== "true" && process.env.TARGET_ENV !== "node") {
+  config.env?.development?.plugins?.push?.("react-refresh/babel");
+}
+if (process.env.ES_MODULES === "false") {
+  config.plugins?.push?.([
+    "babel-plugin-transform-strip-block",
+    {
+      requireDirective: true,
+      identifiers: [{ start: "block:start", end: "block:end" }]
+    }
+  ]);
+}
+const babelConfig = config;
+var babel_config_default = babelConfig;

package/dist/cjs/commands/storybook.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,22 +17,45 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var storybook_exports = {};
 __export(storybook_exports, {
   storybookCmd: () => storybookCmd
 });
 module.exports = __toCommonJS(storybook_exports);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_url = require("node:url");
 var import_utils = require("./utils.js");
+const import_meta = {};
+const DEFAULT_PORT = 11e3;
+const puiCliRoot = import_node_path.default.resolve(
+  import_node_path.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)),
+  "../../.."
+);
+const storybookBin = import_node_path.default.join(puiCliRoot, "node_modules/.bin/storybook");
+const crossEnvBin = import_node_path.default.join(puiCliRoot, "node_modules/.bin/cross-env");
+const puiCliNodeModules = import_node_path.default.join(puiCliRoot, "node_modules");
+const getStorybookEnv = () => {
+  const nodePath = [puiCliNodeModules, process.env.NODE_PATH].filter(Boolean).join(import_node_path.default.delimiter);
+  return `NODE_PATH="${nodePath}"`;
+};
 const buildStoryBook = async (outputDir = "demo", isDoc = false) => {
   const additionalParams = isDoc ? `--docs -o ${outputDir}/docs` : `-o ${outputDir}`;
   await (0, import_utils.exec)(
-    `cross-env NODE_ENV=production build-storybook --quiet ${additionalParams}`
+    `"${crossEnvBin}" ${getStorybookEnv()} NODE_ENV=production "${storybookBin}" build --quiet ${additionalParams}`
   );
 };
-const startStoryBook = async (isDoc = false) => {
+const startStoryBook = async (isDoc = false, port = DEFAULT_PORT) => {
   await (0, import_utils.exec)(
-    `cross-env NODE_ENV=development STORYBOOK_BUILD=true start-storybook ${isDoc ? "--docs" : ""} -p 11000 --quiet`
+    `"${crossEnvBin}" ${getStorybookEnv()} NODE_ENV=development STORYBOOK_BUILD=true "${storybookBin}" dev ${isDoc ? "--docs" : ""} -p ${port} --quiet`
   );
 };
 const cmdArgs = {
@@ -47,13 +72,17 @@ const cmdArgs = {
     string: true,
     alias: "o",
     default: "demo"
+  },
+  port: {
+    number: true,
+    default: DEFAULT_PORT
   }
 };
 const storybookCmd = {
   handler: async (argv) => {
     try {
       if (!argv.build) {
-        await startStoryBook(argv.docs);
+        await startStoryBook(argv.docs, argv.port);
         (0, import_utils.logInfo)("Storybook started");
       } else {
         await buildStoryBook(argv.output, argv.docs);

package/dist/cjs/index.js

@@ -20,8 +20,6 @@ var index_exports = {};
 __export(index_exports, {
   babelConfig: () => import_babel_config.babelConfig,
   commitlintConfig: () => import_commitlint_config.commitlintConfig,
-  eslintBaseConfig: () => import_non_react.esConfig,
-  eslintConfig: () => import_react.esReactConfig,
   eslintFlatBaseConfig: () => import_non_react_export.eslintFlatBaseConfig,
   eslintFlatBaseConfigStrict: () => import_non_react_export.eslintFlatBaseConfigStrict,
   eslintFlatConfig: () => import_react_export.eslintFlatConfig,
@@ -35,16 +33,14 @@ __export(index_exports, {
   vitestConfig: () => import_vitest_config.vitestConfig
 });
 module.exports = __toCommonJS(index_exports);
-var import_babel_config = require("./babel.config.cjs");
+var import_babel_config = require("./babel.config.js");
 var import_non_react_export = require("./lint-config/eslint/flat/non-react-export.mjs");
 var import_react_export = require("./lint-config/eslint/flat/react-export.mjs");
-var import_non_react = require("./lint-config/eslint/non-react.cjs");
-var import_react = require("./lint-config/eslint/react.cjs");
 var import_export = require("./lint-config/stylelint/export.mjs");
-var import_prettier_config = require("./lint-config/prettier.config.cjs");
-var import_commitlint_config = require("./lint-config/commitlint.config.cjs");
-var import_jest_config = require("./testing/jest.config.cjs");
+var import_prettier_config = require("./lint-config/prettier.config.mjs");
+var import_commitlint_config = require("./lint-config/commitlint.config.mjs");
+var import_jest_config = require("./testing/jest.config.mjs");
 var import_vitest_config = require("./testing/vitest.config.js");
-var import_jest_node_config = require("./testing/jest.node.config.cjs");
+var import_jest_node_config = require("./testing/jest.node.config.mjs");
 var import_lint_staged_config = require("./lint-config/lint-staged.config.js");
 var import_appRoutes = require("./server/appRoutes.js");

package/dist/cjs/lint-config/commitlint/export.mjs

@@ -0,0 +1 @@
+export { commitlintConfig, default } from '../commitlint.config.mjs';

package/dist/cjs/lint-config/commitlint.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('@commitlint/types').UserConfig} */
+export const commitlintConfig = {
+  extends: ['@commitlint/config-conventional'],
+};
+
+export default commitlintConfig;

package/dist/cjs/lint-config/eslint/common.cjs

@@ -1,5 +1,12 @@
  
-const prettierOptions = require("../prettier.config.cjs");
+const prettierOptions = {
+  printWidth: 80,
+  tabWidth: 2,
+  useTabs: false,
+  semi: true,
+  singleQuote: true,
+  trailingComma: 'all',
+};
 // const webpackConfig = require('../../webpack/webpack.prod.babel');
 
 exports.baseExtends = [

package/dist/cjs/lint-config/eslint/flat/compat.mjs

@@ -2,7 +2,7 @@
  * ESLint 10 removed deprecated context APIs (e.g. getSourceCode, getScope, getFilename).
  * Wrap legacy plugins via @eslint/compat v2 (ESLint 10–aware fixupPluginRules).
  */
-import { fixupConfigRules, fixupPluginRules } from '@eslint/compat';
+import { fixupPluginRules } from '@eslint/compat';
 import react from 'eslint-plugin-react';
 import reduxSaga from 'eslint-plugin-redux-saga';
 import storybook from 'eslint-plugin-storybook';
@@ -20,8 +20,8 @@ export const reactPlugin = fixupPluginRules(react);
 /** @type {import('eslint').ESLint.Plugin} */
 export const reduxSagaPlugin = fixupPluginRules(reduxSaga);
 
-/** Storybook flat presets — uses legacy context APIs (eslint-plugin-storybook@0.12). */
+/** Storybook flat presets — native flat config (eslint-plugin-storybook@10). */
 /** @type {import('eslint').Linter.Config[]} */
-export const storybookFlatConfigs = fixupConfigRules(
-  Array.isArray(storybookFlat) ? storybookFlat : [storybookFlat],
-);
+export const storybookFlatConfigs = Array.isArray(storybookFlat)
+  ? storybookFlat
+  : [storybookFlat];

package/dist/cjs/lint-config/eslint/flat/rules.mjs

@@ -182,4 +182,5 @@ export const ignorePatterns = [
   '**/.scannerwork/**',
   '**/stats.json',
   '**/jsconfig.json',
+  './babel.config.ts',
 ];

package/dist/cjs/lint-config/lint-staged.config.js

@@ -34,11 +34,23 @@ module.exports = __toCommonJS(lint_staged_config_exports);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_node_fs = __toESM(require("node:fs"), 1);
 const npmClient = import_node_fs.default.existsSync(import_node_path.default.join(process.cwd(), "pnpm-lock.yaml")) ? "pnpm" : "npm";
+const filterRootBabelConfig = (files) => files.filter(
+  (file) => import_node_path.default.relative(process.cwd(), file) !== "babel.config.ts"
+);
+const filterTscheckFiles = filterRootBabelConfig;
 const lintStagedConfig = {
   "*.{js,ts,jsx,tsx,md,mdx,html,css,json}": ["prettier --write"],
-  "*.{ts,tsx}": [`${npmClient} run tscheck`],
-  "*.{js,ts,jsx,tsx}": [
-    `${npmClient} run lint:fix`,
-    `${npmClient} run test:staged`
-  ]
+  "*.{ts,tsx}": (files) => {
+    const filesToCheck = filterTscheckFiles(files);
+    if (!filesToCheck.length) return [];
+    return [`${npmClient} run tscheck -- ${filesToCheck.join(" ")}`];
+  },
+  "*.{js,ts,jsx,tsx}": (files) => {
+    const filesToLint = filterRootBabelConfig(files);
+    if (!filesToLint.length) return [];
+    return [
+      `${npmClient} run lint:fix -- ${filesToLint.join(" ")}`,
+      `${npmClient} run test:staged -- ${filesToLint.join(" ")}`
+    ];
+  }
 };

package/dist/cjs/lint-config/prettier/export.mjs

@@ -0,0 +1 @@
+export { prettierConfig, default } from '../prettier.config.mjs';

package/dist/cjs/lint-config/{prettier.config.cjs → prettier.config.mjs}

@@ -1,4 +1,5 @@
-exports.prettierConfig = {
+/** @type {import('prettier').Config} */
+export const prettierConfig = {
   printWidth: 80,
   tabWidth: 2,
   useTabs: false,
@@ -6,3 +7,5 @@ exports.prettierConfig = {
   singleQuote: true,
   trailingComma: 'all',
 };
+
+export default prettierConfig;

package/dist/cjs/skills/migrate-storybook-out-of-cjs/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: migrate-storybook-out-of-cjs
+description: >-
+  Migrate PUI Storybook from CJS wrappers and @elliemae/pui-app-sdk/storybook/cjs/* to ESM
+  (.storybook/*.mjs) and @elliemae/pui-app-sdk/storybook/* imports. Use when upgrading Storybook
+  10 with pui-cli 9, bumping to latest pui-app-sdk, replacing require() in .storybook/main.js,
+  removing storybook/cjs/main or storybook/cjs/middleware, deleting .storybook/middleware.js,
+  or converting preview/manager/theme to ESM.
+---
+
+# Migrate Storybook out of CJS (Storybook 10 + latest pui-app-sdk)
+
+Moves consumer repos from legacy CommonJS Storybook wrappers (`require('@elliemae/pui-app-sdk/storybook/cjs/...')`) to ESM (`.storybook/*.mjs` + `@elliemae/pui-app-sdk/storybook/*`).
+
+Requires **pui-cli 9** and a matching **pui-app-sdk** release on the same train. The `storybook/cjs/*` package paths are **removed** from pui-app-sdk — repos still on CJS imports will fail at install or runtime.
+
+For the full pui-cli 9 upgrade (Node 24, ESLint 10, etc.), install `migrate-to-pui-cli-9` first or in parallel.
+
+## When to use
+
+- `.storybook/main.js` uses `require('@elliemae/pui-app-sdk/storybook/cjs/main')`
+- `.storybook/middleware.js` exists or imports `storybook/cjs/middleware`
+- Storybook fails after bumping pui-app-sdk with “Cannot find module …/storybook/cjs/…”
+- Storybook fails with `Cannot find module '…/dist/esm/utils/storybook/main.js'` (app-sdk not built)
+- Moving from Storybook 6 CJS config to Storybook 10 ESM config with pui-cli
+
+## pui-app-sdk changes (latest Storybook 10 train)
+
+| Topic           | Before                                          | After                                                                                |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Import path     | `@elliemae/pui-app-sdk/storybook/cjs/main`      | `@elliemae/pui-app-sdk/storybook/main`                                               |
+| Export name     | `getConfig()`                                   | **`getStorybookConfig(viteBuilder?)`**                                               |
+| Published files | CJS under `storybook/cjs/`                      | TypeScript in repo; **`dist/esm\|cjs/utils/storybook/*`** at runtime                 |
+| Shared modules  | `cjs/main`, `cjs/webpack`, …                    | `main`, `preview`, `manager`, `theme`, `webpack`, `vite`, `middleware` (deprecated)  |
+| app-sdk dogfood | CJS + SB6 webpack hacks in `.storybook/main.js` | **`.storybook/*.ts`** → `../lib/utils/storybook/*` (source; not package self-import) |
+
+Consumers **must** import compiled dist (`@elliemae/pui-app-sdk/storybook/*`). After a local `file:` link, run **`pnpm run build`** in app-sdk before Storybook.
+
+## What changed (consumers)
+
+| Topic             | Before (CJS / SB6)                         | After (ESM / SB10)                                                                                                                         |
+| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Consumer config   | `.storybook/main.js`                       | `.storybook/main.mjs`                                                                                                                      |
+| Shared import     | `@elliemae/pui-app-sdk/storybook/cjs/main` | `@elliemae/pui-app-sdk/storybook/main`                                                                                                     |
+| Export name       | `getConfig()` (CJS default)                | **`getStorybookConfig()`** (named export)                                                                                                  |
+| API mocks         | `.storybook/middleware.js`                 | Built into pui-cli Storybook dev server                                                                                                    |
+| Preview / manager | `.storybook/preview.js`, `manager.js`      | `.storybook/preview.mjs`, `manager.mjs` (when using ESM imports)                                                                           |
+| CLI               | `start-storybook` / `build-storybook`      | `pui-cli storybook` → `storybook dev` / `storybook build`                                                                                  |
+| Addons            | Installed in consumer `package.json`       | Bundled in pui-cli; referenced by package name in app-sdk config                                                                           |
+| MDX docs          | `*.stories.mdx`                            | Docs-only pages: **`*.mdx`** + `@storybook/addon-docs/blocks`                                                                              |
+| Babel (Storybook) | SWC / ad-hoc overrides                     | `@storybook/addon-webpack5-compiler-babel` + project **`babel.config.ts`** → pui-cli `babelConfig` (includes private class fields/methods) |
+
+## Pre-flight
+
+1. Bump `@elliemae/pui-cli@9` and `@elliemae/pui-app-sdk@*` together.
+2. Run `pnpm install`. If using a local `file:` link to pui-app-sdk, **`pnpm run build`** in app-sdk, then reinstall in the consumer so `dist/` storybook exports exist.
+3. Confirm the repo uses `pui-cli storybook` (not raw `start-storybook` scripts).
+4. Consumer **`babel.config.ts`** should re-export pui-cli only — migrate from `babel.config.cjs` if present. **Do not** add `@babel/plugin-transform-private-methods` locally (included in pui-cli 9).
+
+## Migration steps
+
+### Step 0 — Babel config (if not done in `migrate-to-pui-cli-9`)
+
+Replace `babel.config.cjs` with `babel.config.ts`:
+
+```typescript
+import { babelConfig } from '@elliemae/pui-cli';
+
+export default babelConfig;
+```
+
+Delete `babel.config.cjs`. Do **not** add private-method Babel plugins locally.
+
+### Step 1 — Replace `.storybook/main.js`
+
+Delete `main.js`. Create `.storybook/main.mjs`:
+
+```javascript
+import { getStorybookConfig } from '@elliemae/pui-app-sdk/storybook/main';
+
+export default getStorybookConfig();
+```
+
+**Do not** use `getConfig`, `require('…/storybook/cjs/main')`, or import storybook from app-sdk before dist is built.
+
+Optional Vite builder (experimental): `export default getStorybookConfig(true);`
+
+### Step 2 — Remove middleware
+
+Delete `.storybook/middleware.js` if present.
+
+pui-cli registers mock API routes during `storybook dev`. The deprecated `@elliemae/pui-app-sdk/storybook/middleware` export exists only for repos not yet on pui-cli 9 Storybook — **do not** add it back in new ESM configs.
+
+### Step 3 — Convert preview, manager, theme (if customized)
+
+If the repo only uses shared pui-app-sdk defaults, you may have no preview file — skip.
+
+**Minimal preview** (no custom theme):
+
+```javascript
+// .storybook/preview.mjs
+export {
+  decorators,
+  parameters,
+  loaders,
+} from '@elliemae/pui-app-sdk/storybook/preview';
+```
+
+**Preview with local theme** (see `pui-react-boilerplate`):
+
+```javascript
+// .storybook/preview.mjs
+import {
+  getParameters,
+  loaders,
+  decorators,
+} from '@elliemae/pui-app-sdk/storybook/preview';
+import { theme } from './theme.mjs';
+
+const parameters = getParameters(theme);
+
+export { decorators, parameters, loaders };
+```
+
+**Manager / theme** — convert `manager.js` → `manager.mjs`, `theme.js` → `theme.mjs` when customized:
+
+```javascript
+// .storybook/manager.mjs
+import { initSBManager } from '@elliemae/pui-app-sdk/storybook/manager';
+import { theme } from './theme.mjs';
+
+initSBManager(theme);
+```
+
+```javascript
+// .storybook/theme.mjs
+export const theme = {
+  brandTitle: 'My App',
+  brandUrl: 'https://example.com',
+};
+```
+
+Keep `.storybook/preview-head.html` unchanged.
+
+Delete obsolete `.js` duplicates after creating `.mjs` files (`preview.js`, `manager.js`, `theme.js`, `middleware.js`).
+
+### Step 4 — MDX docs (Storybook 10 / MDX3)
+
+- Docs-only pages: rename **`intro.stories.mdx`** → **`intro.mdx`** (avoid `.stories.mdx` unless the file exports CSF stories).
+- Import Meta from **`@storybook/addon-docs/blocks`**:
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Introduction" />
+```
+
+### Step 5 — Monorepo lib packages (no `app/` directory)
+
+pui-app-sdk omits `../app/**` story globs when no `app/` folder exists. If globs still fail, filter explicitly in `main.mjs`:
+
+```javascript
+import { getStorybookConfig } from '@elliemae/pui-app-sdk/storybook/main';
+
+const config = getStorybookConfig();
+config.stories = config.stories.filter((s) => !s.includes('/app/'));
+
+export default config;
+```
+
+Pilot: `pui-mono-repo-boilerplate/libs/foo`.
+
+### Step 6 — Stories and types
+
+- Prefer CSF3 and `@storybook/react-webpack5` types where TypeScript fails.
+- Remove Storybook 6 webpack alias workarounds (MDX pinning, react-select hacks) unless a story still breaks after upgrade.
+- Consumers do **not** install `@storybook/addon-*` separately — addons resolve from pui-cli via NODE_PATH.
+
+### Step 7 — ESLint
+
+Ensure `.storybook/**` is linted. After pui-cli 9 ESLint flat config migration, run `pnpm exec pui-cli lint` on story files.
+
+## Verify
+
+```bash
+pnpm exec pui-cli storybook              # dev, default port 11000
+pnpm exec pui-cli storybook -b           # static build to demo/
+pnpm exec pui-cli storybook -b --docs    # docs build
+pnpm exec pui-cli lint
+```
+
+Checklist:
+
+- [ ] `babel.config.ts` re-exports pui-cli; no `babel.config.cjs`
+- [ ] No `require('@elliemae/pui-app-sdk/storybook/cjs/…')` anywhere
+- [ ] `.storybook/main.mjs` exists; `main.js` removed
+- [ ] `.storybook/middleware.js` removed (if it existed)
+- [ ] app-sdk dist built when using local link
+- [ ] Story dev server starts; mock API routes work without middleware file
+- [ ] Static build succeeds
+
+## Troubleshooting
+
+| Symptom                                                   | Fix                                                                                  |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `Cannot find module '…/storybook/cjs/main'`               | Migrate to `@elliemae/pui-app-sdk/storybook/main` in `main.mjs`                      |
+| `Cannot find module '…/dist/esm/utils/storybook/main.js'` | Run `pnpm run build` in app-sdk; or install published app-sdk alpha                  |
+| `getConfig is not a function`                             | Use named import **`getStorybookConfig`**, not `getConfig`                           |
+| `Can't resolve './app'` in lib-only package               | Use conditional globs in app-sdk or filter `config.stories` in `main.mjs`            |
+| `Class private methods are not enabled`                   | Upgrade pui-cli 9; remove duplicate Babel plugins from consumer Babel config         |
+| Babel cannot load `babel.config.ts`                       | Confirm Node 24; migrate from `babel.config.cjs` per `migrate-to-pui-cli-9` Phase 2b |
+| `Unable to index …stories.mdx`                            | Rename docs-only file to `.mdx`; fix `<Meta>` import                                 |
+| `Failed to load native binding` / SWC errors              | Reinstall deps; pui-cli uses Babel compiler addon, not SWC                           |
+| “Using default Webpack5 setup” (no Babel)                 | Refresh pnpm install after bumping pui-cli / pui-app-sdk                             |
+| API mocks missing                                         | Delete middleware file; use `pui-cli storybook` (not legacy CLI)                     |
+| Stale app-sdk in monorepo                                 | Rebuild linked app-sdk; `pnpm install` in consumer                                   |
+
+## Reference repos
+
+- `pui-react-boilerplate` — app with `app/` stories; `.storybook/*.mjs` + package imports
+- `pui-mono-repo-boilerplate/libs/foo` — lib-only package
+- `pui-app-sdk/.storybook/` — dogfood **`.storybook/*.ts`** with relative `../lib/utils/storybook/*` imports
+
+Full guide: [pui-cli 9 migration — Storybook 10](https://docs.pui.mortgagetech.q1.ice.com/cli/pui-cli-9-migration) (`docs/pui-cli-9-migration.md` in pui-cli).
+
+## Install this skill
+
+From a consumer repo (after `@elliemae/pui-cli` is installed):
+
+```bash
+pnpm exec pui-cli skills list
+pnpm exec pui-cli skills install migrate-storybook-out-of-cjs --target all
+```
+
+Skills are copied to `.cursor/skills/`, `.claude/skills/`, and `.github/skills/`.
+
+## What NOT to change
+
+- Production Webpack build config — Storybook migration is dev/docs tooling only
+- Business logic in stories unless types or CSF3 require it
+- Do not re-add `@storybook/*` addon packages to consumer `package.json` unless pui-cli docs explicitly require an exception
+- Do not add private-method Babel plugins to consumer Babel config when using pui-cli 9 shared config