@elliemae/pui-cli 9.0.0-alpha.4 → 9.0.0-alpha.5

package/README.md

@@ -8,6 +8,16 @@
 
 ## Migration Guide
 
+### pui-cli 9 (Node 24, pnpm 11, ESLint 9)
+
+Team upgrade guide: [pui-cli 9 migration guide](docs/pui-cli-9-migration.md).
+
+Install the bundled Cursor skill in a consumer repo:
+
+```bash
+pnpm exec pui-cli skills install migrate-to-pui-cli-9 --target all
+```
+
 ### ESLint 9 flat config (alpha)
 
 `pui-cli` now ships ESLint 9 with `typescript-eslint` v8 flat configs. Replace legacy `.eslintrc.cjs` with:

package/dist/cjs/cli.js

@@ -40,6 +40,7 @@ var import_vitest = require("./commands/vitest.js");
 var import_version = require("./commands/version.js");
 var import_tscheck = require("./commands/tscheck.js");
 var import_buildcdn = require("./commands/buildcdn.js");
+var import_skills = require("./commands/skills.js");
 const import_meta = {};
 const __dirname = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
 (0, import_dotenv.config)();
@@ -57,5 +58,6 @@ process.env.PATH += import_node_path.default.delimiter + import_node_path.defaul
   await (0, import_yargs.default)((0, import_helpers.hideBin)(process.argv)).command(import_version.versionCmd).help().argv;
   await (0, import_yargs.default)((0, import_helpers.hideBin)(process.argv)).command(import_tscheck.tscheckCmd).help().argv;
   await (0, import_yargs.default)((0, import_helpers.hideBin)(process.argv)).command(import_buildcdn.buildCDNCmd).help().argv;
+  await (0, import_yargs.default)((0, import_helpers.hideBin)(process.argv)).command(import_skills.skillsCmd).help().argv;
   await (0, import_update_notifier.notifyUpdates)();
 })();

package/dist/cjs/commands/skills.js

