@codefast/cli 0.3.12 → 0.3.13-canary.0

package/README.md

@@ -1,100 +1,255 @@
 # @codefast/cli
 
-Two tools bundled in one CLI:
+A focused CLI for two recurring maintenance tasks in monorepos:
 
-| Command       | Purpose                                                                                                                                                                             |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mirror sync` | Regenerate `package.json` `exports` from each package's built `dist/` tree (pnpm workspace packages)                                                                                |
-| `arrange`     | Analyze, dry-run, or apply suggested grouping for long Tailwind class strings inside `cn()` / `tv()` call sites (Tailwind v4–oriented heuristics), or `group` a pasted class string |
+- **`arrange`** — analyze and regroup Tailwind class strings inside `cn()` / `tv()` calls according to a consistent render-pipeline order.
+- **`mirror`** — regenerate `package.json` `exports` fields from built `dist/` trees across a pnpm workspace.
+- **`tag`** (alias: **`annotate`**) — auto-add `@since <version>` to exported TypeScript declarations that are still missing version metadata.
+
+```mermaid
+flowchart LR
+  R[codefast]
+  R --> A[arrange]
+  R --> M[mirror]
+  R --> T[tag]
+
+  A --> A0[analyze]
+  A --> A1[preview]
+  A --> A2[apply]
+  A --> A3[group]
+
+  M --> M0[sync]
+```
 
 ---
 
-## Requirements & Install
+## Requirements
+
+- Node.js `>=22.0.0`
+- pnpm (recommended)
+
+---
 
-**Node.js ≥ 24** is required.
+## Installation
 
 ```bash
-# Global
+# Install globally
 pnpm add -g @codefast/cli
 
