npm package: @hobui/viui-cli
Description: CLI to sync i-design-system .cursor (rules, skills, commands) into consumer repos
Latest version: 0.0.6

# @hobui/viui-cli


CLI to sync i-design-system `.cursor` (rules, skills, commands, plans) into consumer repos. Use this so Cursor/AI in the consumer repo follows the same design system rules, tokens, and BEM conventions.

**Scope:** Published as `@hobui/viui-cli`. Consumer installs with `pnpm add @hobui/viui-cli`.

## One-command UX (recommended)

At the consumer repo root, run:

```bash
pnpm add @hobui/viui-cli
```

After install, **postinstall** runs an interactive **setup wizard** (only when the terminal is interactive — not in CI):

1. **Step 1:** Init `.cursor` (rules, plans) and `src/plugins/viui-conf`, or sync if already present.
2. **Step 2:** Optionally install `@viui/web` for Vi* components (`pnpm add @viui/web`).
3. **Step 3:** Optionally add a postinstall script to auto-sync on future `pnpm install`.

No need to run `viui-cli init` or `pnpm add @viui/web` separately. To run the wizard again: `pnpm exec viui-cli setup` (use `-y` to skip prompts).

## Commands

| Command   | Description |
| --------- | ----------- |
| `setup`   | Interactive wizard: init/sync .cursor, install @viui/web, optional postinstall. Runs automatically after `pnpm add @hobui/viui-cli` (postinstall). |
| `init`    | Create `.cursor/` at repo root and copy rules, skills, commands (and optionally plans). Run once when onboarding. |
| `sync`    | Update existing `.cursor/` from the design system (overwrite). Use after design system updates. |
| `version` | Print CLI version and, if present, the synced design system version (from `.cursor/.design-system-version`). |

## Usage at consumer repo

**From npm (after publish) — one command:**

```bash
pnpm add @hobui/viui-cli
# then follow the setup wizard (Y/n per step)
```

**Manual steps (if you skip the wizard):**

```bash
pnpm add -D @hobui/viui-cli
pnpm exec viui-cli init
pnpm add @viui/web
```

**Local development (from i-design-system monorepo):**

1. Build the CLI from i-design-system root or `packages/cli`:

   ```bash
   pnpm build:cli
   # or: cd packages/cli && pnpm build
   ```

2. From the consumer repo root (e.g. kpi-5):

   ```bash
   node path/to/i-design-system/packages/cli/dist/cli.js init
   # or: pnpm exec --prefix path/to/i-design-system/packages/cli @hobui/viui-cli init
   ```

Always run `init` or `sync` from the **consumer repo root** (CWD = root). If you run from another folder (e.g. i-design-system), the wrong `.cursor` will be updated. The CLI logs `Syncing .cursor at: <path>` so you can confirm the target.

**Auto-sync after install:** If the consumer has `@hobui/viui-cli` as a dependency (e.g. `"@hobui/viui-cli": "file:../../i-design-system/packages/cli"`), add a script so `.cursor` is synced automatically after each `pnpm install`:

```json
"scripts": {
  "postinstall": "pnpm exec viui-cli sync"
}
```

Run `setup:ds` (or `pnpm exec viui-cli init`) once when first onboarding the repo; after that, `postinstall` keeps `.cursor` in sync when dependencies are installed.

## Init options

| Option       | Description |
| ------------ | ----------- |
| `-y`, `--yes`   | Skip confirmation (no prompt). |
| `--dry-run`     | Only print what would be copied; do not write files. |
| `--no-plans`    | Do not sync `.cursor/plans`. |

## Sync options

Sync overwrites existing files from the design system bundle and **removes** any file or folder in your `.cursor/` that is not in the bundle (so your `.cursor/` mirrors the bundle; files excluded via `.cursorignore` at build time will be removed on sync).

