@codefast/cli 0.3.16-canary.3 → 0.4.0-canary.5

package/README.md

@@ -18,8 +18,8 @@ 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)
@@ -40,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
@@ -49,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`)
 
 ---
@@ -87,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
@@ -113,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.
 
@@ -137,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
@@ -176,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
 ```
 
@@ -296,7 +303,7 @@ export default {
 
 #### Skipping a package
 
-Set a package to `false` to exclude it from `codefast mirror sync` entirely:
+Set a package to `false` to exclude it from `codefast mirror` entirely:
 
 ```javascript
 mirror: {
@@ -362,7 +369,7 @@ Keeps the existing `package.json#exports` map exactly as-is and only fills in mi
 
 #### `css`
 
-Controls CSS file export generation. `mirror sync` scans `dist/` for `.css` files and writes wildcard or per-file export entries.
+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/
@@ -387,7 +394,7 @@ Controls CSS file export generation. `mirror sync` scans `dist/` for `.css` file
 
 When `css` is omitted, CSS files found in `dist/` are still exported by default.
 
-#### What `mirror sync` writes
+#### What `mirror` writes
 
 For a package with `dist/button.mjs`, `dist/button.d.ts`, and `source: true`, the generated export entry looks like:
 
@@ -430,22 +437,22 @@ tag: {
 
 ```javascript
 arrange: {
-  // Called after files are written by `codefast arrange apply`
+  // 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 apply` writes files. Not called by `arrange preview`. |
+| 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` 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.
+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 {
@@ -467,8 +474,8 @@ export default {
 Contract:
 
 - `tag.onAfterWrite` fires after `codefast tag` writes JSDoc annotations.
-- `arrange.onAfterWrite` fires after `codefast arrange apply` rewrites class strings.
-- Hook is **not** called on `--dry-run` or `arrange preview`.
+- `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`.
 
@@ -509,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`.
 
 ---
 
@@ -538,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

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

@@ -1,8 +1,8 @@
-import "../constants.mjs";
-import { tokenizeClassString } from "../tailwind-token.mjs";
 import { forEachDomainChild, isDomainArrayLiteralExpression, isDomainCallExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral } from "./ast-node.mjs";
+import "../constants.mjs";
 import { CN_APPLY_LITERAL_WALK_OPTS, collectUnconditionalTailwindLiteralsFromCnArguments, forEachStringLiteralInClassExpression, isUnsafeLiteralForCnStyleApplySplit } from "./collectors-cn.mjs";
 import { buildKnownCnTvBindings, isCnOrTvIdentifier, propertyAssignmentNameText } from "./helpers.mjs";
+import { tokenizeClassString } from "../tailwind-token.mjs";
 //#region src/arrange/domain/ast/collectors-tv.ts
 /**
 * @since 0.3.16-canary.0

package/dist/arrange/domain/ast/helpers.mjs

@@ -1,5 +1,5 @@
-import { EMPTY_CN_TV_BINDINGS } from "../constants.mjs";
 import { isDomainIdentifier, isDomainImportDeclaration, isDomainNamedImports, isDomainNamespaceImport, isDomainPropertyAccessExpression, isDomainStringLiteral, lineOfSourcePosition } from "./ast-node.mjs";
+import { EMPTY_CN_TV_BINDINGS } from "../constants.mjs";
 import { applyEditsDescending, indentOfLineContaining } from "../../../core/source-text-edit.mjs";
 //#region src/arrange/domain/ast/helpers.ts
 /**
@@ -21,7 +21,7 @@ const KNOWN_CN_TV_MODULES = new Set([
 function moduleLooksLikeCnTvReexport(moduleSpecifier) {
 	const norm = moduleSpecifier.replace(/\\/g, "/");
 	if (/(?:^|[./])utils(?:\/|$)/.test(norm)) return true;
-	if (/\/utils\//.test(norm) || /\/utils$/.test(norm)) return true;
+	if (/\/utils\//.test(norm) || norm.endsWith("/utils")) return true;
 	if (/(?:^|\/)cn\.tsx?$/.test(norm)) return true;
 	return false;
 }

package/dist/arrange/domain/ast/simplify-targets.mjs

@@ -0,0 +1,109 @@
+import { forEachDomainChild, isDomainArrayLiteralExpression, isDomainCallExpression, isDomainJsxAttribute, isDomainJsxExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral } from "./ast-node.mjs";
+import "../constants.mjs";
+import { indentOfLineContaining } from "../../../core/source-text-edit.mjs";
+import { buildKnownCnTvBindings, isCnOrTvIdentifier } from "./helpers.mjs";
+import { escapeTsStringLiteralContent } from "../source-text-formatters.mjs";
+//#region src/arrange/domain/ast/simplify-targets.ts
+function toFlatString(text) {
+	return `"${escapeTsStringLiteralContent(text.trim())}"`;
+}
+function joinLiterals(args) {
+	return args.filter(isDomainTailwindClassLiteral).map((lit) => lit.text).join(" ");
+}
+function isAllStaticLiterals(args) {
+	return args.length > 0 && args.every(isDomainTailwindClassLiteral);
+}
+/**
+* For a cn() call that has both static and dynamic args:
+* - Merge ALL static string literals (regardless of position) into one string.
+* - Place the merged string first.
+* - Append all dynamic args in their original relative order.
+*
+* Returns `null` when nothing changes (0 statics, or already 1 static at arg[0]).
+*/
+function buildMixedCnReplacement(call, sourceText) {
+	const args = [...call.arguments];
+	if (args.length === 0) return null;
+	const staticTexts = [];
+	const dynamicSrcs = [];
+	for (const arg of args) if (isDomainTailwindClassLiteral(arg)) staticTexts.push(arg.text);
+	else dynamicSrcs.push(sourceText.slice(arg.pos, arg.end));
+	if (staticTexts.length === 0) return null;
+	const firstArg = args[0];
+	if (staticTexts.length === 1 && firstArg !== void 0 && isDomainTailwindClassLiteral(firstArg)) return null;
+	const flatStatic = staticTexts.join(" ").trim();
+	const baseIndent = indentOfLineContaining(sourceText, call.pos);
+	const argIndent = `${baseIndent}  `;
+	return `cn(\n${[`${argIndent}"${escapeTsStringLiteralContent(flatStatic)}",`, ...dynamicSrcs.map((src) => `${argIndent}${src},`)].join("\n")}\n${baseIndent})`;
+}
+function collectTvArrayEdits(obj, results, depth) {
+	if (depth > 12) return;
+	for (const prop of obj.properties) {
+		if (!isDomainPropertyAssignment(prop)) continue;
+		const init = prop.initializer;
+		if (isDomainArrayLiteralExpression(init)) {
+			const elements = [...init.elements];
+			if (!elements.some(isDomainSpreadElement) && elements.length > 0 && isAllStaticLiterals(elements)) results.push({
+				start: init.pos,
+				end: init.end,
+				replacement: toFlatString(joinLiterals(elements)),
+				label: "tv-array"
+			});
+		} else if (isDomainObjectLiteralExpression(init)) collectTvArrayEdits(init, results, depth + 1);
+	}
+}
+/**
+* Collect all simplify edits for a source file:
+* - Arrays of pure string literals inside tv() slots → flat string
+* - cn() calls whose every argument is a static string literal → flat string (unwrap cn)
+* - cn() calls with mixed static + dynamic args → merge adjacent statics into one string
+* - JSX className={cn(...all-static...)} → className="flat string"
+*
+* @since 0.3.16-canary.0
+*/
+function collectSimplifyTargets(sourceFile) {
+	const sourceText = sourceFile.text;
+	const results = [];
+	const knownBindings = buildKnownCnTvBindings(sourceFile);
+	const seenCnPos = /* @__PURE__ */ new Set();
+	const visitNode = (node) => {
+		if (isDomainCallExpression(node)) {
+			if (isCnOrTvIdentifier(node.expression, "tv", knownBindings)) {
+				const arg0 = node.arguments[0];
+				if (arg0 && isDomainObjectLiteralExpression(arg0)) collectTvArrayEdits(arg0, results, 0);
+			} else if (isCnOrTvIdentifier(node.expression, "cn", knownBindings) && !seenCnPos.has(node.pos)) {
+				seenCnPos.add(node.pos);
+				const args = [...node.arguments];
+				if (isAllStaticLiterals(args)) {
+					const flat = joinLiterals(args);
+					const parent = node.parent;
+					if (parent && isDomainJsxExpression(parent) && parent.parent && isDomainJsxAttribute(parent.parent)) results.push({
+						start: parent.pos,
+						end: parent.end,
+						replacement: toFlatString(flat),
+						label: "jsx-cn"
+					});
+					else results.push({
+						start: node.pos,
+						end: node.end,
+						replacement: toFlatString(flat),
+						label: "cn-static"
+					});
+				} else {
+					const replacement = buildMixedCnReplacement(node, sourceText);
+					if (replacement !== null) results.push({
+						start: node.pos,
+						end: node.end,
+						replacement,
+						label: "cn-merge"
+					});
+				}
+			}
+		}
+		forEachDomainChild(node, visitNode);
+	};
+	for (const stmt of sourceFile.statements) visitNode(stmt);
+	return results;
+}
+//#endregion
+export { collectSimplifyTargets };

package/dist/arrange/domain/ast/targets.mjs

@@ -1,12 +1,12 @@
+import { forEachDomainChild, isDomainArrayLiteralExpression, isDomainJsxAttribute, isDomainPropertyAssignment, isDomainTailwindClassLiteral } from "./ast-node.mjs";
 import "../constants.mjs";
-import { tokenizeClassString } from "../tailwind-token.mjs";
-import { forEachDomainChild, isDomainArrayLiteralExpression, isDomainJsxAttribute, isDomainTailwindClassLiteral } from "./ast-node.mjs";
 import { isUnsafeLiteralForCnStyleApplySplit } from "./collectors-cn.mjs";
 import { jsxClassNameStaticLiteral } from "./collectors-jsx.mjs";
 import { endAfterOptionalCommaFollowingInSource, indentOfLineContaining, textPrefixFromLineStartToPosition } from "../../../core/source-text-edit.mjs";
+import { tokenizeClassString } from "../tailwind-token.mjs";
 import { collectGroupableStringNodes, slotClassString } from "./collectors-tv.mjs";
-import { areCnTailwindPartitionsEquivalent, suggestCnGroups, summarizeGroupBucketLabels } from "../grouping.mjs";
 import { escapeTsStringLiteralContent, formatArray, formatArrayElementsAsSiblingLines, formatJsxCnAttributeValue } from "../source-text-formatters.mjs";
+import { areCnTailwindPartitionsEquivalent, suggestCnGroups, summarizeGroupBucketLabels } from "../grouping.mjs";
 //#region src/arrange/domain/ast/targets.ts
 /**
 * @since 0.3.16-canary.0
@@ -62,7 +62,7 @@ function formatCnCallReplacement(stringNode, sourceText, withClassName) {
 	for (const dynamicArgumentSource of dynamicArgTexts) allArgs.push(`${argIndent}${dynamicArgumentSource}`);
 	if (withClassName) allArgs.push(`${argIndent}className`);
 	const commaAfterLastArg = allArgs.length > 1;
-	return `cn(\n${allArgs.map((argLine, lineIndex) => lineIndex < allArgs.length - 1 || commaAfterLastArg ? `${argLine},` : `${argLine}`).join("\n")}\n${baseIndent})`;
+	return `cn(\n${allArgs.map((argLine, lineIndex) => lineIndex < allArgs.length - 1 || commaAfterLastArg ? `${argLine},` : argLine).join("\n")}\n${baseIndent})`;
 }
 /**
 * @since 0.3.16-canary.0
@@ -88,14 +88,29 @@ function planGroupEditForTarget(target, textAfterUnwrap, withClassName) {
 	if (areCnTailwindPartitionsEquivalent(target.item.nodes.map((classLiteral) => classLiteral.text), groups)) return;
 	if (!target.item.cnCall) {
 		const anchorClassLiteral = target.item.primaryClassLiteral;
-		const parentArray = target.item.nodes.length > 1 && anchorClassLiteral.parent !== null && isDomainArrayLiteralExpression(anchorClassLiteral.parent) ? anchorClassLiteral.parent : null;
-		const start = parentArray ? parentArray.pos : anchorClassLiteral.pos;
-		const end = parentArray ? parentArray.end : endAfterOptionalCommaFollowingInSource(textAfterUnwrap, anchorClassLiteral.end);
-		const baseIndent = indentOfLineContaining(textAfterUnwrap, start);
+		const parentNode = anchorClassLiteral.parent;
+		const parentArray = target.item.nodes.length > 1 && parentNode !== null && isDomainArrayLiteralExpression(parentNode) ? parentNode : null;
+		const bareStringProperty = !parentArray && parentNode !== null && isDomainPropertyAssignment(parentNode);
+		if (parentArray || bareStringProperty) {
+			const start = parentArray ? parentArray.pos : anchorClassLiteral.pos;
+			const end = parentArray ? parentArray.end : anchorClassLiteral.end;
+			const baseIndent = indentOfLineContaining(textAfterUnwrap, start);
+			return {
+				start,
+				end,
+				replacement: formatArray(groups).split("\n").map((line, lineIndex) => lineIndex === 0 ? line : `${baseIndent}${line}`).join("\n"),
+				bucketSummary: summarizeGroupBucketLabels(groups),
+				jsxCn: false,
+				lineSf: target.item.sf,
+				reportNode: anchorClassLiteral,
+				label: target.item.isTvContext ? "tv" : "cn"
+			};
+		}
+		const start = anchorClassLiteral.pos;
 		return {
 			start,
-			end,
-			replacement: parentArray ? formatArray(groups).split("\n").map((line, lineIndex) => lineIndex === 0 ? line : `${baseIndent}${line}`).join("\n") : formatArrayElementsAsSiblingLines(groups, textPrefixFromLineStartToPosition(textAfterUnwrap, start)),
+			end: endAfterOptionalCommaFollowingInSource(textAfterUnwrap, anchorClassLiteral.end),
+			replacement: formatArrayElementsAsSiblingLines(groups, textPrefixFromLineStartToPosition(textAfterUnwrap, start)),
 			bucketSummary: summarizeGroupBucketLabels(groups),
 			jsxCn: false,
 			lineSf: target.item.sf,

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

@@ -42,7 +42,7 @@ function tryBuildGroupFileWorkPlan(input) {
 	if (domainSfGrouped.text !== unwrap.textAfterUnwrap) throw new Error("Domain invariant: domainSfGrouped.text must match unwrap phase textAfterUnwrap");
 	const groupTargets = collectGroupTargets(domainSfGrouped, filePath);
 	if (unwrap.cnInTvCalls.length === 0 && groupTargets.length === 0) return null;
-	const sortedTargets = [...groupTargets].sort((leftTarget, rightTarget) => targetReplaceStart(rightTarget) - targetReplaceStart(leftTarget));
+	const sortedTargets = [...groupTargets].toSorted((leftTarget, rightTarget) => targetReplaceStart(rightTarget) - targetReplaceStart(leftTarget));
 	const plannedGroupEdits = [];
 	for (const groupTarget of sortedTargets) {
 		const plan = planGroupEditForTarget(groupTarget, unwrap.textAfterUnwrap, withClassName);