@codefast/cli 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @codefast/cli
 
+## 0.12.0
+
+### Minor Changes
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Add `codefast audit publish`, a static publish-surface check. It flags `#/`-prefixed internal import specifiers — valid
+  to the in-repo runners but rejected by Node's ESM resolver on the supported floor, so they break the published package —
+  and any `exports`/`imports` target the slimmed publish manifest would not ship. It joins the `audit` family and gates
+  CI, replacing an external `publint` step.
+
+### Patch Changes
+
+- [#885](https://github.com/codefastlabs/codefast/pull/885) [`8580a2b`](https://github.com/codefastlabs/codefast/commit/8580a2b2dd9f502d7c330e5a2f0a3942041633b6) Thanks [@thevuong](https://github.com/thevuong)! - Match GitHub's heading-slug algorithm in `audit links`, so a cross-reference that resolves on GitHub resolves in the
+  audit.
+
+  Heading anchors are now slugged the way GitHub does: each space becomes its own hyphen with runs left intact,
+  underscores are kept as slug characters, and repeated headings gain `-1`, `-2`, … suffixes in heading order. The
+  previous slugger collapsed whitespace, dropped underscores, and offered only the base slug for duplicates, so a link a
+  browser lands on could be reported as dangling — the `@remarks` already claimed GitHub parity the code did not deliver.
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Lower the monorepo's Node floor from 24 to 22.12, so the packages install and run on the active Node 22 LTS line.
+
+  `engines.node` becomes `>=22.12.0` across every package — the floor the shared toolchain (oxlint, Vite, Vitest, TanStack
+  Start) already requires. Development stays on the latest Node (`.node-version`) for speed, and a CI matrix exercises the
+  floor and the active LTS directly, so the floor is a contract CI proves rather than one everyone has to run.
+  `@types/node` is pinned to the floor's major (`^22`), with a workspace override holding the whole tree there so a dev
+  tool's `@types/node: "*"` peer can no longer pull a newer major and mask an API the floor lacks. The floor stays
+  mechanical, not advisory: `@codefast/di` keeps its own `Map` upsert helpers rather than the ES2025
+  `Map.prototype.getOrInsert` (which would raise the floor to 26) and its `lib` stays `ES2024`. `@codefast/cli`'s mirror
+  step now calls the `node:path` functions directly instead of aliasing them, which the floor's types correctly flag as
+  unbound methods.
+
+  The shared `@codefast/typescript-config` presets pin `lib` and `target` to `ES2024` (was `ESNext`) so the compiler's
+  ECMAScript surface matches the Node floor: an ES2025 builtin such as `Map.prototype.getOrInsert` now fails to type-check
+  rather than compiling and crashing on Node 22.12. `@codefast/di` and `@codefast/di-testing` already pinned `lib` and are
+  unchanged.
+
+  Internal subpath imports move from a `#/` prefix to a bare `#` (`#core/token`, not `#/core/token`), and the
+  `package.json#imports` keys become `#*`/`#tests/*`/`#examples/*` to match. Node's native ESM resolver rejects a
+  `#/`-prefixed specifier with `ERR_INVALID_MODULE_SPECIFIER` on the whole Node 22 line (and on Node 24 before 24.14), and
+  each package ships those specifiers verbatim inside its published `dist/*.js` for a consumer's Node to resolve — so this
+  rename is what actually lets the packages import on the new floor. Purely internal: a consumer's own import paths are
+  unchanged.
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Fix `pack-slim` stripping the stylesheet source of packages that export CSS.
+
+  `codefast pack-slim` removed the whole `src` directory from a package's published `files`, but `@codefast/ui` and
+  `@codefast/tracking` ship Tailwind source through `./css/*` → `./src/css/*`, so their published tarballs went out with
+  no CSS at all and the `./css/*` export resolved to nothing. pack-slim now keeps the `src` subtrees a surviving
+  `exports`/`imports` target still points into (e.g. `src/css`) and drops the rest of `src`, so the stylesheets ship while
+  the TypeScript source stays out. Surfaced and now guarded by the new `codefast audit publish` check.
+
+## 0.11.0
+
+### Minor Changes
+
+- [#855](https://github.com/codefastlabs/codefast/pull/855) [`76cf7a6`](https://github.com/codefastlabs/codefast/commit/76cf7a65372c5f13f779c7b59200cb956d93b882) Thanks [@thevuong](https://github.com/thevuong)! - Fix `codefast arrange simplify` changing rendered output: a mixed `cn()` call moved every static literal to the front,
+  which flipped tailwind-merge precedence and dropped overrides that sat after a variant call. It now coalesces only
+  adjacent static literals and preserves argument order.
+
+  Add `codefast arrange simplify --fold-variant-classname` (alias `--fold-variant-class-name`), which folds
+  `cn(buttonVariants({ size: "sm" }), "flex-1")` into `buttonVariants({ size: "sm", className: "flex-1" })`. The fold is
+  gated on the native TypeScript type server confirming the callee accepts a `className`/`class`, so it loads the
+  `typescript` package (a new optional peer, v7) and applies only inside a `tsconfig`; the default pass is unchanged.
+
+  The fold splices `className` in after the last option, so a trailing comma or line comment in the options object no
+  longer breaks the rewrite. Overlapping edits are now resolved before they are applied — keeping the outermost of any
+  nested `cn()`/variant pair — so nested calls no longer corrupt the output.
+
+- [#854](https://github.com/codefastlabs/codefast/pull/854) [`a7ad2d8`](https://github.com/codefastlabs/codefast/commit/a7ad2d8b24b10b5554a5809be943aca00e22e844) Thanks [@thevuong](https://github.com/thevuong)! - `codefast audit imports` now enforces the Zod namespace form (`import * as z from "zod"`) in every workspace package,
+  not only the front-end/bundled ones. The rule's `scope` restriction is dropped, so a named `import { z } from "zod"` is
+  flagged everywhere — backend/tsc packages such as `cli` itself included. Type-only imports
+  (`import type { ZodType } from "zod"`) stay allowed; only the value `z` is banned.
+
+### Patch Changes
+
+- [#855](https://github.com/codefastlabs/codefast/pull/855) [`9e481c5`](https://github.com/codefastlabs/codefast/commit/9e481c554b7f60216b130495fd157fe3a459721e) Thanks [@thevuong](https://github.com/thevuong)! - Fix `codefast arrange --dry-run --json` printing human-readable preview lines to stdout ahead of the JSON summary, which
+  broke piping the output to a JSON parser. Dry-run previews are now emitted only in human mode; `--json` writes a single
+  JSON object.
+
+- [#854](https://github.com/codefastlabs/codefast/pull/854) [`504a61a`](https://github.com/codefastlabs/codefast/commit/504a61a996684fbd4fb6703141612d3cd97dbfde) Thanks [@thevuong](https://github.com/thevuong)! - Reorganize the CLI source into a uniform per-command and per-subcommand directory layout. Each command follows one
+  skeleton (`command.ts`, `cli-schema.ts`, `prepare.ts`, `run*.ts`, `output.ts`, `cli-result.ts`, `domain/`), and every
+  `audit`/`arrange` subcommand is now its own mini-command directory (`audit/rtl/`, `arrange/inspect/`, …) with the shared
+  runner and grouping engine kept at the command root. Internal refactor only — no public API or behavior change.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -16,13 +16,13 @@ encode an opinionated house style (called out below) that you can adopt, ignore,
 
 - **Safe by default.** Every writing command supports `--dry-run`, and every audit is read-only except
   `audit comments --fix`.
-- **Scriptable.** `--json` prints one JSON object on stdout and suppresses the human progress output.
+- **Scriptable.** `--json` prints one JSON object on stdout instead of the human-readable output.
 - **CI-ready.** Audits exit non-zero when findings remain, so they gate a pipeline with no extra glue.
 - **Configurable.** An optional `codefast.config.*` file, validated by a strict schema, adjusts every command.
 
 ## Requirements
 
-- **Node.js ≥ 24** (the CLI is published as ESM).
+- **Node.js ≥ 22.12** (the CLI is published as ESM).
 - **A project root — workspace or single package.** Commands resolve their root by walking up from the current
   directory: the nearest `pnpm-workspace.yaml` marks a **workspace** (every package under it is in scope), and with no
   workspace file the nearest `package.json` marks a **single package** (that one package is the whole scope). Only
@@ -75,22 +75,72 @@ codefast audit links                               # find broken markdown cross-
   `codefast mirror --no-color`.
 - **Writing commands write by default; pass `--dry-run` to preview.** The audits are read-only — the one exception is
   `audit comments --fix`, which repairs section dividers in place.
-- **`--json` prints a single JSON object on stdout** and suppresses the human-readable progress output, so any command
-  can gate a script or a CI job.
+- **`--json` prints a single JSON object on stdout** instead of the human-readable output, so any command can gate a
+  script or a CI job.
+- **Set `CODEFAST_VERBOSE=1` (or `true`) for verbose error diagnostics.** On an unexpected infrastructure failure the
+  CLI also prints the underlying stack trace. This is distinct from `mirror --verbose`, which adds per-package progress
+  detail to that one command.
 
 ## Commands at a glance
 
+```text
+codefast                              # Codefast monorepo developer CLI
+│  ├─ --no-color                      # disable ANSI color output
+│  └─ --version
+│
+├─ arrange [target]                   # regroup Tailwind classes in cn()/tv() in render-pipeline order
+│  │   ├─ --dry-run                   # preview, without writing files
+│  │   ├─ --with-class-name           # append className as the final cn() argument (alias: --with-classname)
+│  │   ├─ --cn-import <spec>          # override the module specifier when adding a cn import
+│  │   └─ --json
+│  │
+│  ├─ inspect [target]                # report long strings, cn nested in tv() (read-only)
+│  │   └─ --json
+│  ├─ simplify [target]               # flatten grouped arrays & static cn() to plain strings in tv() slots
+│  │   ├─ --dry-run
+│  │   └─ --fold-variant-class-name   # fold cn() overrides into the variant's className option (uses the TS type server)
+│  └─ group <tokens...>               # group a pasted class string (stdout: cn(...) or a tv() array with --tv)
+│      ├─ --tv                        # emit a tv()-style array instead of a cn() call
+│      ├─ --with-class-name
+│      └─ --json
+│
+├─ audit                              # source audits (read-only source scans)
+│  ├─ rtl [target]                    # physical-direction Tailwind classes to make logical / rtl:-paired
+│  ├─ links [target]                  # markdown links pointing at a missing path/anchor
+│  ├─ imports [target]                # banned import forms (React by-name, Zod namespace in front-end, …)
+│  ├─ display-names [target]          # token()/tag()/module names breaking the <namespace>:<Name> convention
+│  └─ comments [target]               # section dividers not in the one allowed form
+│      └─ --fix                       # rewrite every fixable divider in place (the only audit that writes)
+│      (each audit also takes [target] + --json)
+│
+├─ mirror [package]                   # write package.json#exports from dist/ for workspace packages
+│  ├─ --dry-run
+│  ├─ -v, --verbose
+│  └─ --json
+│
+├─ pack-slim [package]                # strip src, source conditions, dev-only scripts/devDeps, source maps before publish
+│  ├─ --dry-run
+│  ├─ --force                         # run even if the git working tree has uncommitted changes
+│  └─ --json
+│
+└─ tag [target]                       # add @since <version> to exported declarations
+   ├─ --dry-run
+   └─ --json
+```
+
+Every command also responds to `--help`; each command's section below explains what its flags do.
+
 | Command               | What it does                                                               | Writes?           |
 | --------------------- | -------------------------------------------------------------------------- | ----------------- |
 | `arrange`             | Regroup Tailwind classes in `cn()` / `tv()` calls in render-pipeline order | yes (`--dry-run`) |
 | `mirror`              | Write each package's `package.json#exports` from its built `dist/`         | yes (`--dry-run`) |
 | `pack-slim`           | Strip the dev-only surface from a package right before publish             | yes (`--dry-run`) |
 | `tag`                 | Stamp `@since <version>` on exported declarations that lack one            | yes (`--dry-run`) |
-| `audit links`         | Report markdown cross-references that resolve to nothing                   | no                |
 | `audit rtl`           | Report physical-direction Tailwind classes that should be logical          | no                |
+| `audit links`         | Report markdown cross-references that resolve to nothing                   | no                |
 | `audit imports`       | Enforce the import policy (React by-name, Zod namespace in front-end)      | no (report only)  |
-| `audit comments`      | Check doc-comment conventions; repair section dividers                     | `--fix` only      |
 | `audit display-names` | Enforce the `namespace:Name` display-name convention                       | no                |
+| `audit comments`      | Check doc-comment conventions; repair section dividers                     | `--fix` only      |
 
 **Which of these are for you?** `arrange`, `mirror`, `pack-slim`, `tag`, and `audit links` are general-purpose — they
 work for any pnpm workspace or single package that builds with `tsc`. The other four audits encode codefast's own house
@@ -120,13 +170,6 @@ intentional; pass such a file explicitly to process it.
 `#lib/utils` re-export, any `…/utils` path, or a dedicated `cn.ts` module — so an unrelated local `cn` is left alone.
 Long static JSX `className` strings are regrouped regardless of where `cn` comes from.
 
-| Flag                 | Description                                                                   |
-| -------------------- | ----------------------------------------------------------------------------- |
-| `--dry-run`          | Preview suggested replacements without writing files.                         |
-| `--with-classname`   | Append `className` as the final `cn()` argument (alias: `--with-class-name`). |
-| `--cn-import <spec>` | Override the module specifier used when a missing `cn` import is added.       |
-| `--json`             | Print one JSON object on stdout (suppresses human progress).                  |
-
 Exits `1` when the `arrange.onAfterWrite` hook fails, `0` otherwise.
 
 ### `arrange inspect [target]`
@@ -136,7 +179,15 @@ Read-only report of long strings, nested `cn` inside `tv()`, and related finding
 ### `arrange simplify [target]`
 
 Flattens grouped arrays and static-only `cn()` calls back to plain strings in `tv()` slots — the inverse cleanup pass.
-Accepts `--dry-run` and `--json`.
+In a mixed `cn()` call it coalesces only _adjacent_ static literals and keeps argument order, so tailwind-merge
+precedence is unchanged (a later argument still overrides an earlier one).
+
+With `--fold-variant-classname`, `cn(buttonVariants({ size: "sm" }), "flex-1")` becomes
+`buttonVariants({ size: "sm", className: "flex-1" })`, and a dynamic or multi-part override folds into a `className`
+array. The fold fires only when the native TypeScript type server confirms the callee's options accept a `className` (or
+`class`) of the right shape, so it loads the `typescript` package (an optional peer, v7) and needs the target inside a
+`tsconfig`; files outside a project keep the base pass. Run a formatter afterward — a folded call can exceed the print
+width until it is wrapped.
 
 ### `arrange group <tokens...>`
 
@@ -148,11 +199,7 @@ codefast arrange group "relative flex h-10 w-full items-center rounded-md bg-pri
 codefast arrange group --tv "flex items-center gap-2"
 ```
 
-| Flag               | Description                                                                   |
-| ------------------ | ----------------------------------------------------------------------------- |
-| `--tv`             | Emit a `tv()`-style array instead of a `cn()` call.                           |
-| `--with-classname` | Append `className` as the final `cn()` argument (alias: `--with-class-name`). |
-| `--json`           | Emit `{ schemaVersion, primaryLine, bucketsCommentLine }` on stdout.          |
+With `--json`, that object is `{ schemaVersion, primaryLine, bucketsCommentLine }`.
 
 ## `mirror`
 
@@ -167,12 +214,6 @@ codefast mirror packages/ui     # one package (path relative to repo root)
 codefast mirror --dry-run       # report changes without writing
 ```
 
-| Flag              | Description                                                   |
-| ----------------- | ------------------------------------------------------------- |
-| `--dry-run`       | Report what would change without writing any `package.json`.  |
-| `-v`, `--verbose` | Print extra diagnostics.                                      |
-| `--json`          | Print one JSON summary on stdout (suppresses human progress). |
-
 Exits `1` when any package fails, `0` otherwise.
 
 ### Per-package `mirror` configuration
@@ -221,12 +262,6 @@ codefast pack-slim packages/ui     # one package (path relative to repo root)
 codefast pack-slim --dry-run       # report what would be stripped without touching a file
 ```
 
-| Flag        | Description                                                       |
-| ----------- | ----------------------------------------------------------------- |
-| `--dry-run` | Report what would be stripped without touching any file.          |
-| `--force`   | Run even if the git working tree has uncommitted tracked changes. |
-| `--json`    | Print one JSON summary on stdout (suppresses human progress).     |
-
 Exits `1` when any package fails, `0` otherwise.
 
 ## `tag`
@@ -242,11 +277,6 @@ codefast tag packages/ui/src   # tag one directory or file
 codefast tag --dry-run         # summary only, no writes
 ```
 
-| Flag        | Description                                                   |
-| ----------- | ------------------------------------------------------------- |
-| `--dry-run` | Show summary without writing files.                           |
-| `--json`    | Print one JSON summary on stdout (suppresses human progress). |
-
 Exits `1` when no target is selected, when any target fails, or when the `tag.onAfterWrite` hook fails.
 
 ## `audit`
@@ -317,11 +347,6 @@ codefast audit comments --fix              # rewrite fixable dividers in place
 codefast audit comments --json             # machine-readable summary
 ```
 
-| Flag     | Description                                          |
-| -------- | ---------------------------------------------------- |
-| `--fix`  | Rewrite every mechanically fixable divider in place. |
-| `--json` | Print one JSON summary on stdout.                    |
-
 Configure exceptions via `audit.comments.allowlist` — each entry is a divider line as written or
 `repo/relative/path.ts:<divider>`.
 

package/dist/arrange/command.js

@@ -1,18 +1,95 @@
-import process from "node:process";
 import { Command } from "commander";
-import { analyzeDirectory } from "#/arrange/analyze";
-import { arrangeAnalyzeDirectoryRequestSchema, arrangeSuggestGroupsRequestSchema, arrangeSyncRunRequestSchema, } from "#/arrange/cli-schema";
-import { printAnalyzeReport, printGroupFilePreviewFromWork, printSimplifyResult, printSyncResult, } from "#/arrange/output";
-import { runArrangeSimplify } from "#/arrange/simplify-sync";
-import { suggestCnGroupsFromCli } from "#/arrange/suggest";
-import { runArrangeSync } from "#/arrange/sync";
-import { prepareArrangeWorkspace } from "#/arrange/workspace";
-import { readOptionalPositionalArg } from "#/core/cli/positional";
-import { consumeCliAppError, runCliResultAsync } from "#/core/cli/result-handle";
-import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#/core/exit-codes";
-import { nodeFilesystem } from "#/core/filesystem/node";
-import { logger } from "#/core/logger";
-import { parseWithSchema } from "#/core/schema-parse";
+import { formatArrangeGroupJsonOutput } from "#arrange/group/cli-result";
+import { arrangeSuggestGroupsRequestSchema } from "#arrange/group/cli-schema";
+import { presentArrangeGroupResult } from "#arrange/group/output";
+import { suggestCnGroupsFromCli } from "#arrange/group/suggest";
+import { formatArrangeAnalyzeJsonOutput } from "#arrange/inspect/cli-result";
+import { arrangeAnalyzeDirectoryRequestSchema } from "#arrange/inspect/cli-schema";
+import { presentAnalyzeReport } from "#arrange/inspect/output";
+import { runArrangeInspect } from "#arrange/inspect/run";
+import { prepareArrangeWorkspace } from "#arrange/prepare";
+import { exitCodeForArrangeResult, formatArrangeJsonOutput } from "#arrange/regroup/cli-result";
+import { arrangeRunRequestSchema } from "#arrange/regroup/cli-schema";
+import { presentArrangeResult, presentGroupFilePreviewFromWork } from "#arrange/regroup/output";
+import { runArrange } from "#arrange/regroup/run";
+import { formatArrangeSimplifyJsonOutput } from "#arrange/simplify/cli-result";
+import { arrangeSimplifyRunRequestSchema } from "#arrange/simplify/cli-schema";
+import { presentSimplifyResult } from "#arrange/simplify/output";
+import { runArrangeSimplify } from "#arrange/simplify/run";
+import { applyCommandPipeline, registerPipelineSubcommand } from "#core/cli/command-pipeline";
+import { consumeCliAppError } from "#core/cli/result-handle";
+import { CLI_EXIT_SUCCESS } from "#core/exit-codes";
+import { nodeFilesystem } from "#core/filesystem/node";
+import { logger } from "#core/logger";
+import { parseWithSchema } from "#core/schema-parse";
+const targetHelp = "Directory or file (default: nearest package directory from cwd)";
+const prepareWorkspace = (fs, input) => prepareArrangeWorkspace(fs, { currentWorkingDirectory: input.currentWorkingDirectory, rawTarget: input.rawArg });
+const regroupPipeline = {
+    positional: { name: "[target]", help: targetHelp },
+    schema: arrangeRunRequestSchema,
+    configureArgv: (command) => {
+        command.option("--dry-run", "Preview suggested replacements without writing files", false);
+        command.option("--with-classname, --with-class-name", "Append className as final cn() argument", false);
+        command.option("--cn-import <spec>", "Override module specifier when adding cn import");
+    },
+    prepare: prepareWorkspace,
+    buildRequest: ({ prelude, opts }) => ({
+        rootDir: prelude.rootDir,
+        targetPath: prelude.resolvedTarget,
+        write: !opts.dryRun,
+        withClassName: opts.withClassName,
+        cnImport: opts.cnImport,
+        config: prelude.config.arrange ?? {},
+    }),
+    run: (fs, request) => runArrange(fs, request),
+    presentHuman: ({ result, opts }) => {
+        // Dry-run previews are human-only; the --json summary omits the non-serializable plans.
+        if (opts.dryRun) {
+            for (const plan of result.previewPlans) {
+                presentGroupFilePreviewFromWork(plan);
+            }
+        }
+        presentArrangeResult(result, !opts.dryRun);
+    },
+    formatJson: ({ result, opts }) => formatArrangeJsonOutput(result, !opts.dryRun),
+    exitCode: exitCodeForArrangeResult,
+};
+const inspectPipeline = {
+    name: "inspect",
+    description: "Report long strings, nested cn in tv(), and related findings (read-only)",
+    positional: { name: "[target]", help: targetHelp },
+    schema: arrangeAnalyzeDirectoryRequestSchema,
+    prepare: prepareWorkspace,
+    buildRequest: ({ prelude }) => ({ analyzeRootPath: prelude.resolvedTarget }),
+    run: async (fs, request) => runArrangeInspect(fs, request.analyzeRootPath),
+    presentHuman: ({ result, prelude }) => {
+        presentAnalyzeReport(prelude.resolvedTarget, result);
+    },
+    formatJson: ({ result, prelude }) => formatArrangeAnalyzeJsonOutput(prelude.resolvedTarget, result),
+    exitCode: () => CLI_EXIT_SUCCESS,
+};
+const simplifyPipeline = {
+    name: "simplify",
+    description: "Flatten grouped arrays and static-only cn() calls back to plain strings in tv() slots",
+    positional: { name: "[target]", help: targetHelp },
+    schema: arrangeSimplifyRunRequestSchema,
+    configureArgv: (command) => {
+        command.option("--dry-run", "Show what simplify would change without writing files", false);
+        command.option("--fold-variant-classname, --fold-variant-class-name", "Fold cn() overrides into a variant function's className option (uses the TypeScript type server)", false);
+    },
+    prepare: prepareWorkspace,
+    buildRequest: ({ prelude, opts }) => ({
+        targetPath: prelude.resolvedTarget,
+        write: !opts.dryRun,
+        foldVariantClassName: opts.foldVariantClassName,
+    }),
+    run: (fs, request) => runArrangeSimplify(fs, request),
+    presentHuman: ({ result, opts }) => {
+        presentSimplifyResult(result, !opts.dryRun);
+    },
+    formatJson: ({ result, opts }) => formatArrangeSimplifyJsonOutput(result, !opts.dryRun),
+    exitCode: () => CLI_EXIT_SUCCESS,
+};
 /**
  * Creates the `arrange` command and its subcommands.
  *
@@ -23,110 +100,19 @@ export function createArrangeCommand() {
         .description("Regroup Tailwind classes in cn() / tv() calls in render-pipeline order")
         // The parent action shares option names (--json) with subcommands; positional
         // options ensure tokens after a subcommand bind to that subcommand, not the parent.
-        .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),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { resolvedTarget, rootDir, config } = prelude.value;
-        const parsed = parseWithSchema(arrangeSyncRunRequestSchema, {
-            rootDir,
-            targetPath: resolvedTarget,
-            write,
-            withClassName: opts.withClassName,
-            cnImport: opts.cnImport,
-            config: config.arrange ?? {},
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        await runCliResultAsync(runArrangeSync(nodeFilesystem, parsed.value), (value) => {
-            if (!write) {
-                for (const plan of value.previewPlans) {
-                    printGroupFilePreviewFromWork(plan);
-                }
-            }
-            if (opts.json) {
-                logger.out(formatArrangeSyncJsonOutput(value, write));
-                return exitCodeForArrangeSyncResult(value);
-            }
-            printSyncResult(value, write);
-            return exitCodeForArrangeSyncResult(value);
-        });
-    });
-    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 CLI_EXIT_SUCCESS;
-            }
-            printSimplifyResult(value, write);
-            return CLI_EXIT_SUCCESS;
-        });
-    });
+        .enablePositionalOptions();
+    applyCommandPipeline(cmd, nodeFilesystem, regroupPipeline);
+    registerPipelineSubcommand(cmd, nodeFilesystem, inspectPipeline);
+    registerPipelineSubcommand(cmd, nodeFilesystem, simplifyPipeline);
+    // `group` is a pure token-string transform — no workspace prelude, a variadic positional — so it
+    // does not fit the workspace pipeline and stays wired by hand.
     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)
+        .option("--json", "Print one JSON object on stdout instead of the human-readable output", false)
         .action(async (classTokenSeries, opts) => {
         const parsed = parseWithSchema(arrangeSuggestGroupsRequestSchema, {
             inlineClasses: classTokenSeries.join(" ").trim(),
@@ -141,31 +127,8 @@ export function createArrangeCommand() {
             logger.out(formatArrangeGroupJsonOutput(output));
         }
         else {
-            logger.out(output.primaryLine);
-            logger.out(output.bucketsCommentLine);
+            presentArrangeGroupResult(output);
         }
     });
     return cmd;
-}
-function formatArrangeAnalyzeJsonOutput(analyzeRootPath, report) {
-    return JSON.stringify({ schemaVersion: 1, analyzeRootPath, report });
-}
-function formatArrangeSyncJsonOutput(result, write) {
-    const { previewPlans: _plans, ...serializableResult } = result;
-    return JSON.stringify({
-        schemaVersion: 1,
-        ok: result.hookError === null,
-        write,
-        result: serializableResult,
-    });
-}
-function formatArrangeGroupJsonOutput(output) {
-    return JSON.stringify({
-        schemaVersion: 1,
-        primaryLine: output.primaryLine,
-        bucketsCommentLine: output.bucketsCommentLine,
-    });
-}
-function exitCodeForArrangeSyncResult(result) {
-    return result.hookError !== null ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
 }

package/dist/arrange/domain/ast/collectors-cn.d.ts

@@ -1,5 +1,5 @@
-import type { DomainAstNode } from "#/arrange/domain/ast/ast-node";
-import type { ForEachStringLiteralInClassExpressionOptions, TailwindClassLiteral } from "#/arrange/domain/types";
+import type { DomainAstNode } from "#arrange/domain/ast/ast-node";
+import type { ForEachStringLiteralInClassExpressionOptions, TailwindClassLiteral } from "#arrange/domain/types";
 /**
  * Visits every static class literal reachable inside a class expression.
  *

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

@@ -1,5 +1,5 @@
-import { DomainBinaryOperator, DomainSyntaxKind, isDomainArrayLiteralExpression, isDomainTailwindClassLiteral, } from "#/arrange/domain/ast/ast-node";
-import { MAX_CLASS_EXPR_DEPTH } from "#/arrange/domain/constants";
+import { DomainBinaryOperator, DomainSyntaxKind, isDomainArrayLiteralExpression, isDomainTailwindClassLiteral, } from "#arrange/domain/ast/ast-node";
+import { MAX_CLASS_EXPR_DEPTH } from "#arrange/domain/constants";
 /**
  * Visits every static class literal reachable inside a class expression.
  *

package/dist/arrange/domain/ast/collectors-jsx.d.ts

@@ -1,5 +1,5 @@
-import type { DomainJsxAttribute } from "#/arrange/domain/ast/ast-node";
-import type { JsxClassNameStatic } from "#/arrange/domain/types";
+import type { DomainJsxAttribute } from "#arrange/domain/ast/ast-node";
+import type { JsxClassNameStatic } from "#arrange/domain/types";
 /**
  * Extracts the static literal of a JSX `className` attribute, or `undefined` when it is not static.
  *

package/dist/arrange/domain/ast/collectors-jsx.js

@@ -1,4 +1,4 @@
-import { isDomainIdentifier, isDomainJsxExpression, isDomainTailwindClassLiteral } from "#/arrange/domain/ast/ast-node";
+import { isDomainIdentifier, isDomainJsxExpression, isDomainTailwindClassLiteral } from "#arrange/domain/ast/ast-node";
 /**
  * Extracts the static literal of a JSX `className` attribute, or `undefined` when it is not static.
  *

package/dist/arrange/domain/ast/collectors-tv.d.ts

@@ -1,5 +1,5 @@
-import type { DomainCallExpression, DomainObjectLiteralExpression, DomainSourceFile } from "#/arrange/domain/ast/ast-node";
-import type { StringNode, TailwindClassLiteral } from "#/arrange/domain/types";
+import type { DomainCallExpression, DomainObjectLiteralExpression, DomainSourceFile } from "#arrange/domain/ast/ast-node";
+import type { StringNode, TailwindClassLiteral } from "#arrange/domain/types";
 type StringNodeVisitor = (classLiteral: TailwindClassLiteral, sourceFile: DomainSourceFile, cnCall?: DomainCallExpression) => void;
 /**
  * Visits every class literal reachable inside a `tv({ ... })` object, including `cn()` arguments.

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

@@ -1,8 +1,8 @@
-import { isDomainArrayLiteralExpression, isDomainCallExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral, forEachDomainChild, } from "#/arrange/domain/ast/ast-node";
-import { CN_APPLY_LITERAL_WALK_OPTS, collectUnconditionalTailwindLiteralsFromCnArguments, forEachStringLiteralInClassExpression, isUnsafeLiteralForCnStyleApplySplit, } from "#/arrange/domain/ast/collectors-cn";
-import { buildKnownCnTvBindings, isCnOrTvIdentifier, propertyAssignmentNameText } from "#/arrange/domain/ast/helpers";
-import { APPLY_MIN_TOKENS, MAX_OBJECT_DEPTH } from "#/arrange/domain/constants";
-import { tokenizeClassString } from "#/arrange/domain/tailwind-token";
+import { isDomainArrayLiteralExpression, isDomainCallExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral, forEachDomainChild, } from "#arrange/domain/ast/ast-node";
+import { CN_APPLY_LITERAL_WALK_OPTS, collectUnconditionalTailwindLiteralsFromCnArguments, forEachStringLiteralInClassExpression, isUnsafeLiteralForCnStyleApplySplit, } from "#arrange/domain/ast/collectors-cn";
+import { buildKnownCnTvBindings, isCnOrTvIdentifier, propertyAssignmentNameText } from "#arrange/domain/ast/helpers";
+import { APPLY_MIN_TOKENS, MAX_OBJECT_DEPTH } from "#arrange/domain/constants";
+import { tokenizeClassString } from "#arrange/domain/tailwind-token";
 /**
  * Visits every class literal reachable inside a `tv({ ... })` object, including `cn()` arguments.
  *

package/dist/arrange/domain/ast/helpers.d.ts

@@ -1,5 +1,5 @@
-import type { DomainAstNode, DomainCallExpression, DomainPropertyAssignment, DomainSourceFile } from "#/arrange/domain/ast/ast-node";
-import { applyEditsDescending } from "#/core/source-text-edit";
+import type { DomainAstNode, DomainCallExpression, DomainPropertyAssignment, DomainSourceFile } from "#arrange/domain/ast/ast-node";
+import { applyEditsDescending } from "#core/source-text-edit";
 /**
  * Builds a set of local binding names that are imported from a known cn/tv
  * module in `sourceFile`.

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

@@ -1,6 +1,6 @@
-import { isDomainIdentifier, isDomainImportDeclaration, isDomainNamedImports, isDomainNamespaceImport, isDomainPropertyAccessExpression, isDomainStringLiteral, lineOfSourcePosition, } from "#/arrange/domain/ast/ast-node";
-import { EMPTY_CN_TV_BINDINGS } from "#/arrange/domain/constants";
-import { applyEditsDescending, indentOfLineContaining } from "#/core/source-text-edit";
+import { isDomainIdentifier, isDomainImportDeclaration, isDomainNamedImports, isDomainNamespaceImport, isDomainPropertyAccessExpression, isDomainStringLiteral, lineOfSourcePosition, } from "#arrange/domain/ast/ast-node";
+import { EMPTY_CN_TV_BINDINGS } from "#arrange/domain/constants";
+import { applyEditsDescending, indentOfLineContaining } from "#core/source-text-edit";
 /**
  * Known module specifiers that export `cn` / `tv`.
  */
@@ -12,7 +12,6 @@ const KNOWN_CN_TV_MODULES = new Set([
     // from "tailwind-variants"; new code should prefer "@codefast/tailwind-variants".
     "tailwind-variants",
     "#lib/utils",
-    "#/lib/utils",
     "~/lib/utils",
     "@/lib/utils",
 ]);

package/dist/arrange/domain/ast/simplify-targets.d.ts

@@ -1,4 +1,4 @@
-import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+import type { DomainSourceFile } from "#arrange/domain/ast/ast-node";
 /**
  * A planned text replacement produced by the simplify pass.
  *