@maz-ui/upgrade 5.0.0-beta.0

package/README.md

@@ -0,0 +1,346 @@
+# @maz-ui/upgrade
+
+Automated source rewrites for migrating a project from **Maz-UI v4** to **v5**.
+
+Run it once at the start of your migration to clear the mechanical changes
+from your todo list, then walk through the rest of the
+[migration guide](https://maz-ui.com/guide/migration-v5) for the items that
+need a human eye (theme `foundation.radius` reshape, `MazIcon` API,
+`MazBadge` numeric sizes, `MazChart` `update-mode`).
+
+The companion [`@maz-ui/mcp`](https://maz-ui.com/guide/mcp) server lets your
+AI assistant read the migration guide and apply the manual steps with full
+context.
+
+## Table of contents
+
+- [@maz-ui/upgrade](#maz-uiupgrade)
+  - [Table of contents](#table-of-contents)
+  - [Quick start](#quick-start)
+  - [Usage](#usage)
+  - [Options](#options)
+  - [What it scans](#what-it-scans)
+  - [How it ignores files](#how-it-ignores-files)
+  - [Transform groups](#transform-groups)
+    - [`imports`](#imports)
+    - [`props`](#props)
+    - [`css`](#css)
+    - [`config`](#config)
+    - [`deps`](#deps)
+  - [Dependency install](#dependency-install)
+  - [Output](#output)
+  - [Exit codes](#exit-codes)
+  - [What it does NOT do](#what-it-does-not-do)
+  - [Programmatic API](#programmatic-api)
+  - [License](#license)
+
+## Quick start
+
+```bash
+# 1. Preview the rewrites without touching anything
+npx @maz-ui/upgrade ./ --dry-run
+
+# 2. Apply when the diff looks good
+npx @maz-ui/upgrade ./
+
+# 3. Run your typecheck / tests, fix the few remaining manual items
+#    listed at the end of the migration guide
+```
+
+Working in a Vue/Nuxt monorepo? Point at the app:
+
+```bash
+npx @maz-ui/upgrade ./apps/web --dry-run
+```
+
+## Usage
+
+```text
+npx @maz-ui/upgrade [options] <path...>
+```
+
+- **`<path...>`** — one or more directories to walk. Each path is resolved
+  against the current working directory. At least one path is required;
+  pass `./` to scan the whole project.
+- The tool walks every supported file under those paths, applies the
+  enabled transform groups, and writes the result back in place (or just
+  prints what would change with `--dry-run`).
+
+## Options
+
+| Flag              | Description                                                                                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-n`, `--dry-run` | Print every file that would change without writing it back. Use this first.                                                                           |
+| `--only=<groups>` | Comma-separated list of transform groups to run. See [Transform groups](#transform-groups). Default: `imports,props,css,config,deps` (all of them).   |
+| `--no-gitignore`  | Do not respect the project's `.gitignore`. The built-in safe list of build / dependency directories still applies.                                    |
+| `--no-install`    | Do not run the package manager after rewriting `package.json` files. By default the CLI runs `<pm> install` once at least one `package.json` changed. |
+| `-h`, `--help`    | Print the help screen and exit.                                                                                                                       |
+| `-v`, `--version` | Print the upgrade tool version and exit.                                                                                                              |
+
+Examples:
+
+```bash
+# Only rewrite import paths and component props
+npx @maz-ui/upgrade ./src --only=imports,props
+
+# Same, but also include files your .gitignore would otherwise skip
+npx @maz-ui/upgrade ./src --only=css --no-gitignore
+
+# Multiple roots in one run
+npx @maz-ui/upgrade ./apps/web ./packages/ui-kit --dry-run
+```
+
+## What it scans
+
+The CLI walks every file matching one of these extensions inside the
+provided paths:
+
+- **Vue:** `.vue`
+- **CSS:** `.css`
+- **TypeScript:** `.ts`, `.tsx`, `.cts`, `.mts`
+- **JavaScript:** `.js`, `.jsx`, `.cjs`, `.mjs`
+- **Manifest:** every `package.json` (root + nested in monorepo workspaces)
+
+That covers component templates, scoped/global styles, plus `nuxt.config.ts`,
+`main.ts` / `main.js`, custom theme preset files, plugin registration files,
+and anything else where a v4 pattern can appear.
+
+## How it ignores files
+
+Two layers, applied in order:
+
+1. **Built-in safe list** (always on): `node_modules`, `dist`, `build`,
+   `.nuxt`, `.output`, `.next`, `.svelte-kit`, `.turbo`, `.cache`,
+   `coverage`, `.vercel`, `.netlify`.
+2. **Your `.gitignore`** — read at the project root and any nested
+   `.gitignore` files, the same way `prettier`, `eslint` or
+   `@tailwindcss/upgrade` work. Pass `--no-gitignore` to skip this layer
+   (the safe list above still applies).
+
+If your build output, generated types, or vendored copies of maz-ui live
+outside both lists, add them to a local `.gitignore` (or to a sibling
+`.git/info/exclude`) so they're skipped on the next run.
+
+## Transform groups
+
+By default all five groups run. Use `--only=<a,b,...>` to scope the run.
+Each group is independent and idempotent: re-running the tool on
+already-migrated code is a no-op.
+
+### `imports`
+
+CSS subpath rename, applied to imports in `.vue` and JS/TS files:
+
+| v4                           | v5                          |
+| ---------------------------- | --------------------------- |
+| `import 'maz-ui/styles'`     | `import 'maz-ui/style.css'` |
+| `import 'maz-ui/aos-styles'` | `import 'maz-ui/aos.css'`   |
+
+### `props`
+
+Component prop / slot / class renames, applied to `.vue` files only.
+Patterns specific enough to rewrite globally (e.g. `left-icon` /
+`right-icon`) are handled file-wide. Patterns that would otherwise be
+ambiguous (`variant=`, `color="background"`) are rewritten **only inside
+`<Maz...>` opening tags**, never on your own components.
+
+| v4                                                                | v5                                                          |
+| ----------------------------------------------------------------- | ----------------------------------------------------------- |
+| `left-icon="x"` / `right-icon="x"`                                | `start-icon="x"` / `end-icon="x"`                           |
+| `:left-icon="x"` / `:right-icon="x"`                              | `:start-icon="x"` / `:end-icon="x"`                         |
+| `<template #left-icon>` / `<template #right-icon>`                | `<template #start-icon>` / `<template #end-icon>`           |
+| `<template #icon-left>` / `<template #icon-right>` (MazContainer) | `<template #icon-start>` / `<template #icon-end>`           |
+| `footer-align="left"` / `footer-align="right"`                    | `footer-align="start"` / `footer-align="end"`               |
+| `<MazDrawer variant="left">` / `<MazDrawer variant="right">`      | `<MazDrawer variant="start">` / `<MazDrawer variant="end">` |
+| `<Maz... color="background">`                                     | `<Maz... color="surface">`                                  |
+| `active-color="background"`                                       | `active-color="surface"`                                    |
+| `rounded-size="base"`                                             | `rounded-size="md"`                                         |
+| `.--has-left-icon` / `.--has-right-icon` (CSS selectors)          | `.--has-start-icon` / `.--has-end-icon`                     |
+
+### `css`
+
+CSS variable renames + `hsl(var(...))` collapse, applied to `.vue` style
+blocks, `.css` files, and any inline strings in `.ts`/`.js`:
+
+| v4                                                                                         | v5                                                                                |
+| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `var(--maz-background)` / `var(--maz-background-700)` / `var(--maz-background-foreground)` | `var(--maz-surface)` / `var(--maz-surface-700)` / `var(--maz-surface-foreground)` |
+| `var(--maz-border)` / `var(--maz-border-700)`                                              | `var(--maz-divider)` / `var(--maz-divider-700)`                                   |
+| `hsl(var(--maz-primary))`                                                                  | `var(--maz-primary)`                                                              |
+| `hsl(var(--maz-primary) / 0.5)`                                                            | `color-mix(in srgb, var(--maz-primary) 0.5, transparent)`                         |
+
+Foundation tokens that happen to start with the same prefix (e.g.
+`--maz-border-width`, `--maz-border-radius`) are explicitly **not**
+renamed.
+
+### `config`
+
+Plugin / Nuxt module / preset config keys, applied to `.vue` and JS/TS
+files:
+
+| v4                                                                      | v5                                    |
+| ----------------------------------------------------------------------- | ------------------------------------- |
+| Nuxt `mazUi.css.injectMainCss`                                          | `mazUi.css.injectCss`                 |
+| Theme `strategy: 'hybrid'`                                              | `strategy: 'runtime'`                 |
+| `MazUiTheme` plugin options `injectCriticalCSS: …` / `injectFullCSS: …` | line removed (silently ignored in v5) |
+| Nuxt theme `injectAllCSSOnServer: …`                                    | line removed (silently ignored in v5) |
+| Custom preset `colors.{light,dark}.background`                          | `colors.{light,dark}.surface`         |
+| Custom preset `colors.{light,dark}.border`                              | `colors.{light,dark}.divider`         |
+
+The preset color rename is scoped to `light: { … }` / `dark: { … }`
+blocks, so unrelated CSS-in-JS / JSX style props elsewhere are left
+alone.
+
+### `deps`
+
+Dependency version bumps in every `package.json` the walk picks up
+(root + nested workspaces). Bumps `maz-ui` and every `@maz-ui/*`
+entry across `dependencies`, `devDependencies` and `peerDependencies`
+to `^5.0.0`. Existing JSON indentation and trailing newline are
+preserved; non-maz-ui dependencies are never touched.
+
+| What                                                                         | Behaviour             |
+| ---------------------------------------------------------------------------- | --------------------- |
+| `maz-ui`, `@maz-ui/*` semver ranges (`^4.x`, `~4.x`, `4.x`, `4.0.0`, …)      | Rewritten to `^5.0.0` |
+| `workspace:*`, `link:…`, `file:…`, `portal:…`, `npm:…`, `http(s):…`, `git+…` | Left untouched        |
+| Dist tags (`latest`, `next`, `beta`, `alpha`, `canary`)                      | Left untouched        |
+| Anything else (`vue`, `chart.js`, your own packages, …)                      | Left untouched        |
+
+`vue-chartjs` is **not** removed automatically, even though `MazChart`
+no longer depends on it — keep it if you use it directly elsewhere,
+remove it manually otherwise.
+
+## Dependency install
+
+Once the rewrite is done, if at least one `package.json` changed and
+the `deps` group ran, the CLI:
+
+1. Detects your package manager from the lockfile in `cwd`:
+   `bun.lockb`/`bun.lock` → **bun**, `pnpm-lock.yaml` → **pnpm**,
+   `yarn.lock` → **yarn**, `package-lock.json` → **npm**, otherwise
+   defaults to **npm**.
+2. Runs `<pm> install` with inherited stdio so you see the install
+   progress live. The CLI exits with the install's exit code if it
+   fails.
+
+Pass `--no-install` to skip step 2 — the CLI then prints the command
+you should run manually:
+
+```text
+package.json files updated. Run `pnpm install` to apply.
+```
+
+`--dry-run` always skips the install regardless of `--no-install`.
+
+## Output
+
+For each file that the tool changes, you get one line on stdout:
+
+```text
+updated: src/components/Header.vue
+updated: app.vue
+updated: nuxt.config.ts
+```
+
+In dry-run mode the prefix becomes `[dry-run] would update: ...`.
+
+At the end of the run you get a summary:
+
+```text
+Scanned 142 files, updated 27.
+Groups applied: imports, props, css, config, deps
+
+Detected package manager: pnpm. Running `pnpm install`…
+
+[ … pnpm install output … ]
+
+Next: see https://maz-ui.com/guide/migration-v5 for the manual steps
+(foundation.radius → scales.rounded.md, MazIcon API, MazBadge sizes, MazChart update-mode).
+```
+
+## Exit codes
+
+- `0` — completed successfully (zero or more files updated; install
+  step, if any, succeeded).
+- `1` — argument error (unknown option or unknown group), no path
+  provided, or unhandled error during the walk.
+- Any other code propagated from the package manager when the install
+  step fails (CLI exits with that exact status).
+
+## What it does NOT do
+
+Some changes need a human (or your AI assistant via the
+[`@maz-ui/mcp`](https://maz-ui.com/guide/mcp) server) — see the
+[migration guide](https://maz-ui.com/guide/migration-v5) for the full
+context:
+
+- **`MazIcon` API simplification** — `name`/`path`/`src` props collapsing
+  into a single `icon` prop needs the original asset path to rewrite
+  correctly.
+- **`MazBadge` numeric `size`** — picking the right keyword (`mini`/`xs`/…)
+  is a judgment call.
+- **Theme preset radius reshape** — `foundation.radius` →
+  `scales.rounded.md` needs to move the value to a new sibling block,
+  which is too structural for a safe regex. The simpler color key renames
+  (`background` → `surface`, `border` → `divider`) are handled by the
+  `config` group, and the `package.json` version bump by the `deps`
+  group.
+- **`MazChart` `update-mode` default** — switched from `'default'` to
+  `'none'` in v5; deciding whether to restore the v4 animation is up to
+  you.
+- **Tailwind v3 → v4 migration** — if you ship your own Tailwind utilities
+  alongside maz-ui, run `npx @tailwindcss/upgrade` first; it covers 95% of
+  the Tailwind side. See the
+  [Tailwind integration page](https://maz-ui.com/guide/tailwind).
+
+## Programmatic API
+
+Each transform is exported as a pure `(string) => string` function, so
+you can call them from your own scripts or compose a custom orchestrator:
+
+```ts
+import type { TransformGroup, TransformOptions } from '@maz-ui/upgrade'
+import {
+  ALL_GROUPS,
+  transformConfig,
+  transformCssVars,
+  transformDeps,
+  transformFile,
+  transformHslVar,
+  transformImports,
+  transformPresetColors,
+  transformProps,
+} from '@maz-ui/upgrade'
+
+transformImports(`import 'maz-ui/styles'`)
+// → `import 'maz-ui/style.css'`
+
+transformProps(`<MazBtn left-icon="x" />`)
+// → `<MazBtn start-icon="x" />`
+
+transformHslVar(`color: hsl(var(--maz-primary) / 0.5)`)
+// → `color: color-mix(in srgb, var(--maz-primary) 0.5, transparent)`
+
+transformCssVars(`background: var(--maz-background-700);`)
+// → `background: var(--maz-surface-700);`
+
+transformPresetColors(`light: { background: '0 0% 100%', border: '220 13% 91%' }`)
+// → `light: { surface: '0 0% 100%', divider: '220 13% 91%' }`
+
+transformConfig(`{ css: { injectMainCss: true } }`)
+// → `{ css: { injectCss: true } }`
+
+transformDeps(`{ "dependencies": { "maz-ui": "^4.9.3" } }`)
+// → `{ "dependencies": { "maz-ui": "^5.0.0" } }`
+
+// Compose at the file level (extension-aware orchestration):
+transformFile('nuxt.config.ts', source, { groups: ['imports', 'config'] })
+// Pass no options to apply ALL_GROUPS.
+transformFile('app.vue', source)
+```
+
+`ALL_GROUPS` is exported as `readonly TransformGroup[]` (`['imports', 'props', 'css', 'config', 'deps']`) so you can derive your own subsets.
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+

package/dist/cli.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import process from 'node:process';
+import { logger } from '@maz-ui/node';
+import { globby } from 'globby';
+import { transformFile, ALL_GROUPS } from './index.mjs';
+
+const DEFAULT_IGNORES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.nuxt/**",
+  "**/.output/**",
+  "**/.next/**",
+  "**/.svelte-kit/**",
+  "**/.turbo/**",
+  "**/.cache/**",
+  "**/coverage/**",
+  "**/.vercel/**",
+  "**/.netlify/**"
+];
+function parseArgs(argv) {
+  const roots = [];
+  let dryRun = false;
+  let gitignore = true;
+  let install = true;
+  let groups = ALL_GROUPS;
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--dry-run" || arg === "-n") {
+      dryRun = true;
+    } else if (arg === "--no-gitignore") {
+      gitignore = false;
+    } else if (arg === "--no-install") {
+      install = false;
+    } else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    } else if (arg === "--version" || arg === "-v") {
+      printVersion();
+      process.exit(0);
+    } else if (arg.startsWith("--only=")) {
+      groups = parseGroups(arg.slice("--only=".length));
+    } else if (arg === "--only") {
+      groups = parseGroups(argv[++i] ?? "");
+    } else if (arg.startsWith("-")) {
+      logger.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    } else {
+      roots.push(arg);
+    }
+  }
+  if (roots.length === 0) {
+    logger.error("At least one path is required.");
+    printHelp();
+    process.exit(1);
+  }
+  return { dryRun, groups, roots, gitignore, install };
+}
+function parseGroups(value) {
+  const parts = value.split(",").map((p) => p.trim()).filter(Boolean);
+  for (const p of parts) {
+    if (!ALL_GROUPS.includes(p)) {
+      logger.error(`Unknown group: ${p}. Valid: ${ALL_GROUPS.join(", ")}`);
+      process.exit(1);
+    }
+  }
+  return parts;
+}
+function printHelp() {
+  logger.log(`@maz-ui/upgrade \u2014 automated rewrites for migrating a project from Maz-UI v4 to v5.
+
+Usage:
+  npx @maz-ui/upgrade [options] <path...>
+
+Options:
+  -n, --dry-run        Print what would change without writing any file.
+  --only=<groups>      Comma-separated list of transform groups to apply.
+                       Default: ${ALL_GROUPS.join(",")}.
+  --no-gitignore       Do not respect .gitignore (scan everything except the
+                       built-in safe list of build / dependency directories).
+  --no-install         Do not run the package manager after rewriting
+                       package.json files. Default: install runs after a
+                       successful rewrite.
+  -h, --help           Show this help.
+  -v, --version        Print the upgrade tool version.
+
+Transform groups:
+  imports   maz-ui/styles \u2192 maz-ui/style.css, maz-ui/aos-styles \u2192 maz-ui/aos.css
+  props     left-icon/right-icon \u2192 start-icon/end-icon (props, slots,
+            #icon-left/#icon-right, --has-*-icon classes), footer-align,
+            variant, color="background", active-color, rounded-size="base"
+  css       --maz-background \u2192 --maz-surface, --maz-border \u2192 --maz-divider,
+            hsl(var(--maz-X)) collapse (incl. alpha \u2192 color-mix)
+  config    Nuxt injectMainCss \u2192 injectCss, theme strategy 'hybrid' \u2192 'runtime',
+            removes dropped theme options (injectCriticalCSS, injectFullCSS,
+            injectAllCSSOnServer), preset colors.{light,dark}.background \u2192 surface
+            and .border \u2192 divider
+  deps      Bumps every maz-ui / @maz-ui/* entry in package.json
+            (dependencies, devDependencies, peerDependencies) to ^5.0.0.
+            Workspace, link, file and url specs are left untouched.
+
+Scans the given paths for .vue, .css, .ts/.tsx/.cts/.mts,
+.js/.jsx/.cjs/.mjs and package.json files. By default it respects
+your .gitignore (plus a built-in safe list of node_modules, dist,
+build, .nuxt, .output, .next, .svelte-kit, .turbo, .cache, coverage,
+.vercel, .netlify). Pass --no-gitignore to skip the .gitignore step.
+
+After rewriting, if at least one package.json changed and the deps
+group ran, the CLI detects your package manager (pnpm / yarn / bun /
+npm \u2014 based on the lockfile in cwd) and runs <pm> install. Pass
+--no-install to skip that step.
+
+What it does NOT do (handle by hand or with the @maz-ui/mcp server):
+  - Reshape foundation.radius into scales.rounded.md (move + key restructure).
+  - Map MazIcon name=/path=/src= props to the new icon= API.
+  - Map numeric MazBadge size to the keyword scale.
+  - MazChart updateMode default change (judgment call).
+
+Full migration guide: https://maz-ui.com/guide/migration-v5
+`);
+}
+function printVersion() {
+  const pkg = JSON.parse(
+    readFileSync(resolve(dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf8")
+  );
+  logger.log(pkg.version);
+}
+function detectPackageManager(cwd) {
+  if (existsSync(resolve(cwd, "bun.lockb")) || existsSync(resolve(cwd, "bun.lock")))
+    return "bun";
+  if (existsSync(resolve(cwd, "pnpm-lock.yaml")))
+    return "pnpm";
+  if (existsSync(resolve(cwd, "yarn.lock")))
+    return "yarn";
+  if (existsSync(resolve(cwd, "package-lock.json")))
+    return "npm";
+  return "npm";
+}
+function runInstall(pm, cwd) {
+  const result = spawnSync(pm, ["install"], {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  return result.status ?? 1;
+}
+function maybeInstallDeps(opts, depsChanged, cwd) {
+  if (!depsChanged || opts.dryRun)
+    return;
+  const pm = detectPackageManager(cwd);
+  if (!opts.install || !opts.groups.includes("deps")) {
+    logger.log(`
+package.json files updated. Run \`${pm} install\` to apply.`);
+    return;
+  }
+  logger.log(`
+Detected package manager: ${pm}. Running \`${pm} install\`\u2026
+`);
+  const code = runInstall(pm, cwd);
+  if (code !== 0) {
+    logger.error(`
+\`${pm} install\` exited with code ${code}.`);
+    process.exit(code);
+  }
+}
+async function run() {
+  const opts = parseArgs(process.argv);
+  const cwd = process.cwd();
+  let scanned = 0;
+  let changed = 0;
+  let depsChanged = false;
+  for (const root of opts.roots) {
+    const absoluteRoot = resolve(cwd, root);
+    const files = await globby(
+      [
+        "**/*.vue",
+        "**/*.css",
+        "**/*.{js,mjs,cjs,jsx}",
+        "**/*.{ts,mts,cts,tsx}",
+        "**/package.json"
+      ],
+      {
+        cwd: absoluteRoot,
+        absolute: true,
+        gitignore: opts.gitignore,
+        ignore: DEFAULT_IGNORES
+      }
+    );
+    for (const file of files) {
+      scanned += 1;
+      const before = readFileSync(file, "utf8");
+      const after = transformFile(file, before, { groups: opts.groups });
+      if (after === before)
+        continue;
+      changed += 1;
+      if (file.endsWith("package.json"))
+        depsChanged = true;
+      const shown = file.replace(`${cwd}/`, "");
+      logger.log(`${opts.dryRun ? "[dry-run] would update" : "updated"}: ${shown}`);
+      if (!opts.dryRun) {
+        writeFileSync(file, after, "utf8");
+      }
+    }
+  }
+  const prefix = opts.dryRun ? "would update" : "updated";
+  logger.log(`
+Scanned ${scanned} files, ${prefix} ${changed}.`);
+  logger.log(`Groups applied: ${opts.groups.join(", ")}`);
+  maybeInstallDeps(opts, depsChanged, cwd);
+  logger.log(`
+Next: see https://maz-ui.com/guide/migration-v5 for the manual steps`);
+  logger.log(`(foundation.radius \u2192 scales.rounded.md, MazIcon API, MazBadge sizes, MazChart update-mode).`);
+}
+run().catch((err) => {
+  logger.error(err);
+  process.exit(1);
+});

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+declare function transformImports(content: string): string;
+declare function transformProps(content: string): string;
+declare function transformCssVars(content: string): string;
+declare function transformHslVar(content: string): string;
+declare function transformConfig(content: string): string;
+declare function transformPresetColors(content: string): string;
+declare function transformDeps(content: string): string;
+type TransformGroup = 'imports' | 'props' | 'css' | 'config' | 'deps';
+declare const ALL_GROUPS: readonly TransformGroup[];
+interface TransformOptions {
+    groups?: readonly TransformGroup[];
+}
+declare function transformFile(filename: string, content: string, options?: TransformOptions): string;
+
+export { ALL_GROUPS, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformPresetColors, transformProps };
+export type { TransformGroup, TransformOptions };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+declare function transformImports(content: string): string;
+declare function transformProps(content: string): string;
+declare function transformCssVars(content: string): string;
+declare function transformHslVar(content: string): string;
+declare function transformConfig(content: string): string;
+declare function transformPresetColors(content: string): string;
+declare function transformDeps(content: string): string;
+type TransformGroup = 'imports' | 'props' | 'css' | 'config' | 'deps';
+declare const ALL_GROUPS: readonly TransformGroup[];
+interface TransformOptions {
+    groups?: readonly TransformGroup[];
+}
+declare function transformFile(filename: string, content: string, options?: TransformOptions): string;
+
+export { ALL_GROUPS, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformPresetColors, transformProps };
+export type { TransformGroup, TransformOptions };

package/dist/index.mjs

@@ -0,0 +1,129 @@
+const IMPORT_PATH = /(['"])maz-ui\/(styles|aos-styles)\1/g;
+function transformImports(content) {
+  return content.replace(IMPORT_PATH, (_, q, sub) => `${q}maz-ui/${sub === "styles" ? "style.css" : "aos.css"}${q}`);
+}
+const ICON_ATTR = /(\s:?)(left|right)-icon\b/g;
+const ICON_SLOT = /#(left|right)-icon\b/g;
+const ICON_LEFT_RIGHT_SLOT = /#icon-(left|right)\b/g;
+const FOOTER_ALIGN = /(\sfooter-align\s*=\s*['"])(left|right)(['"])/g;
+const ROUNDED_SIZE_BASE = /(\srounded-size\s*=\s*['"])base(['"])/g;
+const ACTIVE_COLOR_BG = /(\sactive-color\s*=\s*['"])background(['"])/g;
+const HAS_ICON_CLASS = /\.--has-(left|right)-icon\b/g;
+const MAZ_OPEN_TAG = /<Maz[A-Z]\w*\b[^>]*>/g;
+const VARIANT_LR = /(\svariant\s*=\s*['"])(left|right)(['"])/g;
+const COLOR_BG = /(\scolor\s*=\s*['"])background(['"])/g;
+function flipDirection(value) {
+  return value === "left" ? "start" : "end";
+}
+function transformProps(content) {
+  let out = content;
+  out = out.replace(ICON_ATTR, (_, prefix, dir) => `${prefix}${flipDirection(dir)}-icon`);
+  out = out.replace(ICON_SLOT, (_, dir) => `#${flipDirection(dir)}-icon`);
+  out = out.replace(ICON_LEFT_RIGHT_SLOT, (_, dir) => `#icon-${flipDirection(dir)}`);
+  out = out.replace(FOOTER_ALIGN, (_, p, dir, s) => `${p}${flipDirection(dir)}${s}`);
+  out = out.replace(ROUNDED_SIZE_BASE, (_, p, s) => `${p}md${s}`);
+  out = out.replace(ACTIVE_COLOR_BG, (_, p, s) => `${p}surface${s}`);
+  out = out.replace(HAS_ICON_CLASS, (_, dir) => `.--has-${flipDirection(dir)}-icon`);
+  out = out.replace(MAZ_OPEN_TAG, (tag) => tag.replace(VARIANT_LR, (_, p, dir, s) => `${p}${flipDirection(dir)}${s}`).replace(COLOR_BG, (_, p, s) => `${p}surface${s}`));
+  return out;
+}
+const MAZ_BACKGROUND = /--maz-background(?:(?![-\w])|(?=-(?:foreground|\d)))/g;
+const MAZ_BORDER_COLOR = /--maz-border(?:(?![-\w])|(?=-(?:foreground|\d)))/g;
+const MAZ_VAR = String.raw`var\(--(?:maz|m)-[\w-]+\)`;
+const HSL_WITH_ALPHA = new RegExp(String.raw`hsl\(\s*(${MAZ_VAR})\s*\/\s*([^)]+)\)`, "g");
+const HSL_NO_ALPHA = new RegExp(String.raw`hsl\(\s*(${MAZ_VAR})\s*\)`, "g");
+function transformCssVars(content) {
+  return content.replace(MAZ_BACKGROUND, "--maz-surface").replace(MAZ_BORDER_COLOR, "--maz-divider");
+}
+function transformHslVar(content) {
+  return content.replace(HSL_WITH_ALPHA, (_, v, alpha) => `color-mix(in srgb, ${v} ${alpha.trim()}, transparent)`).replace(HSL_NO_ALPHA, (_, v) => v);
+}
+const NUXT_INJECT_MAIN_CSS = /\binjectMainCss\b/g;
+const STRATEGY_HYBRID = /(\bstrategy\s*:\s*['"])hybrid(['"])/g;
+const DEPRECATED_THEME_OPTIONS = /^[^\S\n]*(?:injectCriticalCSS|injectFullCSS|injectAllCSSOnServer)\s*:[^,\n]*,?[^\S\n]*\n?/gm;
+function transformConfig(content) {
+  return content.replace(NUXT_INJECT_MAIN_CSS, "injectCss").replace(STRATEGY_HYBRID, (_, p, s) => `${p}runtime${s}`).replace(DEPRECATED_THEME_OPTIONS, "");
+}
+const LIGHT_DARK_BLOCK = /(\b(?:light|dark)\s*:\s*\{)([^{}]*)(\})/g;
+function transformPresetColors(content) {
+  return content.replace(LIGHT_DARK_BLOCK, (_, open, body, close) => {
+    const renamed = body.replace(/(['"]?)background\1(\s*:)/g, (_match, q, suffix) => `${q}surface${q}${suffix}`).replace(/(['"]?)border\1(\s*:)/g, (_match, q, suffix) => `${q}divider${q}${suffix}`);
+    return `${open}${renamed}${close}`;
+  });
+}
+const MAZ_UI_PKG = /^(?:maz-ui|@maz-ui\/.+)$/;
+const TARGET_VERSION = "^5.0.0";
+const PROTECTED_PREFIX = /^(?:workspace|link|file|portal|npm|http|https|git\+|github):/;
+function shouldBump(name, range) {
+  if (!MAZ_UI_PKG.test(name))
+    return false;
+  if (PROTECTED_PREFIX.test(range))
+    return false;
+  if (["latest", "next", "beta", "alpha", "canary", "*"].includes(range))
+    return false;
+  return range !== TARGET_VERSION;
+}
+function detectIndent(content) {
+  const match = content.match(/\n([ \t]+)"/);
+  return match ? match[1] : 2;
+}
+const DEP_FIELDS = ["dependencies", "devDependencies", "peerDependencies"];
+function transformDeps(content) {
+  let pkg;
+  try {
+    pkg = JSON.parse(content);
+  } catch {
+    return content;
+  }
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg))
+    return content;
+  let changed = false;
+  for (const field of DEP_FIELDS) {
+    const deps = pkg[field];
+    if (!deps || typeof deps !== "object" || Array.isArray(deps))
+      continue;
+    const map = deps;
+    for (const [name, range] of Object.entries(map)) {
+      if (typeof range !== "string")
+        continue;
+      if (shouldBump(name, range)) {
+        map[name] = TARGET_VERSION;
+        changed = true;
+      }
+    }
+  }
+  if (!changed)
+    return content;
+  const indent = detectIndent(content);
+  const trailingNewline = content.endsWith("\n") ? "\n" : "";
+  return JSON.stringify(pkg, null, indent) + trailingNewline;
+}
+const ALL_GROUPS = ["imports", "props", "css", "config", "deps"];
+function transformFile(filename, content, options = {}) {
+  const groups = options.groups ?? ALL_GROUPS;
+  const enabled = (g) => groups.includes(g);
+  const isVue = filename.endsWith(".vue");
+  const isCss = filename.endsWith(".css");
+  const isJs = /\.[cm]?[jt]sx?$/.test(filename);
+  const isPackageJson = /(?:^|[\\/])package\.json$/.test(filename);
+  let out = content;
+  if (enabled("imports") && (isVue || isJs))
+    out = transformImports(out);
+  if (enabled("props") && isVue)
+    out = transformProps(out);
+  if (enabled("css")) {
+    if (isVue || isCss)
+      out = transformCssVars(out);
+    if (isVue || isCss || isJs)
+      out = transformHslVar(out);
+  }
+  if (enabled("config") && (isVue || isJs)) {
+    out = transformConfig(out);
+    out = transformPresetColors(out);
+  }
+  if (enabled("deps") && isPackageJson)
+    out = transformDeps(out);
+  return out;
+}
+
+export { ALL_GROUPS, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformPresetColors, transformProps };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@maz-ui/upgrade",
+  "type": "module",
+  "version": "5.0.0-beta.0",
+  "description": "Automated source rewrites for migrating a project from Maz-UI v4 to v5.",
+  "author": "Louis Mazel <me@loicmazuel.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LouisMazel/maz-ui.git"
+  },
+  "bugs": "https://github.com/LouisMazel/maz-ui/issues",
+  "keywords": [
+    "maz-ui",
+    "upgrade",
+    "migration",
+    "v5"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "maz-ui-upgrade": "./dist/cli.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "globby": "^16.2.0",
+    "@maz-ui/node": "5.0.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1",
+    "vitest": "4.1.5",
+    "@maz-ui/eslint-config": "5.0.0-beta.0"
+  },
+  "lint-staged": {
+    "*.{js,ts,mjs,mts,cjs,md,yml,json}": "cross-env NODE_ENV=production eslint --fix"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "typecheck": "tsc --noEmit --skipLibCheck",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest watch",
+    "test:unit:coverage": "vitest run --coverage",
+    "lint": "cross-env NODE_ENV=production eslint .",
+    "lint:fix": "pnpm lint --fix"
+  }
+}