@codefast/cli 0.3.13-canary.1 → 0.3.13-canary.3

package/README.md

@@ -221,7 +221,7 @@ The `<version>` value is read from the nearest `package.json` found by walking u
 
 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`.
+To change a placement, edit `classifyBareUtility` in `src/lib/arrange/domain/tokenizer.util.ts` and add a corresponding `classifyToken` test in `src/lib/arrange/domain/tokenizer.util.test.ts`.
 
 ---
 

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

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

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

package/dist/commands/arrange.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerArrangeCommand(program: Command): void;
+//# sourceMappingURL=arrange.d.ts.map

package/dist/commands/arrange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrange.d.ts","sourceRoot":"","sources":["../../src/commands/arrange.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgH7D"}

package/dist/commands/arrange.js

@@ -0,0 +1,108 @@
+import process from "node:process";
+import { Option } from "commander";
+import { ArrangeAnalyzeDirectoryRequestSchema } from "#lib/arrange/application/requests/analyze-directory.request";
+import { ArrangeSyncRunRequestSchema } from "#lib/arrange/application/requests/arrange-sync.request";
+import { ArrangeSuggestGroupsRequestSchema } from "#lib/arrange/application/requests/suggest-groups.request";
+import { createCliContainer } from "#lib/core/infra/container.adapter";
+import { consumeCliAppError } from "#lib/core/presentation/cli-executor.presenter";
+import { parseWithCliSchema } from "#lib/core/presentation/parse-cli-schema.presenter";
+import { runAsyncExitCodeUseCaseAfterParse, runSyncUseCaseAfterParse, } from "#lib/core/presentation/run-cli-use-case-after-parse.presenter";
+function withClassNameOption() {
+    return new Option("--with-classname, --with-class-name", "Append className as final cn() argument").default(false);
+}
+export 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 cli = createCliContainer();
+        const prelude = await cli.arrange.prepareTargetWorkspaceAndConfig({
+            currentWorkingDirectory: process.cwd(),
+            rawTarget: target,
+        });
+        if (!consumeCliAppError(cli.logger, prelude)) {
+            return;
+        }
+        const { resolvedTarget } = prelude.value;
+        const parsed = parseWithCliSchema(ArrangeAnalyzeDirectoryRequestSchema, {
+            analyzeRootPath: resolvedTarget,
+        });
+        runSyncUseCaseAfterParse(cli, parsed, (input) => cli.arrange.analyzeDirectory(input), (report) => cli.arrange.presentAnalyzeReport(resolvedTarget, report));
+    });
+    arrange
+        .command("preview")
+        .description("Dry-run: print suggested replacements without writing files")
+        .argument("[target]", "Directory or file (default: packages/ui/src/components)")
+        .addOption(withClassNameOption())
+        .option("--cn-import <spec>", "Override module specifier when adding cn import")
+        .action(async (target, opts) => {
+        const cli = createCliContainer();
+        const prelude = await cli.arrange.prepareTargetWorkspaceAndConfig({
+            currentWorkingDirectory: process.cwd(),
+            rawTarget: target,
+        });
+        if (!consumeCliAppError(cli.logger, prelude)) {
+            return;
+        }
+        const { resolvedTarget, rootDir, config } = prelude.value;
+        const parsed = parseWithCliSchema(ArrangeSyncRunRequestSchema, {
+            rootDir,
+            targetPath: resolvedTarget,
+            write: false,
+            withClassName: opts.withClassName,
+            cnImport: opts.cnImport,
+            config: config.arrange ?? {},
+        });
+        await runAsyncExitCodeUseCaseAfterParse(cli, parsed, (input) => cli.arrange.runArrangeSync(input));
+    });
+    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(withClassNameOption())
+        .option("--cn-import <spec>", "Override module specifier when adding cn import")
+        .action(async (target, opts) => {
+        const cli = createCliContainer();
+        const prelude = await cli.arrange.prepareTargetWorkspaceAndConfig({
+            currentWorkingDirectory: process.cwd(),
+            rawTarget: target,
+        });
+        if (!consumeCliAppError(cli.logger, prelude)) {
+            return;
+        }
+        const { resolvedTarget, rootDir, config } = prelude.value;
+        const parsed = parseWithCliSchema(ArrangeSyncRunRequestSchema, {
+            rootDir,
+            targetPath: resolvedTarget,
+            write: true,
+            withClassName: opts.withClassName,
+            cnImport: opts.cnImport,
+            config: config.arrange ?? {},
+        });
+        await runAsyncExitCodeUseCaseAfterParse(cli, parsed, (input) => cli.arrange.runArrangeSync(input));
+    });
+    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(withClassNameOption())
+        .action((tokens, opts) => {
+        const cli = createCliContainer();
+        const parsed = parseWithCliSchema(ArrangeSuggestGroupsRequestSchema, {
+            inlineClasses: tokens.join(" ").trim(),
+            emitTvStyleArray: !!opts.tv,
+            trailingClassName: !!opts.withClassName,
+        });
+        if (!consumeCliAppError(cli.logger, parsed)) {
+            return;
+        }
+        const output = cli.arrange.suggestCnGroups(parsed.value);
+        cli.logger.out(output.primaryLine);
+        cli.logger.out(output.bucketsCommentLine);
+    });
+}

package/dist/commands/mirror.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerMirrorCommand(program: Command): void;
+//# sourceMappingURL=mirror.d.ts.map

package/dist/commands/mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror.d.ts","sourceRoot":"","sources":["../../src/commands/mirror.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoC5D"}

package/dist/commands/mirror.js

@@ -0,0 +1,36 @@
+import process from "node:process";
+import { createCliContainer } from "#lib/core/infra/container.adapter";
+import { consumeCliAppError } from "#lib/core/presentation/cli-executor.presenter";
+import { parseWithCliSchema } from "#lib/core/presentation/parse-cli-schema.presenter";
+import { runAsyncExitCodeUseCaseAfterParse } from "#lib/core/presentation/run-cli-use-case-after-parse.presenter";
+import { MirrorSyncRunRequestSchema } from "#lib/mirror/application/requests/mirror-sync.request";
+export function registerMirrorCommand(program) {
+    const mirror = program
+        .command("mirror")
+        .description("Keep package manifests aligned with what you ship");
+    mirror
+        .command("sync")
+        .description("Write package.json exports from dist/ for workspace packages")
+        .argument("[package]", "Optional package path relative to repo root (e.g. packages/ui)")
+        .option("-v, --verbose", "Print extra diagnostics", false)
+        .action(async function (pkg, options) {
+        const cli = createCliContainer();
+        const prelude = await cli.mirror.prepareMirrorSync({
+            currentWorkingDirectory: process.cwd(),
+            packageArg: pkg,
+            globalCliRaw: this.optsWithGlobals(),
+        });
+        if (!consumeCliAppError(cli.logger, prelude)) {
+            return;
+        }
+        const { rootDir, config, packageFilter, globals } = prelude.value;
+        const parsed = parseWithCliSchema(MirrorSyncRunRequestSchema, {
+            rootDir,
+            config: config.mirror ?? {},
+            verbose: options.verbose,
+            noColor: globals.color === false,
+            packageFilter,
+        });
+        await runAsyncExitCodeUseCaseAfterParse(cli, parsed, (input) => cli.mirror.runMirrorSync(input));
+    });
+}

package/dist/commands/tag.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerTagCommand(program: Command): void;
+//# sourceMappingURL=tag.d.ts.map

package/dist/commands/tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../src/commands/tag.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6CzD"}

package/dist/commands/tag.js

@@ -0,0 +1,44 @@
+import process from "node:process";
+import { createCliContainer } from "#lib/core/infra/container.adapter";
+import { consumeCliAppError } from "#lib/core/presentation/cli-executor.presenter";
+import { parseWithCliSchema } from "#lib/core/presentation/parse-cli-schema.presenter";
+import { TagSyncRunRequestSchema } from "#lib/tag/application/requests/tag-sync.request";
+export function registerTagCommand(program) {
+    program
+        .command("tag")
+        .alias("annotate")
+        .description("Add @since <version> JSDoc tags to exported declarations")
+        .argument("[target]", "Directory or file to annotate (default: auto-discover workspace packages)")
+        .option("--dry-run", "Show summary without writing files", false)
+        .action(async function (target, options) {
+        const cli = createCliContainer();
+        const prelude = await cli.tag.prepareTagSync({
+            currentWorkingDirectory: process.cwd(),
+            rawTarget: target,
+            globalCliRaw: this.optsWithGlobals(),
+        });
+        if (!consumeCliAppError(cli.logger, prelude)) {
+            return;
+        }
+        const { rootDir, config, resolvedTargetPath } = prelude.value;
+        const tagConfig = config.tag ?? {};
+        const parsed = parseWithCliSchema(TagSyncRunRequestSchema, {
+            rootDir,
+            write: !options.dryRun,
+            targetPath: resolvedTargetPath,
+            skipPackages: tagConfig.skipPackages,
+            config: tagConfig,
+        });
+        if (!consumeCliAppError(cli.logger, parsed)) {
+            return;
+        }
+        const tagOutcome = await cli.tag.runTagSync({
+            ...parsed.value,
+            listener: cli.tag.createProgressListener((line) => cli.logger.out(line)),
+        });
+        if (!consumeCliAppError(cli.logger, tagOutcome)) {
+            return;
+        }
+        process.exitCode = cli.tag.presentSyncCliResult(tagOutcome.value, rootDir);
+    });
+}

package/dist/lib/arrange/application/ports/domain-source-parser.port.d.ts

@@ -0,0 +1,5 @@
+import type { DomainSourceFile } from "#lib/arrange/domain/ast/ast-node.model";
+export interface DomainSourceParserPort {
+    parseDomainSourceFile(filePath: string, sourceText: string): DomainSourceFile;
+}
+//# sourceMappingURL=domain-source-parser.port.d.ts.map

package/dist/lib/arrange/application/ports/domain-source-parser.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-source-parser.port.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/ports/domain-source-parser.port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAE/E,MAAM,WAAW,sBAAsB;IACrC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC;CAC/E"}

package/dist/lib/arrange/application/ports/file-walker.port.d.ts

@@ -0,0 +1,5 @@
+import type { CliFs } from "#lib/core/application/ports/cli-io.port";
+export interface FileWalkerPort {
+    walkTypeScriptFiles(rootDirectoryPath: string, fs: CliFs): string[];
+}
+//# sourceMappingURL=file-walker.port.d.ts.map

package/dist/lib/arrange/application/ports/file-walker.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-walker.port.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/ports/file-walker.port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,mBAAmB,CAAC,iBAAiB,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,EAAE,CAAC;CACrE"}

package/dist/lib/arrange/application/requests/analyze-directory.request.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare const ArrangeAnalyzeDirectoryRequestSchema: z.ZodObject<{
+    analyzeRootPath: z.ZodString;
+}, z.core.$strip>;
+export type ArrangeAnalyzeDirectoryRequest = z.infer<typeof ArrangeAnalyzeDirectoryRequestSchema>;
+//# sourceMappingURL=analyze-directory.request.d.ts.map

package/dist/lib/arrange/application/requests/analyze-directory.request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-directory.request.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/requests/analyze-directory.request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oCAAoC;;iBAE/C,CAAC;AAEH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC"}

package/dist/lib/arrange/application/requests/analyze-directory.request.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const ArrangeAnalyzeDirectoryRequestSchema = z.object({
+    analyzeRootPath: z.string().min(1, "analyzeRootPath is required"),
+});

package/dist/lib/arrange/application/requests/arrange-sync.request.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const ArrangeSyncRunRequestSchema: z.ZodObject<{
+    rootDir: z.ZodString;
+    targetPath: z.ZodString;
+    write: z.ZodBoolean;
+    withClassName: z.ZodOptional<z.ZodBoolean>;
+    cnImport: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type ArrangeSyncRunRequest = z.infer<typeof ArrangeSyncRunRequestSchema>;
+export declare const ArrangeRunTargetRequestSchema: z.ZodObject<{
+    targetPath: z.ZodString;
+    write: z.ZodBoolean;
+    withClassName: z.ZodOptional<z.ZodBoolean>;
+    cnImport: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ArrangeRunTargetRequest = z.infer<typeof ArrangeRunTargetRequestSchema>;
+//# sourceMappingURL=arrange-sync.request.d.ts.map

package/dist/lib/arrange/application/requests/arrange-sync.request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrange-sync.request.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/requests/arrange-sync.request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,2BAA2B;;;;;;;iBAOtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,6BAA6B;;;;;iBAKxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}

package/dist/lib/arrange/application/requests/arrange-sync.request.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export const ArrangeSyncRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    write: z.boolean(),
+    withClassName: z.boolean().optional(),
+    cnImport: z.string().optional(),
+    config: z.unknown().optional(),
+});
+export const ArrangeRunTargetRequestSchema = z.object({
+    targetPath: z.string().min(1),
+    write: z.boolean(),
+    withClassName: z.boolean().optional(),
+    cnImport: z.string().optional(),
+});

package/dist/lib/arrange/application/requests/suggest-groups.request.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const ArrangeSuggestGroupsRequestSchema: z.ZodObject<{
+    inlineClasses: z.ZodString;
+    emitTvStyleArray: z.ZodBoolean;
+    trailingClassName: z.ZodBoolean;
+}, z.core.$strip>;
+export type ArrangeSuggestGroupsRequest = z.infer<typeof ArrangeSuggestGroupsRequestSchema>;
+//# sourceMappingURL=suggest-groups.request.d.ts.map

package/dist/lib/arrange/application/requests/suggest-groups.request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-groups.request.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/requests/suggest-groups.request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iCAAiC;;;;iBAM5C,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC"}

package/dist/lib/arrange/application/requests/suggest-groups.request.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export const ArrangeSuggestGroupsRequestSchema = z.object({
+    inlineClasses: z
+        .string()
+        .min(1, 'Pass a class string. Example: codefast arrange group "flex gap-2 text-sm rounded-md"'),
+    emitTvStyleArray: z.boolean(),
+    trailingClassName: z.boolean(),
+});

package/dist/lib/arrange/application/use-cases/analyze-directory.use-case.d.ts

@@ -0,0 +1,17 @@
+import { type AppError } from "#lib/core/domain/errors.domain";
+import { type Result } from "#lib/core/domain/result.model";
+import type { CliFs } from "#lib/core/application/ports/cli-io.port";
+import type { DomainSourceParserPort } from "#lib/arrange/application/ports/domain-source-parser.port";
+import type { ArrangeAnalyzeDirectoryRequest } from "#lib/arrange/application/requests/analyze-directory.request";
+import type { FileWalkerPort } from "#lib/arrange/application/ports/file-walker.port";
+import type { AnalyzeReport } from "#lib/arrange/domain/types.domain";
+export type AnalyzeDirectoryDeps = {
+    readonly fs: CliFs;
+    readonly fileWalker: FileWalkerPort;
+    readonly domainSourceParser: DomainSourceParserPort;
+};
+/**
+ * Orchestrates filesystem + parse ports, delegates analysis rules to the domain service.
+ */
+export declare function analyzeDirectory(request: ArrangeAnalyzeDirectoryRequest, deps: AnalyzeDirectoryDeps): Result<AnalyzeReport, AppError>;
+//# sourceMappingURL=analyze-directory.use-case.d.ts.map

package/dist/lib/arrange/application/use-cases/analyze-directory.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-directory.use-case.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/use-cases/analyze-directory.use-case.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAErE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0DAA0D,CAAC;AACvG,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,6DAA6D,CAAC;AAClH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAMtE,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;CACrD,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,8BAA8B,EACvC,IAAI,EAAE,oBAAoB,GACzB,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAiBjC"}

package/dist/lib/arrange/application/use-cases/analyze-directory.use-case.js

@@ -0,0 +1,24 @@
+import { appError } from "#lib/core/domain/errors.domain";
+import { err, ok } from "#lib/core/domain/result.model";
+import { messageFromCaughtUnknown } from "#lib/core/application/utils/caught-unknown-message.util";
+import { accumulateAnalyzeReportForSourceFile, createEmptyAnalyzeReport, } from "#lib/arrange/domain/arrange-analyze.service";
+/**
+ * Orchestrates filesystem + parse ports, delegates analysis rules to the domain service.
+ */
+export function analyzeDirectory(request, deps) {
+    const report = createEmptyAnalyzeReport();
+    try {
+        const files = deps.fs.statSync(request.analyzeRootPath).isDirectory()
+            ? deps.fileWalker.walkTypeScriptFiles(request.analyzeRootPath, deps.fs)
+            : [request.analyzeRootPath];
+        for (const filePath of files) {
+            const sourceText = deps.fs.readFileSync(filePath, "utf8");
+            const domainSf = deps.domainSourceParser.parseDomainSourceFile(filePath, sourceText);
+            accumulateAnalyzeReportForSourceFile(report, domainSf, sourceText, filePath);
+        }
+        return ok(report);
+    }
+    catch (caughtError) {
+        return err(appError("INFRA_FAILURE", messageFromCaughtUnknown(caughtError), caughtError));
+    }
+}

package/dist/lib/arrange/application/use-cases/group-file-preview.use-case.d.ts

@@ -0,0 +1,17 @@
+import type { CliLogger } from "#lib/core/application/ports/cli-io.port";
+import type { GroupFileUnwrapPlan, GroupFileWorkPlan } from "#lib/arrange/domain/arrange-grouping.service";
+import type { DomainCallExpression, DomainSourceFile } from "#lib/arrange/domain/ast/ast-node.model";
+import type { PlannedGroupEdit } from "#lib/arrange/domain/types.domain";
+export declare function printGroupFilePreview(logger: CliLogger, args: {
+    filePath: string;
+    reportTotal: number;
+    cnInTvNoReplacement: number;
+    cnInTvCalls: readonly DomainCallExpression[];
+    unwrapReplacementByCall: ReadonlyMap<DomainCallExpression, string>;
+    sourceText: string;
+    domainSf: DomainSourceFile;
+    unwrapEdits: readonly GroupFileUnwrapPlan[];
+    plannedGroupEdits: readonly PlannedGroupEdit[];
+}): void;
+export declare function printGroupFilePreviewFromWork(logger: CliLogger, work: GroupFileWorkPlan): void;
+//# sourceMappingURL=group-file-preview.use-case.d.ts.map

package/dist/lib/arrange/application/use-cases/group-file-preview.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-file-preview.use-case.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/use-cases/group-file-preview.use-case.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,8CAA8C,CAAC;AAEtD,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC7C,uBAAuB,EAAE,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD,GACA,IAAI,CA6CN;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAY9F"}

package/dist/lib/arrange/application/use-cases/group-file-preview.use-case.js

@@ -0,0 +1,46 @@
+import { lineOf } from "#lib/arrange/domain/ast/ast-helpers.helper";
+export function printGroupFilePreview(logger, args) {
+    const { out } = logger;
+    const { filePath, reportTotal, cnInTvNoReplacement, cnInTvCalls, unwrapReplacementByCall, sourceText, domainSf, unwrapEdits, plannedGroupEdits, } = args;
+    let header = `\n── ${filePath} (${reportTotal} site(s)`;
+    if (cnInTvNoReplacement > 0) {
+        header += `; plus ${cnInTvNoReplacement} cn() inside tv left unchanged (0 args)`;
+    }
+    header += `) ──`;
+    out(header);
+    for (const call of cnInTvCalls) {
+        const replacement = unwrapReplacementByCall.get(call);
+        if (replacement === undefined) {
+            out(`  Line ${lineOf(domainSf, call)} [tv \u2283 cn]: cn(...) has no arguments — skipped`);
+            continue;
+        }
+        const start = call.pos;
+        const end = call.end;
+        if (sourceText.slice(start, end) === replacement) {
+            continue;
+        }
+        out(`  Line ${lineOf(domainSf, call)} [tv \u2283 cn \u2192 string/array]:`);
+        out(`  ${replacement.split("\n").join("\n  ")}`);
+    }
+    if (unwrapEdits.length > 0 && plannedGroupEdits.length > 0) {
+        out("  ([cn] / [tv] / [JSX className] lines below reflect content after unwrap of cn inside tv.)");
+    }
+    for (const plan of plannedGroupEdits) {
+        out(`  Line ${lineOf(plan.lineSf, plan.reportNode)} [${plan.label}]:`);
+        out(`  ${plan.replacement.split("\n").join("\n  ")}`);
+        out(`  // Buckets: ${JSON.stringify(plan.bucketSummary)}`);
+    }
+}
+export function printGroupFilePreviewFromWork(logger, work) {
+    printGroupFilePreview(logger, {
+        filePath: work.filePath,
+        reportTotal: work.reportTotal,
+        cnInTvNoReplacement: work.cnInTvNoReplacement,
+        cnInTvCalls: work.cnInTvCalls,
+        unwrapReplacementByCall: work.unwrapReplacementByCall,
+        sourceText: work.sourceText,
+        domainSf: work.domainSfForLineNumbers,
+        unwrapEdits: work.unwrapEdits,
+        plannedGroupEdits: work.plannedGroupEdits,
+    });
+}