-# Without a global install
-pnpm dlx @codefast/cli -- --help
+# Or run without installing
+pnpm dlx @codefast/cli --help
+```
+
+---
+
+## Quick start
+
+```bash
+# 1. Preview proposed changes — no files written
+codefast arrange preview packages/ui/src/components
+
+# 2. Apply after reviewing the diff
+codefast arrange apply packages/ui/src/components
+
+# 3. Regenerate package exports from built dist/
+codefast mirror sync
+
+# 4. Add @since tags to exported APIs under src/
+codefast tag
 ```
 
 ---
 
 ## `arrange`
 
-### Recommended workflow
+Reads `cn()` and `tv()` call sites, classifies each Tailwind utility, and rewrites the class strings in render-pipeline order (see [Grouping philosophy](#grouping-philosophy--render-pipeline-order) below).
+
+### Workflow
 
-1. **`analyze [target]`** — Prints a report (long strings, nested `cn` in `tv`, related notes). No files changed.
-2. **`preview [target]`** — Same transforms as `apply`, but writes nothing. Inspect stdout before touching the tree.
-3. **`apply [target]`** — Writes edits. Run `preview` first.
+Run the three subcommands in order:
 
-**Default target** (when path is omitted): `packages/ui/src/components` resolved from `process.cwd()`.
+| 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                     |
 
-### Useful options
+The default `target` when omitted is `packages/ui/src/components`, resolved from `process.cwd()`.
 
-- **`--with-class-name`** — Append `className` as the last argument to the suggested `cn(...)`.
-- **`--cn-import <spec>`** — Override the module specifier when the tool adds a `cn` import.
+### Flags
 
-### `group [tokens...]`
+| Flag                 | Description                                                             |
+| -------------------- | ----------------------------------------------------------------------- |
+| `--with-class-name`  | Append `className` as the last argument when rewriting a `cn(...)` call |
+| `--cn-import <spec>` | Override the module specifier used when adding a missing `cn` import    |
 
-No filesystem involved — paste a class string, get back a suggested `cn(...)` (or a `tv()`-style array with `--tv`) plus a short buckets summary. Use this to tune your mental model before running `analyze` on a large tree.
+### `arrange group` — one-shot string grouping
+
+Groups a single class string without touching the filesystem. Useful for checking how a string would be classified before running `apply`:
+
+```bash
+codefast arrange group "relative flex items-center h-10 w-full rounded-md bg-primary text-white hover:bg-primary/90"
+```
 
 ---
 
-## Grouping philosophy — Render Pipeline Order
+## `mirror sync`
 
-`arrange` does **not** sort alphabetically. It groups utilities in roughly the same order the browser reasons about them:
+Scans built `dist/` trees and regenerates the `exports` field in each `package.json`. Run from anywhere inside the monorepo — the workspace root is discovered automatically via `pnpm-workspace.yaml`.
 
-**Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow → Typography → Composite → Motion → Starting → Behavior → Conditions (State)**
+```bash
+codefast mirror sync              # all packages in the workspace
+codefast mirror sync packages/ui  # a single package path
+codefast mirror sync -v           # verbose output
+```
 
-Bucket breakdown:
+> **Note:** Packages must be built first so `dist/` exists. Run your build step before `mirror sync`.
+
+### Configuration
+
+Create a `codefast.config.js` (or `.mjs`, `.cjs`, `.json`) at the repo root with a `mirror` key:
+
+```js
+// codefast.config.mjs
+export default {
+  mirror: {
+    skipPackages: ["@acme/internal"],
+    pathTransformations: {
+      "@acme/ui": {
+        removePrefix: "./components/",
+      },
+    },
+    customExports: {
+      "@acme/ui": {
+        "./css/*": "./src/styles/*",
+      },
+    },
+    cssExports: {
+      "@acme/ui": {
+        enabled: true,
+        customExports: {
+          "./tokens.css": "./dist/tokens.css",
+        },
+      },
+    },
+  },
+};
+```
 
-| Bucket         | What it covers                                    | Examples                                          |
-| -------------- | ------------------------------------------------- | ------------------------------------------------- |
-| **Existence**  | Display / containment context                     | `hidden`, `block`, `@container`, `group`, `peer`  |
-| **Position**   | Where the box sits                                | `absolute`, `inset-*`, `top-*`, `z-*`             |
-| **Layout**     | How children flow                                 | `flex`, `grid`, `gap-*`, `items-*`                |
-| **Sizing**     | Box dimensions and overflow                       | `w-*`, `h-*`, `aspect-*`, `overflow-*`            |
-| **Spacing**    | Padding and margin only (gaps stay with Layout)   | `p-*`, `m-*`                                      |
-| **Shape**      | Corners and strokes                               | `rounded-*`, `border-*`, `ring-*`                 |
-| **Background** | Surfaces and masks                                | `bg-*`, `from-*`, `via-*`, `to-*`, `mask-*`       |
-| **Shadow**     | Depth                                             | `shadow-*`, `inset-shadow-*`, `text-shadow-*`     |
-| **Typography** | Text appearance                                   | `font-*`, `text-*`, `leading-*`                   |
-| **Composite**  | Layers and transforms — 3D context → 3D → 2D      | `opacity-*`, `rotate-x-*`, `translate-*`          |
-| **Motion**     | Time-based change                                 | `transition-*`, `animate-*`                       |
-| **Starting**   | Tailwind's `starting:` layer, kept next to Motion | `starting:*`                                      |
-| **Behavior**   | Input / scrolling / chrome                        | `cursor-*`, `scroll-*`, `field-sizing-*`, `inert` |
-| **State**      | Everything with a variant stack                   | `hover:`, `md:`, `@md/sidebar:`, `data-[…]:`      |
+Use your real package names from `package.json#name` (for example `@acme/ui`) and adjust entries to match your workspace.
 
-Some adjacent buckets may be merged into one string literal when declared _compatible_ (e.g. `layout` + `sizing`) — keeps `cn()` readable without flattening unrelated concerns.
+> **Migration:** Path-based keys (for example `packages/ui`) are deprecated for `pathTransformations`, `customExports`, `cssExports`, and `skipPackages`. Migrate to package-name keys.
 
-To change a placement, edit `classifyBareUtility` in `src/lib/arrange/tokenizer.ts` and add a `classifyToken` test in `src/lib/arrange.test.ts`.
+> **Security note:** `.js`, `.mjs`, and `.cjs` config files are loaded via `import()`. Only run `mirror sync` in repositories you trust.
 
 ---
 
