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

package/dist/arrange/domain/grouping.mjs

@@ -72,7 +72,7 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 function areCnTailwindPartitionsEquivalent(staticLiteralTexts, suggestedGroups) {
 	const partitionSignatures = (chunks) => chunks.map((chunk) => {
 		const classTokens = tokenizeClassString(chunk);
-		return classTokens.length === 0 ? "" : [...classTokens].sort(compareClassTokensCanonically).join(" ");
+		return classTokens.length === 0 ? "" : [...classTokens].toSorted(compareClassTokensCanonically).join(" ");
 	}).filter((s) => s.length > 0).sort(compareClassTokensCanonically);
 	const staticPartitionSigs = partitionSignatures(staticLiteralTexts);
 	const suggestedPartitionSigs = partitionSignatures(suggestedGroups);
@@ -230,7 +230,7 @@ function mergeEaseTimingIntoFollowingAnimatedState(groups) {
 				const chunkJ = result[j];
 				if (chunkJ === void 0) throw new Error("invariant: mergeEase following chunk missing");
 				if (dominantBucketOfGroup(chunkJ) !== "state") continue;
-				if (!tokenizeClassString(chunkJ).some((classToken) => /^animate/.test(stripVariants(classToken)))) continue;
+				if (!tokenizeClassString(chunkJ).some((classToken) => stripVariants(classToken).startsWith("animate"))) continue;
 				target = j;
 				break;
 			}
@@ -248,7 +248,7 @@ function mergeEaseTimingIntoFollowingAnimatedState(groups) {
 function chunkIsOnlyEaseTimingMotion(groupStr) {
 	const classTokens = tokenizeClassString(groupStr);
 	if (classTokens.length === 0) return false;
-	return classTokens.every((classToken) => classifyToken(classToken) === "motion" && /^ease-/.test(stripVariants(classToken)));
+	return classTokens.every((classToken) => classifyToken(classToken) === "motion" && stripVariants(classToken).startsWith("ease-"));
 }
 /**
 * @since 0.3.16-canary.0
@@ -328,9 +328,9 @@ function suggestCnGroups(classString) {
 function summarizeGroupBucketLabels(groups) {
 	return groups.map((g) => {
 		const uniq = new Set(tokenizeClassString(g).map(classifyToken));
-		if (uniq.size !== 1) return `mixed:${[...uniq].sort(compareClassTokensCanonically).join("+")}`;
+		if (uniq.size !== 1) return `mixed:${[...uniq].toSorted(compareClassTokensCanonically).join("+")}`;
 		const onlyBucket = [...uniq][0];
-		if (onlyBucket === void 0) return `mixed:${[...uniq].sort(compareClassTokensCanonically).join("+")}`;
+		if (onlyBucket === void 0) return `mixed:${[...uniq].toSorted(compareClassTokensCanonically).join("+")}`;
 		return onlyBucket;
 	});
 }

package/dist/arrange/domain/imports.mjs

@@ -1,4 +1,5 @@
-import { isDomainImportDeclaration, isDomainNamedImports, isDomainStringLiteral } from "./ast/ast-node.mjs";
+import { forEachDomainChild, isDomainIdentifier, isDomainImportDeclaration, isDomainNamedImports, isDomainStringLiteral } from "./ast/ast-node.mjs";
+import { endAfterOptionalCommaFollowingInSource } from "../../core/source-text-edit.mjs";
 //#region src/arrange/domain/imports.ts
 function sourceFileImportsCn(sourceFile) {
 	for (const statement of sourceFile.statements) {
@@ -25,6 +26,53 @@ function findImportDeclarationFromModule(sourceFile, moduleSpecifier) {
 		if (isDomainStringLiteral(spec) && spec.text === moduleSpecifier) return statement;
 	}
 }
+function cnIsUsedInBody(node) {
+	if (isDomainIdentifier(node) && node.text === "cn") return true;
+	let found = false;
+	forEachDomainChild(node, (child) => {
+		if (!found) found = cnIsUsedInBody(child);
+	});
+	return found;
+}
+function removeCnSpecifier(sourceText, specifier, allSpecifiers) {
+	const idx = allSpecifiers.indexOf(specifier);
+	if (idx === 0) {
+		const next = allSpecifiers[1];
+		if (!next) return sourceText;
+		return sourceText.slice(0, specifier.pos) + sourceText.slice(next.pos);
+	}
+	const prev = allSpecifiers[idx - 1];
+	if (!prev) return sourceText;
+	const endWithTrailingComma = endAfterOptionalCommaFollowingInSource(sourceText, specifier.end);
+	return sourceText.slice(0, prev.end) + sourceText.slice(endWithTrailingComma);
+}
+/**
+* After simplify rewrites, drop the `cn` import specifier when `cn` is no
+* longer referenced anywhere outside the import declarations.
+*
+* @since 0.3.16-canary.0
+*/
+function dropCnImportIfUnused(sourceFile) {
+	const sourceText = sourceFile.text;
+	for (const stmt of sourceFile.statements) {
+		if (isDomainImportDeclaration(stmt)) continue;
+		if (cnIsUsedInBody(stmt)) return sourceText;
+	}
+	for (const stmt of sourceFile.statements) {
+		if (!isDomainImportDeclaration(stmt) || !stmt.importClause) continue;
+		const clause = stmt.importClause;
+		if (!clause.namedBindings || !isDomainNamedImports(clause.namedBindings)) continue;
+		const elements = clause.namedBindings.elements;
+		const cnSpecifier = elements.find((el) => el.name.text === "cn");
+		if (!cnSpecifier) continue;
+		if (elements.length === 1) {
+			const lineEnd = sourceText.indexOf("\n", stmt.end);
+			return sourceText.slice(0, stmt.pos) + (lineEnd !== -1 ? sourceText.slice(lineEnd + 1) : sourceText.slice(stmt.end));
+		}
+		return removeCnSpecifier(sourceText, cnSpecifier, elements);
+	}
+	return sourceText;
+}
 /**
 * @since 0.3.16-canary.0
 */
@@ -56,4 +104,4 @@ function ensureCnImport(sourceFile, cnImportOverride) {
 	return `${sourceText.slice(0, insertAt)}${importLine}\n${sourceText.slice(insertAt)}`;
 }
 //#endregion
-export { ensureCnImport };
+export { dropCnImportIfUnused, ensureCnImport };

package/dist/arrange/domain/token-classifier.mjs

@@ -50,9 +50,9 @@ function isStateToken(token) {
 	if (prefix.startsWith("supports-[")) return true;
 	if (prefix.startsWith("in-data-")) return true;
 	if (/^data-(?!\[)/.test(prefix)) return true;
-	if (/^aria-/.test(prefix)) return true;
+	if (prefix.startsWith("aria-")) return true;
 	if (/^(group|peer)-/.test(prefix)) return true;
-	if (/^not-/.test(prefix)) return true;
+	if (prefix.startsWith("not-")) return true;
 	if (isCompoundOrMediaVariantPrefix(prefix)) return true;
 	if (prefix.startsWith("[") && prefix.endsWith("]")) return true;
 	return false;
@@ -65,13 +65,13 @@ function isStateToken(token) {
 */
 function compositeSecondaryOrder(bareUtility) {
 	const b = bareUtility;
-	if (/^opacity(?:-|$)/.test(b) || /^mix-blend-/.test(b) || /^isolation(?:-|$)/.test(b) || b === "isolate") return 0;
+	if (/^opacity(?:-|$)/.test(b) || b.startsWith("mix-blend-") || /^isolation(?:-|$)/.test(b) || b === "isolate") return 0;
 	if (b === "transform-3d" || /^perspective(?:-|$)/.test(b)) return 10;
 	if (/^rotate-[xyz](?:-|$)/.test(b) || /^translate-z(?:-|$)/.test(b) || /^scale-z(?:-|$)/.test(b)) return 20;
 	if (/^translate(?:-|$)/.test(b) || /^scale(?:-|$)/.test(b) || /^rotate(?:-|$)/.test(b) || /^skew(?:-|$)/.test(b)) return 30;
 	if (/^transform(?:-(?:gpu|cpu|none))?$/.test(b)) return 35;
-	if (/^blur(?:-|$)/.test(b) || /^backdrop-/.test(b) || /^filter(?:-|$)/.test(b) || /^brightness-/.test(b) || /^contrast-/.test(b) || /^grayscale(?:-|$)/.test(b) || /^hue-rotate-/.test(b) || /^invert(?:-|$)/.test(b) || /^saturate-/.test(b) || /^sepia(?:-|$)/.test(b)) return 40;
-	if (/^will-change/.test(b)) return 50;
+	if (/^blur(?:-|$)/.test(b) || b.startsWith("backdrop-") || /^filter(?:-|$)/.test(b) || b.startsWith("brightness-") || b.startsWith("contrast-") || /^grayscale(?:-|$)/.test(b) || b.startsWith("hue-rotate-") || /^invert(?:-|$)/.test(b) || b.startsWith("saturate-") || /^sepia(?:-|$)/.test(b)) return 40;
+	if (b.startsWith("will-change")) return 50;
 	return 99;
 }
 /**
@@ -82,7 +82,7 @@ function classifyBareUtility(bareUtility) {
 	if (/^@container(?:\/[a-z][a-z0-9-]*)?$/i.test(b)) return "existence";
 	if (/^(?:hidden|contents|sr-only|not-sr-only|list-item|flow-root)$/.test(b) || /^(?:block|inline-block|inline)$/.test(b)) return "existence";
 	if (/^table(?:$|-)/.test(b)) return "existence";
-	if (/^contain-/.test(b)) return "existence";
+	if (b.startsWith("contain-")) return "existence";
 	if (/^(?:group|peer)(?:\/[a-z][a-z0-9-]*)?$/.test(b)) return "existence";
 	if (/^(?:static|relative|absolute|fixed|sticky)$/.test(b)) return "position";
 	if (/^-?(?:inset|top|right|bottom|left|start|end)(?:-|\/|$)/.test(b) || /^-?(?:inset-x|inset-y|inset-s|inset-e)-/.test(b)) return "position";
@@ -90,13 +90,13 @@ function classifyBareUtility(bareUtility) {
 	if (/^(?:flex|inline-flex|grid|inline-grid|subgrid|masonry)(?:$|-)/.test(b) || /^(?:items|justify|justify-items|justify-self|content|self|place|place-content|place-items|place-self)-/.test(b) || /^-?(?:gap|space-[xy]|col-|row-|grid-|auto-cols|auto-rows|order-|order$)/.test(b) || /^-?(?:auto-flow|grid-flow)-/.test(b) || /^(?:columns-|break-after|break-before|break-inside)-/.test(b) || /^(?:float|clear)-/.test(b) || /^(?:wrap-|flex-wrap|flex-nowrap|flex-row|flex-col|flex-auto|flex-initial|flex-none|flex-1|flex-\[)/.test(b) || /^container$/.test(b)) return "layout";
 	if (/^-?(?:w|h|min-w|max-w|min-h|max-h|size|aspect|shrink|grow|basis)-/.test(b) || /^(?:shrink|grow)(?:$|-)/.test(b) || /^-?overflow-/.test(b) || /^-?object-/.test(b)) return "sizing";
 	if (/^-?(?:p|px|py|pt|pb|pl|pr|ps|pe|m|mx|my|mt|mb|ml|mr|ms|me)-/.test(b)) return "spacing";
-	if (/^-?(?:rounded|border|ring|divide|inset-ring)(?:-|\/|$)/.test(b) || /^(?:rounded|border|ring|divide|inset-ring)$/.test(b) || /^ring-offset-/.test(b)) return "shape";
+	if (/^-?(?:rounded|border|ring|divide|inset-ring)(?:-|\/|$)/.test(b) || /^(?:rounded|border|ring|divide|inset-ring)$/.test(b) || b.startsWith("ring-offset-")) return "shape";
 	if (/^-?bg-/.test(b) || /^(?:from|via|to)(?:-|\/|$)/.test(b) || /^bg-(?:linear|radial|conic)-/.test(b) || /^-?mask-/.test(b) || /^-?(?:fill|stroke)-/.test(b)) return "background";
 	if (/^-?(?:shadow|inset-shadow|drop-shadow|text-shadow)(?:-|\/|$)/.test(b) || /^(?:shadow|inset-shadow)$/.test(b) || /^-?outline(?:-|\/|$)/.test(b) || /^outline$/.test(b)) return "shadow";
-	if (/^-?(?:font|leading|tracking|list|indent|align|decoration|underline-offset|text-wrap|text-balance|text-pretty)-/.test(b) || /^-?(?:text-(?!shadow))/.test(b) || /^-?(?:whitespace|break|line-clamp|hyphens)-/.test(b) || /^(?:antialiased|subpixel-antialiased|italic|not-italic|overline|line-through|underline|no-underline|uppercase|lowercase|capitalize|normal-case|truncate|text-wrap|text-balance|text-pretty)$/.test(b) || /^text-wrap-/.test(b) || /^tabular-nums$|^slashed-zero$|^lining-nums$|^oldstyle-nums$|^proportional-nums$/.test(b)) return "typography";
-	if (/^opacity(?:-|$)/.test(b) || /^mix-blend-/.test(b) || /^isolation(?:-|$)/.test(b) || b === "isolate" || /^transform(?:-(?:gpu|cpu|none))?$/.test(b) || /^-?(?:translate|scale|rotate|skew)-/.test(b) || /^perspective(?:-|$)/.test(b) || b === "transform-3d" || /^blur(?:-|$)/.test(b) || /^backdrop-/.test(b) || /^filter(?:-|$)/.test(b) || /^brightness-/.test(b) || /^contrast-/.test(b) || /^grayscale(?:-|$)/.test(b) || /^hue-rotate-/.test(b) || /^invert(?:-|$)/.test(b) || /^saturate-/.test(b) || /^sepia(?:-|$)/.test(b) || /^will-change/.test(b)) return "composite";
-	if (/^(?:transition|duration|ease|delay|animate)(?:-|$)/.test(b) || /^ease-/.test(b)) return "motion";
-	if (/^(?:cursor|pointer-events|select|touch|scroll|scroll-m|scroll-p|overscroll|snap|resize|field-sizing|appearance|scheme|color-scheme|accent|caret)(?:-|$)/.test(b) || /^(?:cursor|select|resize)$/.test(b) || /^scroll-behavior/.test(b) || /^scroll-snap/.test(b) || /^touch-action/.test(b) || b === "inert") return "behavior";
+	if (/^-?(?:font|leading|tracking|list|indent|align|decoration|underline-offset|text-wrap|text-balance|text-pretty)-/.test(b) || /^-?(?:text-(?!shadow))/.test(b) || /^-?(?:whitespace|break|line-clamp|hyphens)-/.test(b) || /^(?:antialiased|subpixel-antialiased|italic|not-italic|overline|line-through|underline|no-underline|uppercase|lowercase|capitalize|normal-case|truncate|text-wrap|text-balance|text-pretty)$/.test(b) || b.startsWith("text-wrap-") || /^tabular-nums$|^slashed-zero$|^lining-nums$|^oldstyle-nums$|^proportional-nums$/.test(b)) return "typography";
+	if (/^opacity(?:-|$)/.test(b) || b.startsWith("mix-blend-") || /^isolation(?:-|$)/.test(b) || b === "isolate" || /^transform(?:-(?:gpu|cpu|none))?$/.test(b) || /^-?(?:translate|scale|rotate|skew)-/.test(b) || /^perspective(?:-|$)/.test(b) || b === "transform-3d" || /^blur(?:-|$)/.test(b) || b.startsWith("backdrop-") || /^filter(?:-|$)/.test(b) || b.startsWith("brightness-") || b.startsWith("contrast-") || /^grayscale(?:-|$)/.test(b) || b.startsWith("hue-rotate-") || /^invert(?:-|$)/.test(b) || b.startsWith("saturate-") || /^sepia(?:-|$)/.test(b) || b.startsWith("will-change")) return "composite";
+	if (/^(?:transition|duration|ease|delay|animate)(?:-|$)/.test(b) || b.startsWith("ease-")) return "motion";
+	if (/^(?:cursor|pointer-events|select|touch|scroll|scroll-m|scroll-p|overscroll|snap|resize|field-sizing|appearance|scheme|color-scheme|accent|caret)(?:-|$)/.test(b) || /^(?:cursor|select|resize)$/.test(b) || b.startsWith("scroll-behavior") || b.startsWith("scroll-snap") || b.startsWith("touch-action") || b === "inert") return "behavior";
 	return "other";
 }
 /**
@@ -106,7 +106,7 @@ function classifyBareUtility(bareUtility) {
 * Pure arbitrary **properties** (`[--x]:`, `[color:red]`) have no `&` in the leading `[…]` segment.
 */
 function isArbitraryParentSelectorStateToken(token) {
-	if (/^\[&/.test(token)) return true;
+	if (token.startsWith("[&")) return true;
 	if (!token.startsWith("[")) return false;
 	const colonIdx = indexOfFirstVariantColon(token);
 	if (colonIdx === -1 || colonIdx === 0 || token[colonIdx - 1] !== "]") return false;

package/dist/arrange/output.mjs

@@ -1,6 +1,6 @@
-import { logger } from "../core/logger.mjs";
 import "./domain/constants.mjs";
 import { lineOf } from "./domain/ast/helpers.mjs";
+import { logger } from "../core/logger.mjs";
 import path from "node:path";
 //#region src/arrange/output.ts
 /**
@@ -30,13 +30,21 @@ function printAnalyzeReport(resolvedTargetPath, report) {
 function printSyncResult(result, write) {
 	logger.out(`\nTotal: ${result.filePaths.length} file(s), ${result.totalFound} site(s) (cn/tv/JSX className) to review.`);
 	if (write) logger.out(`Applied: ${result.totalChanged} site(s) updated.`);
-	else logger.out(`(Run "apply" to write changes, or "pnpm cli:arrange-apply" / "pnpm exec codefast arrange apply")`);
+	else logger.out(`(Re-run without --dry-run to write changes, or "pnpm cli:arrange" / "pnpm exec codefast arrange")`);
 	if (write ? result.totalChanged > 0 : result.totalFound > 0) logger.out("Note: class order may change across concern groups — smoke-test the UI if you rely on cascade order.");
 	if (result.hookError !== null) logger.err(result.hookError);
 }
 /**
 * @since 0.3.16-canary.0
 */
+function printSimplifyResult(result, write) {
+	logger.out(`\nTotal: ${result.filePaths.length} file(s), ${result.totalFound} site(s) to simplify.`);
+	if (write) logger.out(`Applied: ${result.totalChanged} site(s) updated.`);
+	else logger.out(`(Run "simplify" to write changes, or "pnpm cli:arrange-simplify" / "pnpm exec codefast arrange simplify")`);
+}
+/**
+* @since 0.3.16-canary.0
+*/
 function printGroupFilePreviewFromWork(work) {
 	printGroupFilePreviewBody({
 		filePath: work.filePath,
@@ -76,4 +84,4 @@ function printGroupFilePreviewBody(args) {
 	}
 }
 //#endregion
-export { printAnalyzeReport, printGroupFilePreviewFromWork, printSyncResult };
+export { printAnalyzeReport, printGroupFilePreviewFromWork, printSimplifyResult, printSyncResult };

package/dist/arrange/process-file.mjs

@@ -1,6 +1,6 @@
 import { parseDomainSourceFile } from "./source-parse.mjs";
-import { buildGroupFileUnwrapState, countPersistedGroupFileEdits, groupFileDryRunNoEdits, groupFileEditsTouchJsxCn, groupFilePreviewTotals, groupFileWorkHasNothingToReport, mergeGroupFileBodyText, tryBuildGroupFileWorkPlan } from "./domain/grouping-service.mjs";
 import { ensureCnImport } from "./domain/imports.mjs";
+import { buildGroupFileUnwrapState, countPersistedGroupFileEdits, groupFileDryRunNoEdits, groupFileEditsTouchJsxCn, groupFilePreviewTotals, groupFileWorkHasNothingToReport, mergeGroupFileBodyText, tryBuildGroupFileWorkPlan } from "./domain/grouping-service.mjs";
 //#region src/arrange/process-file.ts
 /**
 * @since 0.3.16-canary.0

package/dist/arrange/scan-target.mjs

@@ -3,13 +3,22 @@ import { logger } from "../core/logger.mjs";
 import { walkTsxFiles } from "../core/workspace/typescript-walk.mjs";
 import path from "node:path";
 //#region src/arrange/scan-target.ts
+const TEST_FILE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/**
+* Test/spec files are excluded from directory scans: arrange rewrites class strings,
+* and a `cn(...)` inside an assertion (e.g. `expect(cn("a", "b"))`) is intentional test
+* data, not styling to reformat. An explicit single-file target is still honored.
+*/
+function isTestFile(filePath) {
+	return TEST_FILE_PATTERN.test(path.basename(filePath));
+}
 /**
 * @since 0.3.16-canary.0
 */
 function scanArrangeTargets(fs, targetPath) {
 	const resolvedTargetPath = path.resolve(targetPath);
 	if (fs.statSync(resolvedTargetPath).isDirectory()) try {
-		return walkTsxFiles(resolvedTargetPath, fs);
+		return walkTsxFiles(resolvedTargetPath, fs).filter((filePath) => !isTestFile(filePath));
 	} catch (caughtError) {
 		logger.err(`[file-walker] ${messageFrom(caughtError)}`);
 		throw caughtError;

package/dist/arrange/simplify-process-file.mjs

@@ -0,0 +1,35 @@
+import { applyEditsDescending } from "../core/source-text-edit.mjs";
+import { parseDomainSourceFile } from "./source-parse.mjs";
+import { collectSimplifyTargets } from "./domain/ast/simplify-targets.mjs";
+import { dropCnImportIfUnused } from "./domain/imports.mjs";
+//#region src/arrange/simplify-process-file.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function processArrangeSimplifyFile(fs, args) {
+	const { filePath, write } = args;
+	const sourceText = fs.readFileSync(filePath, "utf8");
+	const meaningful = collectSimplifyTargets(parseDomainSourceFile(filePath, sourceText)).filter((edit) => sourceText.slice(edit.start, edit.end) !== edit.replacement);
+	const textAfterEdits = meaningful.length > 0 ? applyEditsDescending(sourceText, meaningful) : sourceText;
+	const textAfterImportDrop = dropCnImportIfUnused(parseDomainSourceFile(filePath, textAfterEdits));
+	const importDropped = textAfterImportDrop !== textAfterEdits;
+	const totalFound = meaningful.length + (importDropped ? 1 : 0);
+	if (totalFound === 0) return {
+		filePath,
+		totalFound: 0,
+		changed: 0
+	};
+	if (!write) return {
+		filePath,
+		totalFound,
+		changed: 0
+	};
+	fs.writeFileSync(filePath, textAfterImportDrop, "utf8");
+	return {
+		filePath,
+		totalFound,
+		changed: totalFound
+	};
+}
+//#endregion
+export { processArrangeSimplifyFile };

package/dist/arrange/simplify-sync.mjs

@@ -0,0 +1,32 @@
+import { scanArrangeTargets } from "./scan-target.mjs";
+import { ok } from "../core/result.mjs";
+import { processArrangeSimplifyFile } from "./simplify-process-file.mjs";
+//#region src/arrange/simplify-sync.ts
+/**
+* @since 0.3.16-canary.0
+*/
+async function runArrangeSimplify(fs, args) {
+	const filePaths = scanArrangeTargets(fs, args.targetPath);
+	const modifiedFiles = [];
+	let totalFound = 0;
+	let totalChanged = 0;
+	for (const filePath of filePaths) {
+		const result = processArrangeSimplifyFile(fs, {
+			filePath,
+			write: args.write
+		});
+		totalFound += result.totalFound;
+		totalChanged += result.changed;
+		if (result.changed > 0) modifiedFiles.push(result.filePath);
+	}
+	return ok({
+		filePaths,
+		modifiedFiles,
+		totalFound,
+		totalChanged,
+		hookError: null,
+		previewPlans: []
+	});
+}
+//#endregion
+export { runArrangeSimplify };

package/dist/arrange/suggest.mjs

@@ -1,5 +1,5 @@
-import { suggestCnGroups, summarizeGroupBucketLabels } from "./domain/grouping.mjs";
 import { formatArray, formatCnCall } from "./domain/source-text-formatters.mjs";
+import { suggestCnGroups, summarizeGroupBucketLabels } from "./domain/grouping.mjs";
 //#region src/arrange/suggest.ts
 /**
 * @since 0.3.16-canary.0

package/dist/arrange/sync.mjs

@@ -1,6 +1,6 @@
 import { messageFrom } from "../core/errors.mjs";
-import { ok } from "../core/result.mjs";
 import { scanArrangeTargets } from "./scan-target.mjs";
+import { ok } from "../core/result.mjs";
 import { processArrangeGroupFile } from "./process-file.mjs";
 //#region src/arrange/sync.ts
 async function runOnAfterWriteHook(hook, modifiedFiles) {

package/dist/arrange/workspace.mjs

@@ -1,8 +1,8 @@
 import { AppError, messageFrom } from "../core/errors.mjs";
 import { err, ok } from "../core/result.mjs";
+import { resolveArrangeTargetPath } from "./resolve-target.mjs";
 import { loadCodefastConfig } from "../core/config.mjs";
 import { findRepoRoot } from "../core/workspace/resolver.mjs";
-import { resolveArrangeTargetPath } from "./resolve-target.mjs";
 //#region src/arrange/workspace.ts
 /**
 * @since 0.3.16-canary.0

package/dist/cli.mjs

@@ -22,7 +22,7 @@ function readVersion() {
 */
 async function runCli(argv) {
 	const program = new Command();
-	program.name("codefast").description("Codefast monorepo developer CLI").version(readVersion()).option("--no-color", "Disable ANSI color output").configureHelp({ sortSubcommands: true }).showHelpAfterError("(use --help for usage)");
+	program.name("codefast").description("Codefast monorepo developer CLI").version(readVersion()).option("--no-color", "Disable ANSI color output").enablePositionalOptions().configureHelp({ sortSubcommands: true }).showHelpAfterError("(use --help for usage)");
 	program.addCommand(createArrangeCommand());
 	program.addCommand(createMirrorCommand());
 	program.addCommand(createTagCommand());

package/dist/core/cli/result-handle.mjs

@@ -1,6 +1,6 @@
+import { logger } from "../logger.mjs";
 import { formatAppError } from "./format-error.mjs";
 import "../exit-codes.mjs";
-import { logger } from "../logger.mjs";
 import { isVerboseCliDiagnostics } from "../verbose-diagnostics.mjs";
 import process from "node:process";
 //#region src/core/cli/result-handle.ts

package/dist/core/source-text-edit.mjs

@@ -47,7 +47,7 @@ function endAfterOptionalCommaFollowingInSource(source, tokenEnd) {
 * @since 0.3.16-canary.0
 */
 function applyEditsDescending(sourceText, edits) {
-	const sorted = [...edits].sort((editA, editB) => editB.start - editA.start);
+	const sorted = [...edits].toSorted((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;

package/dist/core/workspace/resolver.mjs

@@ -92,13 +92,13 @@ async function readWorkspaceYaml(rootDir, fs) {
 	try {
 		raw = await fs.readFile(workspaceYamlPath, "utf8");
 	} catch (caughtReadError) {
-		throw new Error(`Failed to read ${wf}: ${messageFrom(caughtReadError)}`);
+		throw new Error(`Failed to read ${wf}: ${messageFrom(caughtReadError)}`, { cause: caughtReadError });
 	}
 	let doc;
 	try {
 		doc = parse(raw);
 	} catch (caughtYamlParseError) {
-		throw new Error(`Failed to parse ${wf}: ${messageFrom(caughtYamlParseError)}`);
+		throw new Error(`Failed to parse ${wf}: ${messageFrom(caughtYamlParseError)}`, { cause: caughtYamlParseError });
 	}
 	if (doc === null || doc === void 0) throw new Error(`${wf} must define a mapping at the document root`);
 	return {
@@ -153,7 +153,7 @@ async function listWorkspacePackageDirectories(rootDirectoryPathAbsolute, fs, su
 				if (!suppressGlobPermissionDiagnostics) logger.out(`⚠ Skipping workspace glob "${pattern}" (${messageFrom(caughtGlobError)})`);
 				continue;
 			}
-			throw new Error(`Invalid workspace glob "${pattern}": ${messageFrom(caughtGlobError)}`);
+			throw new Error(`Invalid workspace glob "${pattern}": ${messageFrom(caughtGlobError)}`, { cause: caughtGlobError });
 		}
 		for (const matchedPath of matches) {
 			const posix = toPosix(matchedPath);

package/dist/mirror/cli-result.mjs

@@ -9,10 +9,11 @@ function exitCodeForMirrorSyncResult(stats) {
 /**
 * @since 0.3.16-canary.0
 */
-function formatMirrorSyncJsonOutput(stats, elapsedSeconds) {
+function formatMirrorSyncJsonOutput(stats, elapsedSeconds, write = true) {
 	return JSON.stringify({
 		schemaVersion: 1,
 		ok: stats.packagesErrored === 0,
+		write,
 		elapsedSeconds,
 		stats
 	});

package/dist/mirror/cli-schema.mjs

@@ -6,7 +6,8 @@ import { z } from "zod";
 const mirrorSyncRunRequestSchema = z.object({
 	rootDir: z.string().min(1),
 	packageFilter: z.string().optional(),
-	config: z.unknown().optional()
+	config: z.unknown().optional(),
+	write: z.boolean().optional()
 });
 //#endregion
 export { mirrorSyncRunRequestSchema };

package/dist/mirror/command.mjs

@@ -1,14 +1,14 @@
-import { parseWithSchema } from "../core/schema-parse.mjs";
 import { logger } from "../core/logger.mjs";
+import { readOptionalPositionalArg } from "../core/cli/positional.mjs";
 import { consumeCliAppError } from "../core/cli/result-handle.mjs";
 import { nodeFilesystem } from "../core/filesystem/node.mjs";
-import { readOptionalPositionalArg } from "../core/cli/positional.mjs";
+import { parseWithSchema } from "../core/schema-parse.mjs";
 import { globalCliCommanderOptionsSchema } from "../core/cli/global-options.mjs";
-import { prepareMirrorSync } from "./prepare.mjs";
-import { runMirrorSync } from "./sync.mjs";
-import { mirrorSyncRunRequestSchema } from "./cli-schema.mjs";
 import { exitCodeForMirrorSyncResult, formatMirrorSyncJsonOutput } from "./cli-result.mjs";
+import { mirrorSyncRunRequestSchema } from "./cli-schema.mjs";
 import { MirrorSyncProgressPresenter } from "./output.mjs";
+import { prepareMirrorSync } from "./prepare.mjs";
+import { runMirrorSync } from "./sync.mjs";
 import process from "node:process";
 import { Command } from "commander";
 //#region src/mirror/command.ts
@@ -16,8 +16,7 @@ import { Command } from "commander";
 * @since 0.3.16-canary.0
 */
 function createMirrorCommand() {
-	const cmd = new Command("mirror").description("Keep package manifests aligned with what you ship");
-	cmd.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).option("--json", "Print one JSON summary on stdout (suppresses human progress)", false).action(async (packageArg, opts, command) => {
+	return new Command("mirror").description("Write package.json exports from dist/ for workspace packages").argument("[package]", "Optional package path relative to repo root (e.g. packages/ui)").option("--dry-run", "Report what would change without writing package.json", false).option("-v, --verbose", "Print extra diagnostics", false).option("--json", "Print one JSON summary on stdout (suppresses human progress)", false).action(async (packageArg, opts, command) => {
 		const globalOptionsOutcome = parseWithSchema(globalCliCommanderOptionsSchema, command.optsWithGlobals?.() ?? command.opts());
 		if (!consumeCliAppError(globalOptionsOutcome)) return;
 		const prelude = await prepareMirrorSync(nodeFilesystem, {
@@ -26,11 +25,13 @@ function createMirrorCommand() {
 			globals: globalOptionsOutcome.value
 		});
 		if (!consumeCliAppError(prelude)) return;
+		const write = !opts.dryRun;
 		const { rootDir, config, packageFilter } = prelude.value;
 		const parsed = parseWithSchema(mirrorSyncRunRequestSchema, {
 			rootDir,
 			config: config.mirror ?? {},
-			packageFilter
+			packageFilter,
+			write
 		});
 		if (!consumeCliAppError(parsed)) return;
 		const json = !!opts.json;
@@ -40,7 +41,8 @@ function createMirrorCommand() {
 		const listener = json ? void 0 : progressPresenter;
 		if (!json) progressPresenter.configure({
 			noColor,
-			verbose
+			verbose,
+			dryRun: !write
 		});
 		const startTime = performance.now();
 		const outcome = await runMirrorSync(nodeFilesystem, {
@@ -48,10 +50,9 @@ function createMirrorCommand() {
 			listener
 		});
 		if (!consumeCliAppError(outcome)) return;
-		if (json) logger.out(formatMirrorSyncJsonOutput(outcome.value, (performance.now() - startTime) / 1e3));
+		if (json) logger.out(formatMirrorSyncJsonOutput(outcome.value, (performance.now() - startTime) / 1e3, write));
 		process.exitCode = exitCodeForMirrorSyncResult(outcome.value);
 	});
-	return cmd;
 }
 //#endregion
 export { createMirrorCommand };

package/dist/mirror/domain/exports.mjs

@@ -202,7 +202,7 @@ async function generateExports(fileSystemService, distDir, pathTransform, cssCon
 		moduleExportsBySpecifier[exportPath] = exportEntry;
 		originalPathBySpecifier[exportPath] = originalExportPath;
 	}
-	let sortedSpecifiers = Object.keys(moduleExportsBySpecifier).sort((leftSpecifier, rightSpecifier) => compareExportSortKeys(getExportSortKey(leftSpecifier, pathTransform), getExportSortKey(rightSpecifier, pathTransform)));
+	let sortedSpecifiers = Object.keys(moduleExportsBySpecifier).toSorted((leftSpecifier, rightSpecifier) => compareExportSortKeys(getExportSortKey(leftSpecifier, pathTransform), getExportSortKey(rightSpecifier, pathTransform)));
 	const sortedExports = {};
 	for (const exportKey of sortedSpecifiers) sortedExports[exportKey] = moduleExportsBySpecifier[exportKey];
 	const cssExports = await generateCssExports(fileSystemService, distDir, cssConfig ?? { enabled: true });
@@ -210,7 +210,7 @@ async function generateExports(fileSystemService, distDir, pathTransform, cssCon
 	for (const [specifier, mappedPath] of Object.entries(extraExports || {})) if (specifier !== "./package.json") sortedExports[specifier] = mappedPath;
 	for (const cssSpecifier of Object.keys(cssExports)) if (!(cssSpecifier in originalPathBySpecifier)) originalPathBySpecifier[cssSpecifier] = cssSpecifier;
 	for (const extraSpecifier of Object.keys(extraExports || {})) if (extraSpecifier !== "./package.json" && !(extraSpecifier in originalPathBySpecifier)) originalPathBySpecifier[extraSpecifier] = extraSpecifier;
-	sortedSpecifiers = Object.keys(sortedExports).filter((exportKey) => exportKey !== PACKAGE_JSON_EXPORT).sort((leftSpecifier, rightSpecifier) => compareExportSortKeys(getExportSortKey(leftSpecifier, pathTransform), getExportSortKey(rightSpecifier, pathTransform)));
+	sortedSpecifiers = Object.keys(sortedExports).filter((exportKey) => exportKey !== PACKAGE_JSON_EXPORT).toSorted((leftSpecifier, rightSpecifier) => compareExportSortKeys(getExportSortKey(leftSpecifier, pathTransform), getExportSortKey(rightSpecifier, pathTransform)));
 	const finalExports = {};
 	for (const exportKey of sortedSpecifiers) finalExports[exportKey] = sortedExports[exportKey];
 	finalExports[PACKAGE_JSON_EXPORT] = PACKAGE_JSON_EXPORT;

package/dist/mirror/output.mjs

@@ -8,12 +8,15 @@ const cliLogger = logger;
 var MirrorSyncProgressPresenter = class {
 	reporter = new MirrorSyncReporter();
 	verbose = false;
+	dryRun = false;
 	configure(options) {
 		this.verbose = options.verbose;
+		this.dryRun = options.dryRun;
 		this.reporter.configureMirrorColors(options.noColor);
 	}
 	onBanner() {
 		this.reporter.mirrorBanner(cliLogger);
+		if (this.dryRun) this.reporter.mirrorDryRunNotice(cliLogger);
 	}
 	onProcessingMode(mode) {
 		this.reporter.mirrorProcessingMode(cliLogger, mode);

package/dist/mirror/supplement-exports.mjs

@@ -70,7 +70,7 @@ function buildSupplementedEntry(specifier, existing, modulePath, distDir, fs, op
 /**
 * @since 0.3.16-canary.0
 */
-async function supplementExportsInPackageJson(fs, packageJsonPath, packageDir, options) {
+async function supplementExportsInPackageJson(fs, packageJsonPath, packageDir, options, write = true) {
 	const raw = await fs.readFile(packageJsonPath, "utf8");
 	const existingExports = JSON.parse(raw).exports;
 	if (!existingExports || typeof existingExports !== "object" || Array.isArray(existingExports)) return { supplementedSpecifiers: [] };
@@ -94,7 +94,7 @@ async function supplementExportsInPackageJson(fs, packageJsonPath, packageDir, o
 		generatedExports: supplementedExports,
 		managedExportSpecifiers: Object.keys(supplementedExports),
 		originalPathBySpecifier
-	});
+	}, write);
 	return { supplementedSpecifiers };
 }
 /**

package/dist/mirror/sync-reporter.mjs

@@ -14,7 +14,7 @@ const ANSI = {
 	brightCyan: "\x1B[96m"
 };
 /**
-* Console implementation: ANSI styling and layout for mirror sync.
+* Console implementation: ANSI styling and layout for the mirror command.
 *
 * @since 0.3.16-canary.0
 */
@@ -27,6 +27,9 @@ var MirrorSyncReporter = class {
 		logger.out(`\n${this.paint("📦 Mirror — package exports", ANSI.bold + ANSI.cyan)}`);
 		logger.out(`${this.paint("═".repeat(60), ANSI.dim)}\n`);
 	}
+	mirrorDryRunNotice(logger) {
+		logger.out(`${this.paint("Dry run — no files will be written.", ANSI.yellow)}\n`);
+	}
 	mirrorProcessingMode(logger, mode) {
 		if (mode.kind === "single") {
 			logger.out(`${this.paint("Processing single package...", ANSI.dim)}\n`);

package/dist/mirror/sync-workspace-package.mjs

@@ -1,16 +1,16 @@
 import { messageFrom } from "../core/errors.mjs";
+import { createMirrorDistFilesystem } from "./dist-filesystem-impl.mjs";
 import { DIST_DIR, PACKAGE_JSON } from "./domain/constants.mjs";
 import { createPathTransform, generateExports } from "./domain/exports.mjs";
 import { resolvePackageDisplayName } from "./domain/package-display-name.mjs";
 import { writePackageJsonExportsAtomic } from "./write-exports.mjs";
-import { createMirrorDistFilesystem } from "./dist-filesystem-impl.mjs";
 import { buildSourcePathResolver, supplementExportsInPackageJson } from "./supplement-exports.mjs";
 import path from "node:path";
 //#region src/mirror/sync-workspace-package.ts
 /**
 * @since 0.3.16-canary.0
 */
-async function syncExportsForWorkspacePackage(fs, rootDir, packagePathStr, config) {
+async function syncExportsForWorkspacePackage(fs, rootDir, packagePathStr, config, write = true) {
 	const pathJoin = path.join;
 	const pathResolve = path.resolve;
 	const pathBasename = path.basename;
@@ -79,7 +79,7 @@ async function syncExportsForWorkspacePackage(fs, rootDir, packagePathStr, confi
 			resolveSourcePath
 		};
 		if (pkgConfig?.preserve) {
-			const { supplementedSpecifiers } = await supplementExportsInPackageJson(fs, packageJsonPath, packageDir, exportOptions);
+			const { supplementedSpecifiers } = await supplementExportsInPackageJson(fs, packageJsonPath, packageDir, exportOptions, write);
 			pkgStats.totalExports = supplementedSpecifiers.length;
 		} else {
 			const pathTransform = createPathTransform(pkgConfig?.strip);
@@ -93,7 +93,7 @@ async function syncExportsForWorkspacePackage(fs, rootDir, packagePathStr, confi
 				generatedExports: generatedExports.exports,
 				managedExportSpecifiers: Object.keys(generatedExports.exports),
 				originalPathBySpecifier: generatedExports.originalPathBySpecifier
-			});
+			}, write);
 			pkgStats.jsModules = generatedExports.jsCount;
 			pkgStats.cssExports = generatedExports.cssCount;
 			pkgStats.extraExports = Object.keys(extraExports).length;

package/dist/mirror/sync.mjs

@@ -12,6 +12,7 @@ import path from "node:path";
 async function runMirrorSync(fs, input) {
 	const config = input.config ?? {};
 	const { listener } = input;
+	const write = input.write ?? true;
 	listener?.onBanner();
 	const startTime = performance.now();
 	try {
@@ -47,7 +48,7 @@ async function runMirrorSync(fs, input) {
 		}
 		let ordinal = 1;
 		for (const pkgPath of targetPackages) {
-			const pkgStats = await syncExportsForWorkspacePackage(fs, input.rootDir, pkgPath, config);
+			const pkgStats = await syncExportsForWorkspacePackage(fs, input.rootDir, pkgPath, config, write);
 			stats.packageDetails.push(pkgStats);
 			listener?.onPackageComplete(pkgStats, ordinal, targetPackages.length);
 			ordinal++;