package/dist/lib/arrange/application/use-cases/group-file.use-case.d.ts

@@ -0,0 +1,5 @@
+import type { CliFs, CliLogger } from "#lib/core/application/ports/cli-io.port";
+import type { DomainSourceParserPort } from "#lib/arrange/application/ports/domain-source-parser.port";
+import type { ArrangeGroupFileOptions, GroupFileResult } from "#lib/arrange/domain/types.domain";
+export declare function groupFile(filePath: string, options: ArrangeGroupFileOptions, fs: CliFs, logger: CliLogger, domainSourceParser: DomainSourceParserPort): GroupFileResult;
+//# sourceMappingURL=group-file.use-case.d.ts.map

package/dist/lib/arrange/application/use-cases/group-file.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-file.use-case.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/use-cases/group-file.use-case.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAChF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0DAA0D,CAAC;AAEvG,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAajG,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,EAChC,EAAE,EAAE,KAAK,EACT,MAAM,EAAE,SAAS,EACjB,kBAAkB,EAAE,sBAAsB,GACzC,eAAe,CAgDjB"}

package/dist/lib/arrange/application/use-cases/group-file.use-case.js

@@ -0,0 +1,40 @@
+import { printGroupFilePreviewFromWork } from "#lib/arrange/application/use-cases/group-file-preview.use-case";
+import { buildGroupFileUnwrapState, countPersistedGroupFileEdits, groupFileDryRunNoEdits, groupFileEditsTouchJsxCn, groupFilePreviewTotals, groupFileWorkHasNothingToReport, mergeGroupFileBodyText, tryBuildGroupFileWorkPlan, } from "#lib/arrange/domain/arrange-grouping.service";
+import { ensureCnImport } from "#lib/arrange/domain/imports.domain";
+export function groupFile(filePath, options, fs, logger, domainSourceParser) {
+    const sourceText = fs.readFileSync(filePath, "utf8");
+    const domainSfInitial = domainSourceParser.parseDomainSourceFile(filePath, sourceText);
+    const unwrap = buildGroupFileUnwrapState(domainSfInitial, sourceText);
+    const domainSfGrouped = domainSourceParser.parseDomainSourceFile(filePath, unwrap.textAfterUnwrap);
+    const work = tryBuildGroupFileWorkPlan({
+        filePath,
+        sourceText,
+        domainSfInitial,
+        domainSfGrouped,
+        withClassName: options.withClassName,
+        unwrap,
+    });
+    if (work === null) {
+        return groupFileDryRunNoEdits(filePath);
+    }
+    if (!options.write) {
+        if (groupFileWorkHasNothingToReport(work)) {
+            return groupFileDryRunNoEdits(filePath);
+        }
+        printGroupFilePreviewFromWork(logger, work);
+        return groupFilePreviewTotals(work);
+    }
+    const persistedEditCount = countPersistedGroupFileEdits(work);
+    let newText = mergeGroupFileBodyText(work);
+    if (persistedEditCount > 0) {
+        if (groupFileEditsTouchJsxCn(work)) {
+            newText = ensureCnImport(domainSourceParser.parseDomainSourceFile(filePath, newText), options.cnImport);
+        }
+        fs.writeFileSync(filePath, newText, "utf8");
+    }
+    return {
+        filePath,
+        totalFound: persistedEditCount + work.cnInTvNoReplacement,
+        changed: persistedEditCount,
+    };
+}