| Option            | Description |
| ------------------ | ----------- |
| `--dry-run`        | Only print what would be overwritten. |
| `--backup`         | Backup existing files before overwrite (`.backup.<timestamp>`). |
| `--rules-only`      | Sync only `.cursor/rules`. |
| `--skills-only`     | Sync only `.cursor/skills`. |
| `--commands-only`  | Sync only `.cursor/commands`. |

## What gets synced

- **rules** — Design system rules (tokens, BEM, component naming, Storybook, etc.).
- **skills** — Cursor skills for design system and accessibility.
- **commands** — Cursor commands (e.g. audit, generate from Figma).
- **plans** — Optional plan docs (e.g. KPI template); use `--no-plans` on init to skip.

After init/sync, `.cursor/.design-system-version` contains the design system version (from i-design-system at CLI build time).

**For AI-generated code (Cursor / AI Agent):** Synced rules apply to **codegen** in the consumer repo. When generating Vue, Storybook or UI code, the agent must: (1) use **Vi\*** components from `@viui/web` (ViButton, ViInput, ViCard, ViMenu, ViButtonToggle, …) instead of raw Vuetify where available; (2) use **Tabler Icons** (`@tabler/icons-vue`) as the default icon set; (3) follow `.cursor/rules/storybook.mdc` (title, CSF3, vi-ui in stories) and `.cursor/rules/icons.mdc`. See also AGENTS.md in the design system repo (§ Codegen / AI Agent, § Rules 3 and 7) and `.cursor/plans/icons_free_sources.plan.md` if plans were synced.

**viui-conf:** Init and sync also copy the design system's **Vuetify config folder** (theme-base, v-light, v-dark, defaults) to **`src/plugins/viui-conf/`** in the consumer repo. The file **`vuetify.ts`** is **not** synced — you keep your own `src/plugins/vuetify.ts` and import from `./viui-conf` (e.g. `import { defaults } from './viui-conf/defaults'`, `import LightTheme from './viui-conf/v-light'`). See [packages/docs/consumer-update.md](../docs/consumer-update.md) (§4).

**viui-themes (SCSS):** Init and sync also copy **design style themes** (neo-brutalism, material, minimalist, etc.) to **`src/assets/styles/viui-themes/`** and create **`src/assets/styles/viui-themes-entry.scss`**. If the consumer has **`src/assets/styles/main.scss`**, the CLI adds an import for `viui-themes-entry` so theme SCSS is loaded automatically. Set `VITE_VIUI_THEME=neo-brutalism` (or another theme id) in `.env` and add `body.classList.add('design-style-neo-brutalism')` (or the matching class) in your app so the theme styles apply globally. See `src/plugins/viui-conf/defaults/README.md` after sync.

### Excluding files when building the CLI (`.cursorignore`)

In **packages/cli**, the file **`.cursorignore`** is read by the copy script when building the CLI. Paths matching its patterns are not copied from i-design-system `.cursor/` into `dist/assets/cursor/`, so they are not synced to consumers. One pattern per line; lines starting with `#` and empty lines are ignored. Supported patterns:

- **`filename`** — skip any file or folder with this name (e.g. `KPI_COMPONENT_TEMPLATE.md`).
- **`*.ext`** — skip any file whose name ends with `.ext` (e.g. `*.plan.md`, `*.log`).
- **`category/path`** — skip the path under that category (e.g. `plans/CLI_BUILD.plan.md`).

Edit `packages/cli/.cursorignore` and run `pnpm build` in packages/cli (or `pnpm build:cli` from root) for changes to take effect.

## Design system package

To use components in the consumer app, install the design system package:

```bash
pnpm add @viui/web
```

Then import components: `import { ViButton, ViInput, ... } from '@viui/web'`. See [CLI_BUILD.plan.md](../../.cursor/plans/CLI_BUILD.plan.md) and root README for full setup.

## Build

```bash
pnpm build
```

Runs `tsc` and copies `.cursor` from repo root into `dist/assets/cursor/`, and writes `.design-system-version` from root `package.json`. Published package includes `dist/` so `npx @hobui/viui-cli init` works without the source repo.