-## `mirror sync`
+## Lifecycle hooks (`codefast.config.mjs`)
+
+`codefast` supports lifecycle hooks so teams can plug in their own post-write workflow (formatter, lint-fix, codemods) without hardcoding any formatter inside CLI core.
+
+```javascript
+import { execSync } from "node:child_process";
+
+export default {
+  tag: {
+    onAfterWrite: ({ files }) => {
+      console.log(`Formatting ${files.length} files with Oxc...`);
+      execSync(`npx oxc format ${files.join(" ")}`, { stdio: "inherit" });
+    },
+  },
+  arrange: {
+    onAfterWrite: ({ files }) => {
+      execSync(`npx oxc format ${files.join(" ")}`, { stdio: "inherit" });
+    },
+  },
+};
+```
+
+Hook contract:
+
+- `tag.onAfterWrite?.({ files })` runs after `codefast tag` writes files.
+- `arrange.onAfterWrite?.({ files })` runs after `codefast arrange apply` writes files.
+- Hooks support both sync and async functions (`void | Promise<void>`).
+- Hook errors are logged but do not crash the CLI process.
+
+---
+
+## `tag` / `annotate`
 
-Run from anywhere under the monorepo — the CLI finds the root via `pnpm-workspace.yaml`.
+Scans `.ts` / `.tsx` source files and annotates exported declarations with `@since <current-package-version>`. This keeps API evolution visible and reduces documentation drift in long-lived codebases.
 
 ```bash
-codefast mirror sync              # All workspace packages
-codefast mirror sync packages/ui  # One package only
-codefast mirror sync -v           # Verbose
+codefast tag                  # annotate exports in ./src
+codefast tag packages/ui/src  # annotate a custom target
+codefast annotate --dry-run   # preview only, do not write files
 ```
 
-**Config:** Place `codefast.config.js` (or `.mjs` / `.cjs` / `.json`) at repo root with a `mirror` object (`skipPackages`, `pathTransformations`, `customExports`, …).
+What it updates:
 
-> ⚠️ `.js`/`.mjs`/`.cjs` config files are loaded via `import()` — only run `mirror sync` in repositories you trust.
+- Adds `/** @since <version> */` when an exported declaration has no JSDoc.
+- Injects `@since <version>` into an existing JSDoc block when missing.
+- Leaves declarations unchanged when `@since` is already present.
+
+The `<version>` value is read from the nearest `package.json` found by walking up from the target path.
 
 ---
 
-## Developing inside this monorepo
+## Grouping philosophy — Render Pipeline Order
+
+`arrange` does **not** sort classes alphabetically. Instead, it groups utilities in roughly the order the browser applies them — from the box's existence, through its shape and surface, to interactive behavior. This makes class strings easier to scan and reason about at a glance.
+
+**Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow → Typography → Composite → Motion → Starting → Behavior → State → Selector**
+
+| Bucket         | What it covers                                      | Examples                                          |
+| -------------- | --------------------------------------------------- | ------------------------------------------------- |
+| **Existence**  | Display and containment context                     | `hidden`, `block`, `@container`, `group`, `peer`  |
+| **Position**   | Where the box sits                                  | `absolute`, `inset-*`, `top-*`, `z-*`             |
+| **Layout**     | How children flow                                   | `flex`, `grid`, `gap-*`, `items-*`                |
+| **Sizing**     | Box dimensions and overflow                         | `w-*`, `h-*`, `aspect-*`, `overflow-*`            |
+| **Spacing**    | Padding and margin only (gaps stay with Layout)     | `p-*`, `m-*`                                      |
+| **Shape**      | Corners and strokes                                 | `rounded-*`, `border-*`, `ring-*`                 |
+| **Background** | Surfaces and masks                                  | `bg-*`, `from-*`, `via-*`, `to-*`, `mask-*`       |
+| **Shadow**     | Depth                                               | `shadow-*`, `inset-shadow-*`, `text-shadow-*`     |
+| **Typography** | Text appearance                                     | `font-*`, `text-*`, `leading-*`                   |
+| **Composite**  | Layers and transforms (3D context → 3D → 2D)        | `opacity-*`, `rotate-x-*`, `translate-*`          |
+| **Motion**     | Time-based change                                   | `transition-*`, `animate-*`                       |
+| **Starting**   | Tailwind's `starting:` layer — kept next to Motion  | `starting:*`                                      |
+| **Behavior**   | Input, scrolling, and browser chrome                | `cursor-*`, `scroll-*`, `field-sizing-*`, `inert` |
+| **State**      | Interactive and conditional variants (non-selector) | `hover:`, `md:`, `@md/sidebar:`, `data-[…]:`      |
+| **Selector**   | Selector-driven variants                            | `[&…]:`, `*:`, `**:`, `has-*`, `group-[…]:`       |
+
+Adjacent buckets may be merged into one string literal when declared _compatible_ (e.g. `layout` + `sizing`). This keeps `cn()` calls readable without flattening unrelated concerns into a single undifferentiated blob.
+
+To change a placement, edit `classifyBareUtility` in `src/lib/arrange/tokenizer.ts` and add a corresponding `classifyToken` test in `src/lib/arrange.test.ts`.
+
+---
+
+## Troubleshooting
+
+**`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 before syncing. Ensure `dist/` exists by running your build step first, then re-run `codefast mirror sync`.
+
+**Unexpected class reorder after `arrange apply`**
+Run `arrange preview` before applying and smoke-test the UI. Some components rely on cascade-sensitive ordering that `arrange` cannot detect automatically.
+
+---
+
+## Contributing (monorepo setup)
 
 ```bash
