@codefast/cli 0.3.16-canary.2 → 0.4.0-canary.4

package/README.md

@@ -18,9 +18,13 @@ A small developer CLI for maintenance tasks in a TypeScript monorepo — Tailwin
 - [Global options](#global-options)
 - [Exit codes](#exit-codes)
 - [`arrange`](#arrange)
-- [`mirror sync`](#mirror-sync)
-- [`tag` / `annotate`](#tag--annotate)
+- [`mirror`](#mirror)
+- [`tag`](#tag)
 - [Configuration (`codefast.config.*`)](#configuration-codefastconfig)
+  - [Full skeleton](#full-skeleton)
+  - [`mirror` configuration](#mirror-configuration)
+  - [`tag` configuration](#tag-configuration)
+  - [`arrange` configuration](#arrange-configuration)
 - [Lifecycle hooks](#lifecycle-hooks)
 - [Grouping philosophy — Render Pipeline Order](#grouping-philosophy--render-pipeline-order)
 - [Troubleshooting](#troubleshooting)
@@ -36,7 +40,9 @@ Three recurring maintenance chores you don't want to script by hand:
 
 - **`arrange`** — regroup Tailwind class strings inside `cn()` / `tv()` calls in render-pipeline order.
 - **`mirror`** — regenerate `package.json` `exports` fields from built `dist/` trees across a pnpm workspace.
-- **`tag`** (alias **`annotate`**) — add `@since <version>` JSDoc tags to exported declarations that are missing version metadata.
+- **`tag`** — add `@since <version>` JSDoc tags to exported declarations that are missing version metadata.
+
+Each top-level command **performs its action by default** (writing files). Pass `--dry-run` to preview without writing. `arrange` additionally exposes a read-only `inspect` report.
 
 ```mermaid
 flowchart LR
@@ -45,19 +51,16 @@ flowchart LR
   R --> M[mirror]
   R --> T[tag]
 
-  A --> A0[analyze]
-  A --> A1[preview]
-  A --> A2[apply]
-  A --> A3[group]
-
-  M --> M0[sync]
+  A --> A0[inspect]
+  A --> A1[simplify]
+  A --> A2[group]
 ```
 
 ---
 
 ## Requirements
 
-- Node.js `>= 22.0.0`
+- Node.js `>= 24.0.0`
 - pnpm (recommended — the CLI discovers workspaces via `pnpm-workspace.yaml`)
 
 ---
@@ -83,17 +86,17 @@ npx @codefast/cli --help
 ## Quick Start
 
 ```bash
-# Analyze Tailwind classes in the nearest package
-codefast arrange analyze
+# Inspect Tailwind classes in the nearest package (read-only report)
+codefast arrange inspect
 
 # Preview proposed rewrites — no files written
-codefast arrange preview packages/ui/src/components
+codefast arrange --dry-run packages/ui/src/components
 
 # Apply after reviewing
-codefast arrange apply packages/ui/src/components
+codefast arrange packages/ui/src/components
 
 # Regenerate every package's `exports` from built dist/
-codefast mirror sync
+codefast mirror
 
 # Add @since <version> to exported APIs under ./src
 codefast tag
@@ -109,15 +112,17 @@ codefast tag
 | `-V`, `--version` | Print the CLI version and exit.                                        |
 | `-h`, `--help`    | Show contextual help for the invoked command.                          |
 
+> **Placement.** Global flags must come **before** the command name (git-style), e.g. `codefast --no-color mirror`. A flag after the command name binds to that command.
+
 ---
 
 ## Exit codes
 
-| Code | Meaning                                                                                                  |
-| ---- | -------------------------------------------------------------------------------------------------------- |
-| `0`  | Success.                                                                                                 |
-| `1`  | General failure (missing paths, infrastructure errors, partial failures in `mirror sync`, failed hooks). |
-| `2`  | Invalid invocation or input (Zod schema validation on CLI requests — `CLI_EXIT_USAGE`).                  |
+| Code | Meaning                                                                                             |
+| ---- | --------------------------------------------------------------------------------------------------- |
+| `0`  | Success.                                                                                            |
+| `1`  | General failure (missing paths, infrastructure errors, partial failures in `mirror`, failed hooks). |
+| `2`  | Invalid invocation or input (Zod schema validation on CLI requests — `CLI_EXIT_USAGE`).             |
 
 Diagnostics go to **stderr**; primary command output goes to **stdout**. When a subcommand accepts `--json`, only the JSON object is written to stdout and all human progress is suppressed, so the stream stays pipeline-safe.
 
@@ -133,25 +138,28 @@ When `[target]` is omitted, `arrange` auto-detects the **nearest package directo
 
 ### Workflow
 
-| Step | Command                             | Effect                                |
-| ---- | ----------------------------------- | ------------------------------------- |
-| 1    | `codefast arrange analyze [target]` | Report only — no files changed        |
-| 2    | `codefast arrange preview [target]` | Show exactly what `apply` would write |
-| 3    | `codefast arrange apply [target]`   | Write the changes                     |
+| Step | Command                               | Effect                                         |
+| ---- | ------------------------------------- | ---------------------------------------------- |
+| 1    | `codefast arrange inspect [target]`   | Report only — no files changed                 |
+| 2    | `codefast arrange --dry-run [target]` | Show exactly what a bare `arrange` would write |
+| 3    | `codefast arrange [target]`           | Write the changes                              |
 
-### Flags (preview / apply)
+### Flags (`arrange`)
 
 | Flag                 | Description                                                                 |
 | -------------------- | --------------------------------------------------------------------------- |
+| `--dry-run`          | Preview the rewrite without writing files.                                  |
 | `--with-class-name`  | Append `className` as the last argument when rewriting a `cn(...)` call.    |
 | `--cn-import <spec>` | Override the module specifier used when a missing `cn` import is added.     |
 | `--json`             | Print a single JSON object on stdout; suppresses human progress and colors. |
 
-`analyze` also supports `--json`.
+`inspect` also supports `--json`. `simplify` accepts `--dry-run` and `--json`.
+
+> **Test files are skipped.** Directory scans exclude `*.test.*` / `*.spec.*` files — a `cn(...)` inside an assertion is test data, not styling to reformat. Pass such a file explicitly to override.
 
 ### `arrange group` — one-shot classification
 
-Groups a class string without touching the filesystem. Useful for checking how classes would be grouped before running `apply`:
+Groups a class string without touching the filesystem. Useful for checking how classes would be grouped before running `arrange`:
 
 ```bash
 # Quoted string
@@ -172,44 +180,47 @@ codefast arrange group --tv "flex items-center gap-2"
 
 ### `--json` payloads
 
-| Subcommand          | Payload highlights                                                                                                                         |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `analyze`           | `schemaVersion`, `analyzeRootPath`, full `report` (same data as the human report).                                                         |
-| `preview` / `apply` | `schemaVersion`, `write`, `ok` (`false` if the `onAfterWrite` hook failed), full `result` (`filePaths`, `modifiedFiles`, `totalFound`, …). |
-| `group`             | `schemaVersion`, `primaryLine`, `bucketsCommentLine`.                                                                                      |
+| Subcommand | Payload highlights                                                                                                                         |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `arrange`  | `schemaVersion`, `write`, `ok` (`false` if the `onAfterWrite` hook failed), full `result` (`filePaths`, `modifiedFiles`, `totalFound`, …). |
+| `inspect`  | `schemaVersion`, `analyzeRootPath`, full `report` (same data as the human report).                                                         |
+| `simplify` | `schemaVersion`, `write`, `ok`, full `result`.                                                                                             |
+| `group`    | `schemaVersion`, `primaryLine`, `bucketsCommentLine`.                                                                                      |
 
 ---
 
-## `mirror sync`
+## `mirror`
 
 Scans built `dist/` trees and regenerates the `exports` field of every workspace package. Run it from anywhere inside the monorepo — the workspace root is discovered via `pnpm-workspace.yaml`.
 
 ```bash
-codefast mirror sync                 # all workspace packages
-codefast mirror sync packages/ui     # one package (path relative to repo root)
-codefast mirror sync -v              # verbose diagnostics
-codefast mirror sync --json          # JSON summary for scripts / CI
+codefast mirror                 # all workspace packages
+codefast mirror packages/ui     # one package (path relative to repo root)
+codefast mirror --dry-run       # preview — report changes without writing
+codefast mirror -v              # verbose diagnostics
+codefast mirror --json          # JSON summary for scripts / CI
 ```
 
-| Flag              | Description                                                           |
-| ----------------- | --------------------------------------------------------------------- |
-| `-v`, `--verbose` | Print extra diagnostics.                                              |
-| `--json`          | Print a single `{ schemaVersion, ok, elapsedSeconds, stats }` object. |
+| Flag              | Description                                                                  |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `--dry-run`       | Report what would change without writing any `package.json`.                 |
+| `-v`, `--verbose` | Print extra diagnostics.                                                     |
+| `--json`          | Print a single `{ schemaVersion, ok, write, elapsedSeconds, stats }` object. |
 
-> **Build first.** `mirror sync` reads from `dist/`. Run your build before syncing or exports will reflect stale output.
+> **Build first.** `mirror` reads from `dist/`. Run your build before syncing or exports will reflect stale output.
 
 Exit code is `1` when any package fails (`stats.packagesErrored > 0`), `0` otherwise.
 
 ---
 
-## `tag` / `annotate`
+## `tag`
 
 Scans `.ts` / `.tsx` sources and adds `@since <current-package-version>` to exported declarations that don't already carry one. The version is read from the nearest `package.json` walking up from the target path.
 
 ```bash
 codefast tag                   # auto-discover workspace packages from cwd
-codefast tag packages/ui/src   # annotate a custom target
-codefast annotate --dry-run    # preview only, do not write
+codefast tag packages/ui/src   # tag a custom target
+codefast tag --dry-run         # preview only, do not write
 codefast tag --json            # JSON summary for scripts / CI
 ```
 
@@ -228,37 +239,46 @@ What it updates:
 
 ## Configuration (`codefast.config.*`)
 
-Create `codefast.config.js`, `.mjs`, `.cjs`, or `.json` at the repo root. Each command reads its own slice.
+Create a config file at the **monorepo root** (next to `pnpm-workspace.yaml`). Supported names, in priority order:
+
+| File name              | Format                                  |
+| ---------------------- | --------------------------------------- |
+| `codefast.config.mjs`  | ES module — `export default { … }`      |
+| `codefast.config.js`   | ES module (if `"type":"module"`) or CJS |
+| `codefast.config.cjs`  | CommonJS — `module.exports = { … }`     |
+| `codefast.config.json` | Plain JSON (no functions — no hooks)    |
+
+The file is found by walking up from the working directory, so running the CLI from any sub-directory still picks up the root config.
+
+> **Security.** `.js`, `.mjs`, and `.cjs` files are executed via `import()`. Only run `codefast` inside repositories you trust.
+
+---
+
+### Full skeleton
 
 ```javascript
 // codefast.config.mjs
 import { execSync } from "node:child_process";
 
 export default {
+  // ─── mirror ────────────────────────────────────────────────────────────────
+  // Keys are package names (from package.json#name).
+  // Set a package to `false` to skip it entirely.
+  // Omit a package to process it with default settings.
   mirror: {
-    skipPackages: ["@acme/internal"],
-    pathTransformations: {
-      "@acme/ui": { removePrefix: "./components/" },
-    },
-    customExports: {
-      "@acme/ui": {
-        "./css/*": "./src/styles/*",
-      },
-    },
-    cssExports: {
-      // Shorthand: `true` enables default CSS export detection
-      "@acme/theme": true,
-      // Or configure explicitly:
-      "@acme/ui": {
-        enabled: true,
-        forceExportFiles: false,
-        customExports: {
-          "./tokens.css": "./dist/tokens.css",
-        },
-      },
+    "@acme/ui": {
+      strip: "./components/",
+      exports: { "./css/*": "./src/css/*" },
+      source: true, // default: true
+      types: true, // default: true
+      import: true, // default: true
+      css: true,
     },
+    "@acme/internal": false,
+    "@acme/docs": false,
   },
 
+  // ─── tag ───────────────────────────────────────────────────────────────────
   tag: {
     skipPackages: ["@acme/internal"],
     onAfterWrite: ({ files }) => {
@@ -266,6 +286,7 @@ export default {
     },
   },
 
+  // ─── arrange ───────────────────────────────────────────────────────────────
   arrange: {
     onAfterWrite: ({ files }) => {
       execSync(`oxfmt ${files.join(" ")}`, { stdio: "inherit" });
@@ -274,31 +295,177 @@ export default {
 };
 ```
 
-Notes:
+---
+
+### `mirror` configuration
+
+`mirror` is a record keyed by **package name** (the `name` field in the package's `package.json`, e.g. `"@acme/ui"`).
+
+#### Skipping a package
+
+Set a package to `false` to exclude it from `codefast mirror` entirely:
+
+```javascript
+mirror: {
+  "@acme/internal": false,
+  "@acme/docs": false,
+}
+```
+
+Packages not mentioned in the config are processed with default settings.
+
+#### Per-package options
+
+Each package entry is an object with the following fields:
+
+| Field      | Type                     | Default | Description                                                                                                                                                                                                                                |
+| ---------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `source`   | `boolean \| string`      | `true`  | Add a `source` condition to each export entry pointing to the original `.ts` file. `true` auto-derives the path (`./src/<module>.ts`). Pass a string to set the root-export path explicitly (`"./src/index.tsx"`). Set to `false` to omit. |
+| `types`    | `boolean`                | `true`  | Include the `types` condition when a `.d.ts` file is present. Set to `false` to omit.                                                                                                                                                      |
+| `import`   | `boolean`                | `true`  | Include the `import` condition. Set to `false` to omit (useful for CJS-only packages).                                                                                                                                                     |
+| `strip`    | `string`                 | —       | Strip a leading path segment from generated export specifiers. See below.                                                                                                                                                                  |
+| `exports`  | `Record<string, string>` | —       | Add or override specific export specifiers. See below.                                                                                                                                                                                     |
+| `preserve` | `boolean`                | —       | Keep the existing `package.json#exports` and only fill in missing conditions.                                                                                                                                                              |
+| `css`      | `boolean \| CssConfig`   | —       | Enable CSS export detection. See below.                                                                                                                                                                                                    |
+
+#### `strip`
+
+Removes a fixed prefix from every generated export specifier. Use this when a package's `dist/` mirrors deep directory structure that you want to flatten in the public API.
+
+```javascript
+// Without strip, dist/components/button.mjs → "./components/button"
+// With strip: "./components/", it becomes → "./button"
+"@acme/ui": {
+  strip: "./components/",
+}
+```
+
+The original file path is preserved for sorting — only the public specifier changes.
+
+#### `exports`
+
+Adds or overrides specific specifiers in the final export map. Keys and values are the exact strings written into `package.json#exports`.
+
+```javascript
+"@acme/ui": {
+  exports: {
+    "./css/*": "./src/css/*",        // wildcard passthrough to sources
+    "./tokens": "./dist/tokens.js",  // explicit extra entry
+  },
+}
+```
 
-- Keys in `mirror.skipPackages` / `pathTransformations` / `customExports` / `cssExports` are **package names** from `package.json#name` (e.g. `@acme/ui`). Path-based keys such as `packages/ui` are deprecated and will be removed.
-- `cssExports[pkg]` accepts a boolean shorthand or the full `{ enabled, customExports, forceExportFiles }` object.
-- `tag.skipPackages` lists package names to skip entirely when `codefast tag` is run without an explicit target.
+Extra entries are merged after auto-generation. They win over anything the scanner would produce for the same specifier. `./package.json` cannot be overridden.
 
-> **Security.** `.js`, `.mjs`, and `.cjs` config files are loaded via `import()` — only run `codefast` inside repositories you trust.
+#### `preserve`
+
+Keeps the existing `package.json#exports` map exactly as-is and only fills in missing conditions (`source`, `types`, `import`) for each entry — no `dist/` scan is performed. Use this when you maintain the exports map by hand and only want the CLI to supplement missing conditions.
+
+```javascript
+"@acme/tailwind-variants": {
+  preserve: true,
+}
+```
+
+#### `css`
+
+Controls CSS file export generation. `mirror` scans `dist/` for `.css` files and writes wildcard or per-file export entries.
+
+```javascript
+// Shorthand: auto-detect all CSS files in dist/
+"@acme/theme": { css: true }
+
+// Full config:
+"@acme/ui": {
+  css: {
+    enabled: true,
+    // Force individual file entries instead of directory wildcards:
+    forceExportFiles: false,
+    // Manually add or override individual CSS specifiers:
+    customExports: {
+      "./tokens.css": "./dist/tokens.css",
+    },
+  },
+}
+
+// Explicitly disable CSS exports for this package:
+"@acme/legacy": { css: false }
+```
+
+When `css` is omitted, CSS files found in `dist/` are still exported by default.
+
+#### What `mirror` writes
+
+For a package with `dist/button.mjs`, `dist/button.d.ts`, and `source: true`, the generated export entry looks like:
+
+```json
+{
+  "./button": {
+    "source": "./src/button.ts",
+    "types": "./dist/button.d.ts",
+    "import": "./dist/button.mjs"
+  }
+}
+```
+
+It also updates the top-level `main`, `module`, and `types` fields from the root (`.`) export, and ensures `"dist"` is listed in `files`.
+
+---
+
+### `tag` configuration
+
+```javascript
+tag: {
+  // Package names to skip when running without an explicit target
+  skipPackages: ["@acme/internal", "@acme/docs"],
+
+  // Called after files are written — use it to format or lint-fix
+  onAfterWrite: ({ files }) => {
+    execSync(`prettier --write ${files.join(" ")}`, { stdio: "inherit" });
+  },
+}
+```
+
+| Field          | Type                                                  | Description                                                                                                                         |
+| -------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `skipPackages` | `string[]`                                            | Package names to skip when `codefast tag` is run without an explicit target. Has no effect when a target path is provided directly. |
+| `onAfterWrite` | `(ctx: { files: string[] }) => void \| Promise<void>` | Lifecycle hook — runs after files are written.                                                                                      |
+
+---
+
+### `arrange` configuration
+
+```javascript
+arrange: {
+  // Called after files are written by `codefast arrange`
+  onAfterWrite: ({ files }) => {
+    execSync(`oxfmt ${files.join(" ")}`, { stdio: "inherit" });
+  },
+}
+```
+
+| Field          | Type                                                  | Description                                                                      |
+| -------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `onAfterWrite` | `(ctx: { files: string[] }) => void \| Promise<void>` | Lifecycle hook — runs after `arrange` writes files. Not called with `--dry-run`. |
 
 ---
 
 ## Lifecycle hooks
 
-Both `tag` and `arrange apply` expose an `onAfterWrite` hook so teams can plug in their own formatter, lint-fix step, or codemod without embedding one in the CLI core.
+Both `tag` and `arrange` call `onAfterWrite` immediately after writing files to disk. The hook receives the list of written file paths and can run any synchronous or asynchronous work — formatters, linters, codegen, notifications.
 
 ```javascript
 export default {
   tag: {
     onAfterWrite: async ({ files }) => {
-      console.log(`Formatting ${files.length} files…`);
-      // sync or async work
+      // async is supported
+      await runFormatter(files);
     },
   },
   arrange: {
     onAfterWrite: ({ files }) => {
-      /* … */
+      // sync is fine too
+      execSync(`oxfmt ${files.join(" ")}`, { stdio: "inherit" });
     },
   },
 };
@@ -306,10 +473,11 @@ export default {
 
 Contract:
 
-- `tag.onAfterWrite?.({ files })` runs after `codefast tag` writes files.
-- `arrange.onAfterWrite?.({ files })` runs after `codefast arrange apply` writes files.
-- Hooks may be synchronous or asynchronous (`void | Promise<void>`).
-- Hook failures are reported on stderr; both commands exit with code `1` when the hook rejects.
+- `tag.onAfterWrite` fires after `codefast tag` writes JSDoc annotations.
+- `arrange.onAfterWrite` fires after `codefast arrange` rewrites class strings.
+- Hook is **not** called on `--dry-run`.
+- Hooks may be synchronous or `async` (`void | Promise<void>`).
+- If the hook throws or rejects, the command reports the error on stderr and exits with code `1`.
 
 ---
 
@@ -348,14 +516,14 @@ To change placement, extend `classifyBareUtility` in `packages/cli/src/arrange/d
 **`codefast: command not found`**
 Install globally with `pnpm add -g @codefast/cli`, or run via `pnpm dlx @codefast/cli <command>`.
 
-**`mirror sync` writes little or no output**
-Packages must be built first. Ensure `dist/` exists by running your build step, then re-run `codefast mirror sync`.
+**`mirror` writes little or no output**
+Packages must be built first. Ensure `dist/` exists by running your build step, then re-run `codefast mirror`.
 
-**Unexpected class reorder after `arrange apply`**
-Run `arrange preview` first and smoke-test the UI. Some components rely on cascade-sensitive ordering that `arrange` cannot detect automatically.
+**Unexpected class reorder after `arrange`**
+Run `arrange --dry-run` first and smoke-test the UI. Some components rely on cascade-sensitive ordering that `arrange` cannot detect automatically.
 
 **`--json` output mixed with progress lines**
-Some shells buffer progress writes on stderr into stdout when piping — redirect stderr explicitly: `codefast mirror sync --json 2>/dev/null | jq`.
+Some shells buffer progress writes on stderr into stdout when piping — redirect stderr explicitly: `codefast mirror --json 2>/dev/null | jq`.
 
 ---
 
@@ -377,7 +545,7 @@ A few naming conventions:
 
 - **`codefast <command>`** refers to CLI commands exposed via the `bin` entry in `@codefast/cli`.
 - **Scripts in `packages/cli/package.json`** (`build`, `test`, …) are package-local dev scripts, not CLI commands.
-- The root `package.json` includes optional convenience wrappers (e.g. `cli:mirror-sync`, `cli:arrange-analyze`) for common dev workflows.
+- The root `package.json` includes optional convenience wrappers (e.g. `cli:mirror`, `cli:arrange-inspect`) for common dev workflows.
 
 ---
 

package/dist/arrange/analyze.mjs

@@ -1,8 +1,8 @@
-import { AppError, messageFrom } from "../core/errors.mjs";
-import { err, ok } from "../core/result.mjs";
 import { accumulateAnalyzeReportForSourceFile, createEmptyAnalyzeReport } from "./domain/analyze-service.mjs";
+import { AppError, messageFrom } from "../core/errors.mjs";
 import { scanArrangeTargets } from "./scan-target.mjs";
 import { parseDomainSourceFile } from "./source-parse.mjs";
+import { err, ok } from "../core/result.mjs";
 //#region src/arrange/analyze.ts
 /**
 * @since 0.3.16-canary.0

package/dist/arrange/command.mjs

@@ -1,15 +1,16 @@
-import { parseWithSchema } from "../core/schema-parse.mjs";
-import "../core/exit-codes.mjs";
 import { logger } from "../core/logger.mjs";
-import { consumeCliAppError, runCliResultAsync } from "../core/cli/result-handle.mjs";
-import { nodeFilesystem } from "../core/filesystem/node.mjs";
-import { arrangeAnalyzeDirectoryRequestSchema, arrangeSuggestGroupsRequestSchema, arrangeSyncRunRequestSchema } from "./cli-schema.mjs";
-import { prepareArrangeWorkspace } from "./workspace.mjs";
 import { analyzeDirectory } from "./analyze.mjs";
-import { runArrangeSync } from "./sync.mjs";
+import { arrangeAnalyzeDirectoryRequestSchema, arrangeSuggestGroupsRequestSchema, arrangeSyncRunRequestSchema } from "./cli-schema.mjs";
+import { printAnalyzeReport, printGroupFilePreviewFromWork, printSimplifyResult, printSyncResult } from "./output.mjs";
+import { runArrangeSimplify } from "./simplify-sync.mjs";
 import { suggestCnGroupsFromCli } from "./suggest.mjs";
-import { printAnalyzeReport, printGroupFilePreviewFromWork, printSyncResult } from "./output.mjs";
+import { runArrangeSync } from "./sync.mjs";
+import { prepareArrangeWorkspace } from "./workspace.mjs";
 import { readOptionalPositionalArg } from "../core/cli/positional.mjs";
+import "../core/exit-codes.mjs";
+import { consumeCliAppError, runCliResultAsync } from "../core/cli/result-handle.mjs";
+import { nodeFilesystem } from "../core/filesystem/node.mjs";
+import { parseWithSchema } from "../core/schema-parse.mjs";
 import process from "node:process";
 import { Command } from "commander";
 //#region src/arrange/command.ts
@@ -17,22 +18,8 @@ import { Command } from "commander";
 * @since 0.3.16-canary.0
 */
 function createArrangeCommand() {
-	const cmd = new Command("arrange").description("Analyze and regroup Tailwind classes in cn() / tv() calls (Tailwind v4)");
-	cmd.command("analyze").description("Report long strings, nested cn in tv(), and related findings").argument("[target]", "Directory or file (default: nearest package directory from cwd)").option("--json", "Print one JSON object on stdout instead of a human report", false).action(async (target, opts) => {
-		const prelude = await prepareArrangeWorkspace(nodeFilesystem, {
-			currentWorkingDirectory: process.cwd(),
-			rawTarget: readOptionalPositionalArg(target)
-		});
-		if (!consumeCliAppError(prelude)) return;
-		const { resolvedTarget } = prelude.value;
-		const parsed = parseWithSchema(arrangeAnalyzeDirectoryRequestSchema, { analyzeRootPath: resolvedTarget });
-		if (!consumeCliAppError(parsed)) return;
-		const outcome = analyzeDirectory(nodeFilesystem, parsed.value.analyzeRootPath);
-		if (!consumeCliAppError(outcome)) return;
-		if (opts.json) logger.out(formatArrangeAnalyzeJsonOutput(resolvedTarget, outcome.value));
-		else printAnalyzeReport(resolvedTarget, outcome.value);
-	});
-	const previewOrApply = (write) => async (target, opts) => {
+	const cmd = new Command("arrange").description("Regroup Tailwind classes in cn() / tv() calls in render-pipeline order").enablePositionalOptions().argument("[target]", "Directory or file (default: nearest package directory from cwd)").option("--dry-run", "Preview suggested replacements without writing files", false).option("--with-classname, --with-class-name", "Append className as final cn() argument", false).option("--cn-import <spec>", "Override module specifier when adding cn import").option("--json", "Print one JSON object on stdout (suppresses human progress)", false).action(async (target, opts) => {
+		const write = !opts.dryRun;
 		const prelude = await prepareArrangeWorkspace(nodeFilesystem, {
 			currentWorkingDirectory: process.cwd(),
 			rawTarget: readOptionalPositionalArg(target)
@@ -57,9 +44,46 @@ function createArrangeCommand() {
 			printSyncResult(value, write);
 			return exitCodeForArrangeSyncResult(value);
 		});
-	};
-	cmd.command("preview").description("Dry-run: print suggested replacements without writing files").argument("[target]", "Directory or file (default: nearest package directory from cwd)").option("--with-classname, --with-class-name", "Append className as final cn() argument", false).option("--cn-import <spec>", "Override module specifier when adding cn import").option("--json", "Print one JSON object on stdout (suppresses human progress)", false).action(previewOrApply(false));
-	cmd.command("apply").description("Apply grouping and cn-in-tv unwrap edits to files").argument("[target]", "Directory or file (default: nearest package directory from cwd)").option("--with-classname, --with-class-name", "Append className as final cn() argument", false).option("--cn-import <spec>", "Override module specifier when adding cn import").option("--json", "Print one JSON object on stdout (suppresses human progress)", false).action(previewOrApply(true));
+	});
+	cmd.command("inspect").description("Report long strings, nested cn in tv(), and related findings (read-only)").argument("[target]", "Directory or file (default: nearest package directory from cwd)").option("--json", "Print one JSON object on stdout instead of a human report", false).action(async (target, opts) => {
+		const prelude = await prepareArrangeWorkspace(nodeFilesystem, {
+			currentWorkingDirectory: process.cwd(),
+			rawTarget: readOptionalPositionalArg(target)
+		});
+		if (!consumeCliAppError(prelude)) return;
+		const { resolvedTarget } = prelude.value;
+		const parsed = parseWithSchema(arrangeAnalyzeDirectoryRequestSchema, { analyzeRootPath: resolvedTarget });
+		if (!consumeCliAppError(parsed)) return;
+		const outcome = analyzeDirectory(nodeFilesystem, parsed.value.analyzeRootPath);
+		if (!consumeCliAppError(outcome)) return;
+		if (opts.json) logger.out(formatArrangeAnalyzeJsonOutput(resolvedTarget, outcome.value));
+		else printAnalyzeReport(resolvedTarget, outcome.value);
+	});
+	cmd.command("simplify").description("Flatten grouped arrays and static-only cn() calls back to plain strings in tv() slots").argument("[target]", "Directory or file (default: nearest package directory from cwd)").option("--dry-run", "Show what simplify would change without writing files", false).option("--json", "Print one JSON object on stdout (suppresses human progress)", false).action(async (target, opts) => {
+		const write = !opts.dryRun;
+		const prelude = await prepareArrangeWorkspace(nodeFilesystem, {
+			currentWorkingDirectory: process.cwd(),
+			rawTarget: readOptionalPositionalArg(target)
+		});
+		if (!consumeCliAppError(prelude)) return;
+		const { resolvedTarget } = prelude.value;
+		await runCliResultAsync(runArrangeSimplify(nodeFilesystem, {
+			targetPath: resolvedTarget,
+			write
+		}), (value) => {
+			if (opts.json) {
+				logger.out(JSON.stringify({
+					schemaVersion: 1,
+					ok: true,
+					write,
+					result: value
+				}));
+				return 0;
+			}
+			printSimplifyResult(value, write);
+			return 0;
+		});
+	});
 	cmd.command("group").description("Try grouping on a pasted class string (stdout: cn(...) or tv array with --tv)").argument("<tokens...>", "Class tokens (quote a single string if it contains spaces)").option("--tv", "Emit tv()-style array instead of cn() call", false).option("--with-classname, --with-class-name", "Append className as final cn() argument", false).option("--json", "Print one JSON object on stdout instead of plain lines", false).action(async (classTokenSeries, opts) => {
 		const parsed = parseWithSchema(arrangeSuggestGroupsRequestSchema, {
 			inlineClasses: classTokenSeries.join(" ").trim(),

package/dist/arrange/domain/analyze-service.mjs

@@ -1,9 +1,9 @@
-import "./constants.mjs";
-import { tokenizeClassString } from "./tailwind-token.mjs";
 import { forEachDomainChild, isDomainCallExpression, isDomainJsxAttribute, isDomainObjectLiteralExpression } from "./ast/ast-node.mjs";
+import "./constants.mjs";
 import { forEachStringLiteralInClassExpression } from "./ast/collectors-cn.mjs";
 import { jsxClassNameStaticLiteral } from "./ast/collectors-jsx.mjs";
 import { buildKnownCnTvBindings, isCnOrTvIdentifier, lineOf } from "./ast/helpers.mjs";
+import { tokenizeClassString } from "./tailwind-token.mjs";
 import { collectCnCallsInsideTv, traverseTvObject } from "./ast/collectors-tv.mjs";
 //#region src/arrange/domain/analyze-service.ts
 /**

package/dist/arrange/domain/ast/collectors-cn.mjs

@@ -1,5 +1,5 @@
-import "../constants.mjs";
 import { isDomainArrayLiteralExpression, isDomainTailwindClassLiteral } from "./ast-node.mjs";
+import "../constants.mjs";
 //#region src/arrange/domain/ast/collectors-cn.ts
 /**
 * @since 0.3.16-canary.0