@@ -0,0 +1,207 @@
+"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 skills_exports = {};
+__export(skills_exports, {
+  skillsCmd: () => skillsCmd
+});
+module.exports = __toCommonJS(skills_exports);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_url = require("node:url");
+var import_node_module = require("node:module");
+var import_promises = require("node:fs/promises");
+var import_node_fs = require("node:fs");
+var import_yargs = __toESM(require("yargs"), 1);
+var import_utils = require("./utils.js");
+const import_meta = {};
+const SKILL_TARGETS = ["cursor", "claude", "copilot", "all"];
+const TARGET_RELATIVE_DIRS = {
+  cursor: [".cursor", "skills"],
+  claude: [".claude", "skills"],
+  copilot: [".github", "skills"]
+};
+const __dirname = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+const getPackageRoot = () => {
+  const require2 = (0, import_node_module.createRequire)(import_meta.url);
+  try {
+    return import_node_path.default.dirname(require2.resolve("@elliemae/pui-cli/package.json"));
+  } catch {
+    return import_node_path.default.resolve(__dirname, "..", "..");
+  }
+};
+const getBundledSkillsDir = () => import_node_path.default.join(getPackageRoot(), "lib", "skills");
+const getTargetSkillsDir = (target) => import_node_path.default.join(process.cwd(), ...TARGET_RELATIVE_DIRS[target]);
+const resolveTargets = (target) => {
+  const selected = target ? Array.isArray(target) ? target : [target] : ["cursor"];
+  if (selected.includes("all")) {
+    return ["cursor", "claude", "copilot"];
+  }
+  return selected;
+};
+const pathExists = async (targetPath) => {
+  try {
+    await (0, import_promises.access)(targetPath, import_node_fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+const listSkillNames = async (skillsDir) => {
+  const entries = await (0, import_promises.readdir)(skillsDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+};
+const copySkillDir = async (src, dest) => {
+  await (0, import_promises.mkdir)(dest, { recursive: true });
+  const entries = await (0, import_promises.readdir)(src, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (entry) => {
+      const srcPath = import_node_path.default.join(src, entry.name);
+      const destPath = import_node_path.default.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        return copySkillDir(srcPath, destPath);
+      }
+      return (0, import_promises.copyFile)(srcPath, destPath);
+    })
+  );
+};
+const installSkillToTarget = async (skillName, target, force) => {
+  const bundledDir = getBundledSkillsDir();
+  const src = import_node_path.default.join(bundledDir, skillName);
+  const dest = import_node_path.default.join(getTargetSkillsDir(target), skillName);
+  if (!await pathExists(src)) {
+    throw new Error(
+      `Skill "${skillName}" not found. Run "pui-cli skills list" for available skills.`
+    );
+  }
+  const srcStat = await (0, import_promises.stat)(src);
+  if (!srcStat.isDirectory()) {
+    throw new Error(`Skill "${skillName}" is not a valid skill directory.`);
+  }
+  if (await pathExists(dest) && !force) {
+    (0, import_utils.logWarning)(
+      `Skipped "${skillName}" for ${target} \u2014 already exists at ${dest}. Use --force to overwrite.`
+    );
+    return false;
+  }
+  await copySkillDir(src, dest);
+  (0, import_utils.logSuccess)(`Installed skill "${skillName}" to ${dest}`);
+  return true;
+};
+const installSkill = async (skillName, targets, force) => {
+  let installed = 0;
+  for (const target of targets) {
+    await (0, import_promises.mkdir)(getTargetSkillsDir(target), { recursive: true });
+    if (await installSkillToTarget(skillName, target, force)) {
+      installed += 1;
+    }
+  }
+  return installed > 0;
+};
+const runList = async () => {
+  const bundledDir = getBundledSkillsDir();
+  if (!await pathExists(bundledDir)) {
+    throw new Error(`Bundled skills directory not found: ${bundledDir}`);
+  }
+  const skills = await listSkillNames(bundledDir);
+  if (!skills.length) {
+    (0, import_utils.logInfo)("No bundled skills found.");
+    return;
+  }
+  (0, import_utils.logInfo)("Available skills:");
+  skills.forEach((name) => (0, import_utils.logInfo)(`  - ${name}`));
+};
+const logReloadHint = (targets) => {
+  const hints = [];
+  if (targets.includes("cursor")) {
+    hints.push("Cursor (.cursor/skills/)");
+  }
+  if (targets.includes("claude")) {
+    hints.push("Claude Code (.claude/skills/)");
+  }
+  if (targets.includes("copilot")) {
+    hints.push("GitHub Copilot (.github/skills/)");
+  }
+  if (hints.length) {
+    (0, import_utils.logInfo)(
+      `Restart or reload your agent to pick up skills in: ${hints.join(", ")}.`
+    );
+  }
+};
+const runInstall = async (name, force, target) => {
+  const bundledDir = getBundledSkillsDir();
+  if (!await pathExists(bundledDir)) {
+    throw new Error(`Bundled skills directory not found: ${bundledDir}`);
+  }
+  const targets = resolveTargets(target);
+  const skills = name ? [name] : await listSkillNames(bundledDir);
+  if (!skills.length) {
+    (0, import_utils.logInfo)("No bundled skills to install.");
+    return;
+  }
+  let installed = 0;
+  for (const skillName of skills) {
+    if (await installSkill(skillName, targets, force)) {
+      installed += 1;
+    }
+  }
+  if (installed) {
+    logReloadHint(targets);
+  }
+};
+const skillsCmd = {
+  command: "skills <action> [name]",
+  describe: "Install bundled agent skills for Cursor, Claude Code, and GitHub Copilot",
+  builder: (yargsRef) => yargsRef.positional("action", {
+    describe: "List bundled skills or install them into the current repo",
+    choices: ["list", "install"],
+    demandOption: true
+  }).positional("name", {
+    describe: "Skill folder name (install all when omitted)",
+    type: "string"
+  }).option("target", {
+    describe: "Install destination: cursor (.cursor/skills), claude (.claude/skills), copilot (.github/skills), or all",
+    choices: SKILL_TARGETS,
+    default: "cursor"
+  }).option("force", {
+    describe: "Overwrite an existing skill directory",
+    type: "boolean",
+    default: false
+  }).help(),
+  handler: async (argv) => {
+    try {
+      if (argv.action === "list") {
+        await runList();
+        return;
+      }
+      await runInstall(argv.name, Boolean(argv.force), argv.target);
+    } catch (err) {
+      (0, import_utils.logError)(err.message);
+      (0, import_yargs.default)().exit(-1, err);
+    }
+  }
+};

package/dist/cjs/skills/migrate-to-pui-cli-9/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: migrate-to-pui-cli-9
+description: >-
+  Migrate a PUI app or library to pui-cli 9 (Node 24, pnpm 11, ESLint 9 flat config).
+  Use when upgrading @elliemae/pui-cli, migrating from .eslintrc.cjs to eslint.config.mjs,
+  fixing ESLint 9 lint failures, or adopting the shared flat config from pui-cli.
+---
+
+# Migrate to pui-cli 9
+
+Upgrades a PUI repo from pui-cli 8 (ESLint 8 + `.eslintrc.cjs`) to pui-cli 9
+(ESLint 9 + `eslint.config.mjs` + Node 24 + pnpm 11).
+
+## Pre-flight: Toolchain
+
+| Requirement         | Version                           |
+| ------------------- | --------------------------------- |
+| Node.js             | **24** (see repo `.node-version`) |
+| pnpm                | **11**                            |
+| `@elliemae/pui-cli` | **9.x** (alpha/beta until GA)     |
+
+```bash
+fnm use 24   # or nvm/volta equivalent
+corepack enable
+pnpm install
+```
+
+## Migration steps (phased PRs recommended)
+
+### Phase 1 — Toolchain only
+
+1. Update `.node-version` to `24` if needed.
+2. Ensure CI Jenkins/docker images use Node 24.
+3. Upgrade pnpm to 11 (`packageManager` field in root `package.json`).
+4. Run `pnpm install`, `pnpm test`, `pnpm run build` — fix any Node/pnpm breakages only.
+
+### Phase 2 — Bump pui-cli
+
+```bash
+pnpm add -D @elliemae/pui-cli@9
+```
+
+Re-run install and smoke-test build/test without ESLint changes yet if the bump is large.
+
+### Phase 3 — ESLint 9 flat config
+
+**React apps and libraries:**
+
+```js
+// eslint.config.mjs
+import { eslintFlatConfig } from '@elliemae/pui-cli/eslint';
+
+export default eslintFlatConfig;
+```
+
+**Node / TS services (non-React):**
+
+```js
+// eslint.config.mjs
+import { eslintFlatBaseConfig } from '@elliemae/pui-cli/eslint';
+
+export default eslintFlatBaseConfig;
+```
+
+Then:
+
+1. Delete `.eslintrc.cjs` and `.eslintignore` (ignores are in the shared config).
+2. Run `pnpm exec pui-cli lint --fix`.
+3. Run `pnpm exec pui-cli lint` until **zero errors** (warnings may remain).
+
+**Strict mode** (only after default config is clean):
+
+```js
+import { eslintFlatConfigStrict } from '@elliemae/pui-cli/eslint';
+export default eslintFlatConfigStrict;
+```
+
+### Phase 4 — Repo-specific overrides (if needed)
+
+Add overrides **after** importing the shared config only when lint debt blocks the migration:
+
+```js
+import { eslintFlatConfig } from '@elliemae/pui-cli/eslint';
+
+export default [
+  ...eslintFlatConfig,
+  {
+    rules: {
+      // Temporary: legacy had ~100 no-explicit-any warnings via @typescript-eslint v5
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+];
+```
+
+Remove overrides in a follow-up debt PR. Do not copy Airbnb or legacy `.eslintrc` rules.
+
+### Phase 5 — Verify
+
+- [ ] `pnpm exec pui-cli lint` — 0 errors
+- [ ] `pnpm exec pui-cli tscheck --files`
+- [ ] `pnpm test`
+- [ ] `pnpm run build` (or `pui-cli build`)
+- [ ] Pre-commit / lint-staged passes
+- [ ] CI green on the target branch
+
+## Common lint fixes after upgrade
+
+| Symptom                              | Fix                                                                    |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| `import-x/no-unresolved`             | Use `import type` for type-only imports                                |
+| `@typescript-eslint/no-explicit-any` | Type the value or add targeted override (warn) during transition       |
+| `@typescript-eslint/no-unused-vars`  | Remove or prefix with `_`                                              |
+| Stale `eslint-disable` comments      | Remove disables for rules no longer in config                          |
+| Test/fixture files flagged           | Shared config includes `lib/**/tests/**` globs — ensure pui-cli 9.0.0+ |
+| `.d.ts` files                        | pui-cli turns off `no-explicit-any` for `**/*.d.ts`                    |
+
+Full rule comparison: [eslint-rules-migration.md](https://docs.pui.mortgagetech.q1.ice.com/cli/eslint-rules-migration) (also at `docs/eslint-rules-migration.md` in pui-cli).
+
+## Install this skill in Cursor
+
+From the consumer repo (after `@elliemae/pui-cli` is installed):
+
+```bash
+pnpm exec pui-cli skills install migrate-to-pui-cli-9 --target all
+```
+
+Skills are copied to `.cursor/skills/`, `.claude/skills/`, and `.github/skills/` for Cursor, Claude Code, and GitHub Copilot.
+
+## What NOT to change
+
+- Application business logic — migration is tooling/config only
+- Webpack/babel config unless pui-cli 9 release notes require it
+- Prettier / Stylelint / commitlint configs unless pui-cli 9 bumps those presets
+
+## Additional resources
+
+- [pui-cli 9 migration guide](https://docs.pui.mortgagetech.q1.ice.com/cli/pui-cli-9-migration)
+- [ESLint rules migration guide](https://docs.pui.mortgagetech.q1.ice.com/cli/eslint-rules-migration)
+- Reference one-liner: `pui-react-boilerplate/eslint.config.mjs`

package/dist/esm/cli.js

@@ -17,6 +17,7 @@ import { vitestCmd } from "./commands/vitest.js";
 import { versionCmd } from "./commands/version.js";
 import { tscheckCmd } from "./commands/tscheck.js";
 import { buildCDNCmd } from "./commands/buildcdn.js";
+import { skillsCmd } from "./commands/skills.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 envConfig();
 process.env.PATH += path.delimiter + path.join(__dirname, "..", "node_modules", ".bin");
@@ -33,5 +34,6 @@ process.env.PATH += path.delimiter + path.join(__dirname, "..", "node_modules",
   await yargs(hideBin(process.argv)).command(versionCmd).help().argv;
   await yargs(hideBin(process.argv)).command(tscheckCmd).help().argv;
   await yargs(hideBin(process.argv)).command(buildCDNCmd).help().argv;
+  await yargs(hideBin(process.argv)).command(skillsCmd).help().argv;
   await notifyUpdates();
 })();

package/dist/esm/commands/skills.js

@@ -0,0 +1,176 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { access, copyFile, mkdir, readdir, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import yargs from "yargs";
+import { logError, logInfo, logSuccess, logWarning } from "./utils.js";
+const SKILL_TARGETS = ["cursor", "claude", "copilot", "all"];
+const TARGET_RELATIVE_DIRS = {
+  cursor: [".cursor", "skills"],
+  claude: [".claude", "skills"],
+  copilot: [".github", "skills"]
+};
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const getPackageRoot = () => {
+  const require2 = createRequire(import.meta.url);
+  try {
+    return path.dirname(require2.resolve("@elliemae/pui-cli/package.json"));
+  } catch {
+    return path.resolve(__dirname, "..", "..");
+  }
+};
+const getBundledSkillsDir = () => path.join(getPackageRoot(), "lib", "skills");
+const getTargetSkillsDir = (target) => path.join(process.cwd(), ...TARGET_RELATIVE_DIRS[target]);
+const resolveTargets = (target) => {
+  const selected = target ? Array.isArray(target) ? target : [target] : ["cursor"];
+  if (selected.includes("all")) {
+    return ["cursor", "claude", "copilot"];
+  }
+  return selected;
+};
+const pathExists = async (targetPath) => {
+  try {
+    await access(targetPath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+const listSkillNames = async (skillsDir) => {
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+};
+const copySkillDir = async (src, dest) => {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (entry) => {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        return copySkillDir(srcPath, destPath);
+      }
+      return copyFile(srcPath, destPath);
+    })
+  );
+};
+const installSkillToTarget = async (skillName, target, force) => {
+  const bundledDir = getBundledSkillsDir();
+  const src = path.join(bundledDir, skillName);
+  const dest = path.join(getTargetSkillsDir(target), skillName);
+  if (!await pathExists(src)) {
+    throw new Error(
+      `Skill "${skillName}" not found. Run "pui-cli skills list" for available skills.`
+    );
+  }
+  const srcStat = await stat(src);
+  if (!srcStat.isDirectory()) {
+    throw new Error(`Skill "${skillName}" is not a valid skill directory.`);
+  }
+  if (await pathExists(dest) && !force) {
+    logWarning(
+      `Skipped "${skillName}" for ${target} \u2014 already exists at ${dest}. Use --force to overwrite.`
+    );
+    return false;
+  }
+  await copySkillDir(src, dest);
+  logSuccess(`Installed skill "${skillName}" to ${dest}`);
+  return true;
+};
+const installSkill = async (skillName, targets, force) => {
+  let installed = 0;
+  for (const target of targets) {
+    await mkdir(getTargetSkillsDir(target), { recursive: true });
+    if (await installSkillToTarget(skillName, target, force)) {
+      installed += 1;
+    }
+  }
+  return installed > 0;
+};
+const runList = async () => {
+  const bundledDir = getBundledSkillsDir();
+  if (!await pathExists(bundledDir)) {
+    throw new Error(`Bundled skills directory not found: ${bundledDir}`);
+  }
+  const skills = await listSkillNames(bundledDir);
+  if (!skills.length) {
+    logInfo("No bundled skills found.");
+    return;
+  }
+  logInfo("Available skills:");
+  skills.forEach((name) => logInfo(`  - ${name}`));
+};
+const logReloadHint = (targets) => {
+  const hints = [];
+  if (targets.includes("cursor")) {
+    hints.push("Cursor (.cursor/skills/)");
+  }
+  if (targets.includes("claude")) {
+    hints.push("Claude Code (.claude/skills/)");
+  }
+  if (targets.includes("copilot")) {
+    hints.push("GitHub Copilot (.github/skills/)");
+  }
+  if (hints.length) {
+    logInfo(
+      `Restart or reload your agent to pick up skills in: ${hints.join(", ")}.`
+    );
+  }
+};
+const runInstall = async (name, force, target) => {
+  const bundledDir = getBundledSkillsDir();
+  if (!await pathExists(bundledDir)) {
+    throw new Error(`Bundled skills directory not found: ${bundledDir}`);
+  }
+  const targets = resolveTargets(target);
+  const skills = name ? [name] : await listSkillNames(bundledDir);
+  if (!skills.length) {
+    logInfo("No bundled skills to install.");
+    return;
+  }
+  let installed = 0;
+  for (const skillName of skills) {
+    if (await installSkill(skillName, targets, force)) {
+      installed += 1;
+    }
+  }
+  if (installed) {
+    logReloadHint(targets);
+  }
+};
+const skillsCmd = {
+  command: "skills <action> [name]",
+  describe: "Install bundled agent skills for Cursor, Claude Code, and GitHub Copilot",
+  builder: (yargsRef) => yargsRef.positional("action", {
+    describe: "List bundled skills or install them into the current repo",
+    choices: ["list", "install"],
+    demandOption: true
+  }).positional("name", {
+    describe: "Skill folder name (install all when omitted)",
+    type: "string"
+  }).option("target", {
+    describe: "Install destination: cursor (.cursor/skills), claude (.claude/skills), copilot (.github/skills), or all",
+    choices: SKILL_TARGETS,
+    default: "cursor"
+  }).option("force", {
+    describe: "Overwrite an existing skill directory",
+    type: "boolean",
+    default: false
+  }).help(),
+  handler: async (argv) => {
+    try {
+      if (argv.action === "list") {
+        await runList();
+        return;
+      }
+      await runInstall(argv.name, Boolean(argv.force), argv.target);
+    } catch (err) {
+      logError(err.message);
+      yargs().exit(-1, err);
+    }
+  }
+};
+export {
+  skillsCmd
+};