+# Build the local CLI (produces dist/bin.js)
+pnpm --filter @codefast/cli build
+
+# Run the local entrypoint
 pnpm exec codefast --help
 ```
 
-Root `package.json` defines optional `cli:*` scripts (e.g. `cli:mirror-sync`, `cli:arrange-analyze`) as thin wrappers around `pnpm exec codefast …`.
+A few naming conventions to keep in mind:
+
+- **`codefast <command>`** refers to CLI commands exposed via the `@codefast/cli` `bin` entry.
+- **Scripts in `packages/cli/package.json`** (`build`, `test`, …) are package-local dev scripts, not CLI commands.
+- The root `package.json` includes optional convenience wrappers such as `cli:mirror-sync` and `cli:arrange-analyze` for common dev workflows.

package/dist/analyze-DvtJ3j9m.mjs

@@ -0,0 +1,92 @@
+import "./constants-AtPhF-Ct.mjs";
+import { d as tokenizeClassString } from "./tokenizer-CeZx73Zu.mjs";
+import { r as forEachStringLiteralInClassExpression } from "./collectors-cn-BS8TTQ8O.mjs";
+import { t as jsxClassNameStaticLiteral } from "./collectors-jsx-D9tL2ZPM.mjs";
+import { a as isCnOrTvIdentifier, o as lineOf, r as buildKnownCnTvBindings } from "./ast-helpers-MDRYuIAk.mjs";
+import { c as traverseTvObject, t as collectCnCallsInsideTv } from "./collectors-tv-D2PXZaRt.mjs";
+import { n as walkTsxFiles } from "./walk-DjgQn66n.mjs";
+import ts from "typescript";
+//#region src/lib/arrange/application/analyze.ts
+function analyzeCnCall(sf, call, report) {
+	for (const arg of call.arguments) forEachStringLiteralInClassExpression(arg, (lit) => {
+		const text = lit.text;
+		const tokenCount = tokenizeClassString(text).length;
+		if (tokenCount >= 18) report.longCnStringLiterals.push({
+			file: sf.fileName,
+			line: lineOf(sf, lit),
+			tokenCount,
+			preview: text.length > 72 ? `${text.slice(0, 72)}…` : text
+		});
+	});
+}
+function visitCallExpressionForArrangeAnalyze(callExpression, sf, sourceText, knownBindings, report) {
+	if (isCnOrTvIdentifier(callExpression.expression, "cn", knownBindings)) {
+		report.cnCallExpressions++;
+		analyzeCnCall(sf, callExpression, report);
+		return;
+	}
+	if (!isCnOrTvIdentifier(callExpression.expression, "tv", knownBindings)) return;
+	report.tvCallExpressions++;
+	const arg0 = callExpression.arguments[0];
+	if (!arg0 || !ts.isObjectLiteralExpression(arg0)) return;
+	for (const nestedCn of collectCnCallsInsideTv(sf, arg0, knownBindings, 0)) {
+		const src = sourceText.slice(nestedCn.getStart(sf), nestedCn.getEnd());
+		const preview = src.length > 72 ? `${src.slice(0, 72)}…` : src;
+		report.cnInsideTvCalls.push({
+			file: sf.fileName,
+			line: lineOf(sf, nestedCn),
+			argCount: nestedCn.arguments.length,
+			preview
+		});
+	}
+	traverseTvObject(sf, arg0, (classLiteral) => {
+		const text = classLiteral.text;
+		const tokenCount = tokenizeClassString(text).length;
+		if (tokenCount >= 18) report.longTvStringLiterals.push({
+			file: sf.fileName,
+			line: lineOf(sf, classLiteral),
+			tokenCount,
+			preview: text.length > 72 ? `${text.slice(0, 72)}…` : text
+		});
+	}, 0, knownBindings);
+}
+function visitJsxAttributeForArrangeAnalyze(jsxClassAttribute, sf, filePath, report) {
+	if (!filePath.endsWith(".tsx")) return;
+	const parsed = jsxClassNameStaticLiteral(jsxClassAttribute);
+	if (!parsed) return;
+	const text = parsed.lit.text;
+	const tokenCount = tokenizeClassString(text).length;
+	if (tokenCount >= 18) report.longJsxClassNameLiterals.push({
+		file: sf.fileName,
+		line: lineOf(sf, parsed.lit),
+		tokenCount,
+		preview: text.length > 72 ? `${text.slice(0, 72)}…` : text
+	});
+}
+function analyzeDirectory(analyzeRootPath, fs) {
+	const report = {
+		files: 0,
+		cnCallExpressions: 0,
+		tvCallExpressions: 0,
+		cnInsideTvCalls: [],
+		longCnStringLiterals: [],
+		longTvStringLiterals: [],
+		longJsxClassNameLiterals: []
+	};
+	const files = fs.statSync(analyzeRootPath).isDirectory() ? walkTsxFiles(analyzeRootPath, fs) : [analyzeRootPath];
+	for (const filePath of files) {
+		const sourceText = fs.readFileSync(filePath, "utf8");
+		const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+		report.files++;
+		const knownBindings = buildKnownCnTvBindings(sf);
+		const visitTypeScriptSubtree = (tsNode) => {
+			if (ts.isCallExpression(tsNode)) visitCallExpressionForArrangeAnalyze(tsNode, sf, sourceText, knownBindings, report);
+			if (ts.isJsxAttribute(tsNode)) visitJsxAttributeForArrangeAnalyze(tsNode, sf, filePath, report);
+			ts.forEachChild(tsNode, visitTypeScriptSubtree);
+		};
+		visitTypeScriptSubtree(sf);
+	}
+	return report;
+}
+//#endregion
+export { analyzeDirectory as t };

package/dist/arrange-Bbh62DrU.mjs

@@ -0,0 +1,107 @@
+import { t as messageFromCaughtUnknown } from "./caught-unknown-message-CRhkDWO7.mjs";
+import { t as loadConfig } from "./loader-DpN-zl5g.mjs";
+import "./config-DVia_f9a.mjs";
+import { t as printConfigSchemaWarnings } from "./config-reporter-SCcWDZc1.mjs";
+import { i as DEFAULT_ARRANGE_TARGET } from "./constants-AtPhF-Ct.mjs";
+import { t as analyzeDirectory } from "./analyze-DvtJ3j9m.mjs";
+import { t as printAnalyzeReport } from "./report-DYxvw34T.mjs";
+import { a as suggestCnGroups, o as summarizeGroupBucketLabels } from "./grouping-c1grpCQT.mjs";
+import { i as formatCnCall, n as formatArray } from "./formatters-DGE8jJ53.mjs";
+import { t as runArrangeSync } from "./run-target-CJWrqNT4.mjs";
+import { n as createNodeCliLogger, t as createNodeCliFs } from "./node-io-DFRbHO6m.mjs";
+import "./arrange-BqP2DI3w.mjs";
+import { t as findRepoRoot } from "./repo-root-HmtIEm6J.mjs";
+import process from "node:process";
+import path from "node:path";
+import { Option } from "commander";
+//#region src/commands/arrange.ts
+/** Commander attribute `withClassName` (second long flag `--with-class-name`). */
+function createWithClassNameOption() {
+	return new Option("--with-classname, --with-class-name", "Append className as final cn() argument").default(false);
+}
+function defaultTargetPath() {
+	return path.resolve(process.cwd(), DEFAULT_ARRANGE_TARGET);
+}
+function checkTargetExists(resolved, fs, logger) {
+	if (!fs.existsSync(resolved)) {
+		logger.err(`Not found: ${resolved}`);
+		process.exitCode = 1;
+		return false;
+	}
+	return true;
+}
+async function loadArrangeCommandConfig(fs, logger, rootDir) {
+	try {
+		const { config, warnings } = await loadConfig(fs, rootDir);
+		printConfigSchemaWarnings(logger, warnings);
+		return { arrangeConfig: config.arrange ?? {} };
+	} catch (caughtConfigError) {
+		logger.err(messageFromCaughtUnknown(caughtConfigError));
+		process.exitCode = 1;
+		return;
+	}
+}
+function registerArrangeCommand(program) {
+	const arrange = program.command("arrange").description("Analyze and regroup Tailwind classes in cn() / tv() calls (Tailwind v4)");
+	arrange.command("analyze").description("Report long strings, nested cn in tv(), and related findings").argument("[target]", "Directory or file (default: packages/ui/src/components)").action(async (target) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const resolved = target ? path.resolve(target) : defaultTargetPath();
+		if (!checkTargetExists(resolved, fs, logger)) return;
+		if (!await loadArrangeCommandConfig(fs, logger, findRepoRoot(fs))) return;
+		printAnalyzeReport(resolved, analyzeDirectory(resolved, fs), logger);
+	});
+	arrange.command("preview").description("Dry-run: print suggested replacements without writing files").argument("[target]", "Directory or file (default: packages/ui/src/components)").addOption(createWithClassNameOption()).option("--cn-import <spec>", "Override module specifier when adding cn import").action(async (target, opts) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const resolved = target ? path.resolve(target) : defaultTargetPath();
+		if (!checkTargetExists(resolved, fs, logger)) return;
+		const rootDir = findRepoRoot(fs);
+		const loaded = await loadArrangeCommandConfig(fs, logger, rootDir);
+		if (!loaded) return;
+		process.exitCode = await runArrangeSync({
+			rootDir,
+			config: loaded.arrangeConfig,
+			targetPath: resolved,
+			write: false,
+			withClassName: opts.withClassName,
+			cnImport: opts.cnImport,
+			fs,
+			logger
+		});
+	});
+	arrange.command("apply").description("Apply grouping and cn-in-tv unwrap edits to files").argument("[target]", "Directory or file (default: packages/ui/src/components)").addOption(createWithClassNameOption()).option("--cn-import <spec>", "Override module specifier when adding cn import").action(async (target, opts) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const resolved = target ? path.resolve(target) : defaultTargetPath();
+		if (!checkTargetExists(resolved, fs, logger)) return;
+		const rootDir = findRepoRoot(fs);
+		const loaded = await loadArrangeCommandConfig(fs, logger, rootDir);
+		if (!loaded) return;
+		process.exitCode = await runArrangeSync({
+			rootDir,
+			config: loaded.arrangeConfig,
+			targetPath: resolved,
+			write: true,
+			withClassName: opts.withClassName,
+			cnImport: opts.cnImport,
+			fs,
+			logger
+		});
+	});
+	arrange.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).addOption(createWithClassNameOption()).action((tokens, opts) => {
+		const inlineClasses = tokens.join(" ").trim();
+		if (!inlineClasses) {
+			process.stderr.write("Pass a class string. Example: codefast arrange group \"flex gap-2 text-sm rounded-md\"\n");
+			process.exitCode = 1;
+			return;
+		}
+		const groups = suggestCnGroups(inlineClasses);
+		const result = opts.tv ? formatArray(groups) : formatCnCall(groups, { trailingClassName: !!opts.withClassName });
+		process.stdout.write(`${result}\n`);
+		const bucketSummary = summarizeGroupBucketLabels(groups);
+		process.stdout.write(`\n// Buckets: ${JSON.stringify(bucketSummary)}\n`);
+	});
+}
+//#endregion
+export { registerArrangeCommand as t };