package/dist/lib/arrange/application/use-cases/run-arrange-sync.use-case.d.ts

@@ -0,0 +1,19 @@
+import { type AppError } from "#lib/core/domain/errors.domain";
+import { type Result } from "#lib/core/domain/result.model";
+import type { CliFs, CliLogger } from "#lib/core/application/ports/cli-io.port";
+import type { DomainSourceParserPort } from "#lib/arrange/application/ports/domain-source-parser.port";
+import type { FileWalkerPort } from "#lib/arrange/application/ports/file-walker.port";
+import type { ArrangeRunTargetRequest, ArrangeSyncRunRequest } from "#lib/arrange/application/requests/arrange-sync.request";
+import type { ArrangeRunResult } from "#lib/arrange/domain/types.domain";
+export type ArrangeSyncDeps = {
+    readonly fs: CliFs;
+    readonly logger: CliLogger;
+    readonly fileWalker: FileWalkerPort;
+    readonly domainSourceParser: DomainSourceParserPort;
+};
+export declare function runOnTarget(request: ArrangeRunTargetRequest, deps: ArrangeSyncDeps): Result<ArrangeRunResult, AppError>;
+/**
+ * Preview/apply orchestration: resolves target path, runs grouping pipeline, optional hook.
+ */
+export declare function runArrangeSync(request: ArrangeSyncRunRequest, deps: ArrangeSyncDeps): Promise<Result<number, AppError>>;
+//# sourceMappingURL=run-arrange-sync.use-case.d.ts.map