package/dist/arrange-BqP2DI3w.mjs

@@ -0,0 +1,8 @@
+import "./collectors-cn-BS8TTQ8O.mjs";
+import "./ast-helpers-MDRYuIAk.mjs";
+import "./analyze-DvtJ3j9m.mjs";
+import "./formatters-DGE8jJ53.mjs";
+import "./imports-DSVq1xhB.mjs";
+import "./group-file-ClW7XdD6.mjs";
+import "./run-target-CJWrqNT4.mjs";
+export {};

package/dist/ast-helpers-MDRYuIAk.mjs

@@ -0,0 +1,115 @@
+import { a as EMPTY_CN_TV_BINDINGS } from "./constants-AtPhF-Ct.mjs";
+import ts from "typescript";
+//#region src/lib/arrange/domain/ast/ast-helpers.ts
+/** Known module specifiers that export `cn` / `tv`. */
+const KNOWN_CN_TV_MODULES = new Set([
+	"@codefast/tailwind-variants",
+	"clsx",
+	"class-variance-authority",
+	"tailwind-variants",
+	"#lib/utils",
+	"~/lib/utils",
+	"@/lib/utils"
+]);
+/**
+* True for typical shadcn-style re-exports: `./utils`, `@/lib/utils`, `…/utils/…`,
+* or a dedicated `cn.ts` / `cn.tsx` module.
+*/
+function moduleLooksLikeCnTvReexport(moduleSpecifier) {
+	const norm = moduleSpecifier.replace(/\\/g, "/");
+	if (/(?:^|[./])utils(?:\/|$)/.test(norm)) return true;
+	if (/\/utils\//.test(norm) || /\/utils$/.test(norm)) return true;
+	if (/(?:^|\/)cn\.tsx?$/.test(norm)) return true;
+	return false;
+}
+/**
+* Build a set of local binding names that are imported from a known cn/tv
+* module in `sf`.
+*/
+function buildKnownCnTvBindings(sf) {
+	const bindings = /* @__PURE__ */ new Set();
+	for (const stmt of sf.statements) {
+		if (!ts.isImportDeclaration(stmt) || !stmt.importClause) continue;
+		if (stmt.importClause.isTypeOnly) continue;
+		const spec = stmt.moduleSpecifier;
+		if (!ts.isStringLiteral(spec)) continue;
+		const moduleSpecifier = spec.text;
+		if (!KNOWN_CN_TV_MODULES.has(moduleSpecifier) && !moduleLooksLikeCnTvReexport(moduleSpecifier)) continue;
+		const clause = stmt.importClause;
+		if (clause.name) bindings.add(clause.name.text);
+		if (!clause.namedBindings) continue;
+		if (ts.isNamedImports(clause.namedBindings)) {
+			for (const namedImport of clause.namedBindings.elements) bindings.add(namedImport.name.text);
+			continue;
+		}
+		bindings.add(clause.namedBindings.name.text);
+	}
+	return bindings;
+}
+/**
+* Returns true when `expr` is an identifier whose name matches `name` AND
+* that name is listed in `knownBindings` from a recognized import.
+*/
+function isCnOrTvIdentifier(expr, name, knownBindings = EMPTY_CN_TV_BINDINGS) {
+	if (knownBindings.size === 0) return false;
+	if (ts.isIdentifier(expr) && expr.text === name) return knownBindings.has(expr.text);
+	if (ts.isPropertyAccessExpression(expr) && expr.name.text === name) return ts.isIdentifier(expr.expression) && knownBindings.has(expr.expression.text);
+	return false;
+}
+function propertyAssignmentNameText(prop) {
+	if (ts.isIdentifier(prop.name)) return prop.name.text;
+	if (ts.isStringLiteral(prop.name)) return prop.name.text;
+}
+function lineOf(sf, tsNode) {
+	return sf.getLineAndCharacterOfPosition(tsNode.getStart(sf)).line + 1;
+}
+/**
+* Returns only the leading whitespace (tabs / spaces) of the line containing
+* `pos`.
+*/
+function indentOfLineContaining(source, pos) {
+	const searchPos = Math.max(0, Math.min(pos, source.length));
+	const prevLineBreak = Math.max(source.lastIndexOf("\n", searchPos - 1), source.lastIndexOf("\r", searchPos - 1));
+	const lineStart = prevLineBreak === -1 ? 0 : prevLineBreak + 1;
+	let lineEnd = source.length;
+	for (let i = lineStart; i < source.length; i++) {
+		const ch = source[i];
+		if (ch === "\n" || ch === "\r") {
+			lineEnd = i;
+			break;
+		}
+	}
+	const line = source.slice(lineStart, lineEnd);
+	return /^[\t ]*/.exec(line)?.[0] ?? "";
+}
+function applyEditsDescending(sourceText, edits) {
+	const sorted = [...edits].sort((editA, editB) => editB.start - editA.start);
+	let out = sourceText;
+	for (const edit of sorted) out = out.slice(0, edit.start) + edit.replacement + out.slice(edit.end);
+	return out;
+}
+/**
+* Replace `cn(...)` nested in `tv({...})` with a plain string (one arg) or a string
+* array (multiple args). Returns undefined when there are zero arguments.
+*/
+function unwrapCnInsideTvCallReplacement(call, sourceText, sf) {
+	const args = call.arguments;
+	if (args.length === 0) return void 0;
+	const baseIndent = indentOfLineContaining(sourceText, call.getStart(sf));
+	const innerIndent = `${baseIndent}  `;
+	if (args.length === 1) {
+		const firstArg = args[0];
+		return sourceText.slice(firstArg.getStart(sf), firstArg.getEnd());
+	}
+	const lines = ["["];
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		const piece = sourceText.slice(arg.getStart(sf), arg.getEnd());
+		const comma = i < args.length - 1 || args.length > 1 ? "," : "";
+		lines.push(`${innerIndent}${piece}${comma}`);
+	}
+	lines.push(`${baseIndent}]`);
+	return lines.join("\n");
+}
+//#endregion
+export { isCnOrTvIdentifier as a, propertyAssignmentNameText as c, indentOfLineContaining as i, unwrapCnInsideTvCallReplacement as l, applyEditsDescending as n, lineOf as o, buildKnownCnTvBindings as r, moduleLooksLikeCnTvReexport as s, KNOWN_CN_TV_MODULES as t };

package/dist/{bin.js → bin.mjs}

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
+import { n as runCli } from "./program-DR-H4tH3.mjs";
 import process from "node:process";
-import { runCli } from "#program";
+//#region src/bin.ts
 const code = await runCli(process.argv);
 process.exit(code);
+//#endregion
+export {};

package/dist/caught-unknown-message-CRhkDWO7.mjs

@@ -0,0 +1,20 @@
+//#region src/lib/infra/caught-unknown-message.ts
+/**
+* Stable, user-facing text for values caught as `unknown`.
+* Avoids `String(unknown)` / `[object Object]` and satisfies strict `no-base-to-string`.
+*/
+function messageFromCaughtUnknown(value) {
+	if (value instanceof Error) return value.message;
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return String(value);
+	if (typeof value === "symbol") return String(value);
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	try {
+		const serialized = JSON.stringify(value);
+		if (typeof serialized === "string") return serialized;
+	} catch {}
+	return "[unserializable non-Error value]";
+}
+//#endregion
+export { messageFromCaughtUnknown as t };