package/dist/lib/arrange/application/use-cases/run-arrange-sync.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-arrange-sync.use-case.d.ts","sourceRoot":"","sources":["../../../../../src/lib/arrange/application/use-cases/run-arrange-sync.use-case.ts"],"names":[],"mappings":"AAKA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGhF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0DAA0D,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACtF,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,wDAAwD,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;CACrD,CAAC;AAEF,wBAAgB,WAAW,CACzB,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAsDpC;AAiBD;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CA+BnC"}

package/dist/lib/arrange/application/use-cases/run-arrange-sync.use-case.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { appError } from "#lib/core/domain/errors.domain";
+import { err, ok } from "#lib/core/domain/result.model";
+import { messageFromCaughtUnknown } from "#lib/core/application/utils/caught-unknown-message.util";
+import { groupFile } from "#lib/arrange/application/use-cases/group-file.use-case";
+export function runOnTarget(request, deps) {
+    const { out } = deps.logger;
+    const { fs, fileWalker, domainSourceParser } = deps;
+    if (!fs.existsSync(request.targetPath)) {
+        return err(appError("NOT_FOUND", `Not found: ${request.targetPath}`));
+    }
+    const filePaths = fs.statSync(request.targetPath).isDirectory()
+        ? fileWalker.walkTypeScriptFiles(request.targetPath, fs)
+        : [request.targetPath];
+    const modifiedFiles = [];
+    let totalFound = 0;
+    let totalChanged = 0;
+    const groupOptions = {
+        write: request.write,
+        withClassName: !!request.withClassName,
+        cnImport: request.cnImport,
+    };
+    for (const filePath of filePaths) {
+        const result = groupFile(filePath, groupOptions, fs, deps.logger, domainSourceParser);
+        totalFound += result.totalFound;
+        totalChanged += result.changed;
+        if (result.changed > 0) {
+            modifiedFiles.push(result.filePath);
+        }
+    }
+    out(`\nTotal: ${filePaths.length} file(s), ${totalFound} site(s) (cn/tv/JSX className) to review.`);
+    if (request.write) {
+        out(`Applied: ${totalChanged} site(s) updated.`);
+    }
+    else {
+        out(`(Run "apply" to write changes, or "pnpm cli:arrange-apply" / "pnpm exec codefast arrange apply")`);
+    }
+    const showCascadeHint = request.write ? totalChanged > 0 : totalFound > 0;
+    if (showCascadeHint) {
+        out("Note: class order may change across concern groups — smoke-test the UI if you rely on cascade order.");
+    }
+    return ok({
+        filePaths,
+        modifiedFiles,
+        totalFound,
+        totalChanged,
+    });
+}
+async function runArrangeOnAfterWriteHook(logger, hook, modifiedFiles) {
+    if (!hook || modifiedFiles.length === 0) {
+        return;
+    }
+    try {
+        await hook({ files: modifiedFiles });
+    }
+    catch (caughtHookError) {
+        logger.err(`[arrange] onAfterWrite hook failed: ${messageFromCaughtUnknown(caughtHookError)}`);
+    }
+}
+/**
+ * Preview/apply orchestration: resolves target path, runs grouping pipeline, optional hook.
+ */
+export async function runArrangeSync(request, deps) {
+    void request.rootDir;
+    const resolvedTarget = path.resolve(request.targetPath);
+    const runTargetRequest = {
+        targetPath: resolvedTarget,
+        write: request.write,
+        withClassName: request.withClassName,
+        cnImport: request.cnImport,
+    };
+    const runOutcome = runOnTarget(runTargetRequest, deps);
+    if (!runOutcome.ok) {
+        if (runOutcome.error.code === "NOT_FOUND") {
+            deps.logger.err(runOutcome.error.message);
+        }
+        return runOutcome;
+    }
+    const result = runOutcome.value;
+    if (request.write && result.modifiedFiles.length > 0) {
+        const arrangeConfig = request.config;
+        await runArrangeOnAfterWriteHook(deps.logger, arrangeConfig?.onAfterWrite, result.modifiedFiles);
+    }
+    return ok(0);
+}