@codefast/cli 0.3.14 → 0.3.16-canary.0

package/dist/core/workspace/resolver.mjs

@@ -0,0 +1,177 @@
+import { messageFrom } from "../errors.mjs";
+import { logger } from "../logger.mjs";
+import { globSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import picomatch from "picomatch";
+import { parse } from "yaml";
+//#region src/core/workspace/resolver.ts
+/**
+* Resolve the monorepo root (directory containing `pnpm-workspace.yaml`).
+*
+* @since 0.3.16-canary.0
+*/
+function findRepoRoot(fromDirectory, fs) {
+	const candidates = [path.dirname(fileURLToPath(import.meta.url)), fromDirectory];
+	for (const start of candidates) {
+		let dir = path.resolve(start);
+		for (;;) {
+			if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
+			const parent = path.dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	}
+	throw new Error(`Could not locate monorepo root (missing pnpm-workspace.yaml). Searched from: ${candidates.join(", ")}`);
+}
+const workspaceYamlFileName = "pnpm-workspace.yaml";
+const defaultIncludePatterns = ["packages/*"];
+const packageJsonFileName = "package.json";
+function toPosix(filePath) {
+	return filePath.split(path.sep).join("/");
+}
+function isGlobPermissionError(caughtError) {
+	if (typeof caughtError !== "object" || caughtError === null || !("code" in caughtError)) return false;
+	const code = caughtError.code;
+	return code === "EACCES" || code === "EPERM";
+}
+function workspacePatternToPackageJsonGlob(pattern) {
+	const normalizedPattern = toPosix(pattern.trim()).replace(/\/+$/, "");
+	if (!normalizedPattern) return `**/${packageJsonFileName}`;
+	return `${normalizedPattern}/${packageJsonFileName}`;
+}
+function splitPnpmWorkspacePackagesArray(raw) {
+	const include = [];
+	const exclude = [];
+	if (!Array.isArray(raw)) return {
+		include,
+		exclude
+	};
+	for (const entry of raw) {
+		if (typeof entry !== "string") continue;
+		const trimmed = entry.trim();
+		if (!trimmed) continue;
+		if (trimmed.startsWith("!")) exclude.push(trimmed.slice(1).trim());
+		else include.push(trimmed);
+	}
+	return {
+		include,
+		exclude
+	};
+}
+function parsePnpmWorkspaceDocument(doc) {
+	const wf = workspaceYamlFileName;
+	if (doc === null || doc === void 0) throw new Error(`${wf} root document must be an object (got empty or null)`);
+	if (typeof doc !== "object" || Array.isArray(doc)) throw new Error(`${wf} root must be a mapping, not an array or scalar`);
+	const parsedDoc = doc;
+	if (!Object.prototype.hasOwnProperty.call(parsedDoc, "packages")) return {
+		include: [],
+		exclude: [],
+		hasPackagesKey: false,
+		isEmptyPackagesArray: false
+	};
+	const pkgs = parsedDoc.packages;
+	if (!Array.isArray(pkgs)) throw new Error(`${wf} field "packages" must be an array`);
+	if (pkgs.length === 0) return {
+		include: [],
+		exclude: [],
+		hasPackagesKey: true,
+		isEmptyPackagesArray: true
+	};
+	return {
+		...splitPnpmWorkspacePackagesArray(pkgs),
+		hasPackagesKey: true,
+		isEmptyPackagesArray: false
+	};
+}
+async function readWorkspaceYaml(rootDir, fs) {
+	const wf = workspaceYamlFileName;
+	const workspaceYamlPath = path.join(rootDir, wf);
+	if (!fs.existsSync(workspaceYamlPath)) return { exists: false };
+	let raw;
+	try {
+		raw = await fs.readFile(workspaceYamlPath, "utf8");
+	} catch (caughtReadError) {
+		throw new Error(`Failed to read ${wf}: ${messageFrom(caughtReadError)}`);
+	}
+	let doc;
+	try {
+		doc = parse(raw);
+	} catch (caughtYamlParseError) {
+		throw new Error(`Failed to parse ${wf}: ${messageFrom(caughtYamlParseError)}`);
+	}
+	if (doc === null || doc === void 0) throw new Error(`${wf} must define a mapping at the document root`);
+	return {
+		exists: true,
+		doc
+	};
+}
+/**
+* @since 0.3.16-canary.0
+*/
+async function listWorkspacePackageDirectories(rootDirectoryPathAbsolute, fs, suppressGlobPermissionDiagnostics) {
+	const workspaceYaml = await readWorkspaceYaml(rootDirectoryPathAbsolute, fs);
+	const defInc = defaultIncludePatterns;
+	let include;
+	let exclude;
+	let layoutSource;
+	const hasPnpmWorkspaceYamlFile = workspaceYaml.exists;
+	if (!workspaceYaml.exists) {
+		include = [...defInc];
+		exclude = [];
+		layoutSource = "default-patterns";
+	} else {
+		const parsed = parsePnpmWorkspaceDocument(workspaceYaml.doc);
+		if (!parsed.hasPackagesKey) {
+			include = [...defInc];
+			exclude = [];
+			layoutSource = "default-patterns";
+		} else if (parsed.isEmptyPackagesArray) return {
+			packageDirectoryPathsAbsolute: [],
+			layoutSource: "declared-empty",
+			hasPnpmWorkspaceYamlFile: true
+		};
+		else {
+			include = parsed.include;
+			exclude = parsed.exclude;
+			layoutSource = "pnpm-workspace-yaml";
+		}
+	}
+	const foundRelativePosixPackageRoots = /* @__PURE__ */ new Set();
+	const globOpts = {
+		cwd: rootDirectoryPathAbsolute,
+		posix: true,
+		...path.sep === "\\" ? { windowsPathsNoEscape: true } : {}
+	};
+	for (const pattern of include) {
+		const globPat = workspacePatternToPackageJsonGlob(pattern);
+		let matches;
+		try {
+			matches = globSync(globPat, globOpts);
+		} catch (caughtGlobError) {
+			if (isGlobPermissionError(caughtGlobError)) {
+				if (!suppressGlobPermissionDiagnostics) logger.out(`⚠ Skipping workspace glob "${pattern}" (${messageFrom(caughtGlobError)})`);
+				continue;
+			}
+			throw new Error(`Invalid workspace glob "${pattern}": ${messageFrom(caughtGlobError)}`);
+		}
+		for (const matchedPath of matches) {
+			const posix = toPosix(matchedPath);
+			const suffix = `/${packageJsonFileName}`;
+			if (!posix.endsWith(suffix)) continue;
+			const rel = posix.slice(0, -suffix.length);
+			if (!rel) continue;
+			foundRelativePosixPackageRoots.add(rel);
+		}
+	}
+	const excludeMatchers = exclude.map((pat) => picomatch(pat, { dot: true }));
+	const filteredRelative = [...foundRelativePosixPackageRoots].filter((rel) => !excludeMatchers.some((isMatch) => isMatch(rel)));
+	filteredRelative.sort((a, b) => a.localeCompare(b));
+	return {
+		packageDirectoryPathsAbsolute: filteredRelative.map((rel) => path.resolve(rootDirectoryPathAbsolute, rel.split("/").join(path.sep))),
+		layoutSource,
+		hasPnpmWorkspaceYamlFile
+	};
+}
+//#endregion
+export { findRepoRoot, listWorkspacePackageDirectories };

package/dist/core/workspace/typescript-walk.mjs

@@ -0,0 +1,36 @@
+import path from "node:path";
+//#region src/core/workspace/typescript-walk.ts
+const defaultSkipDirectoryNames = new Set([
+	"node_modules",
+	"dist",
+	".git",
+	".turbo",
+	".next",
+	".cache",
+	"out",
+	"build",
+	"coverage",
+	".vercel",
+	".output"
+]);
+/**
+* @since 0.3.16-canary.0
+*/
+function walkTsxFiles(rootDirectoryPath, fs) {
+	const result = [];
+	visitTsxPaths(result, rootDirectoryPath, fs);
+	return result;
+}
+function visitTsxPaths(result, entryPath, fs) {
+	if (fs.statSync(entryPath).isDirectory()) {
+		for (const childName of fs.readdirSync(entryPath)) {
+			if (defaultSkipDirectoryNames.has(childName)) continue;
+			visitTsxPaths(result, path.join(entryPath, childName), fs);
+		}
+		return;
+	}
+	if (entryPath.endsWith(".d.ts")) return;
+	if (entryPath.endsWith(".tsx") || entryPath.endsWith(".ts")) result.push(entryPath);
+}
+//#endregion
+export { walkTsxFiles };

package/dist/mirror/cli-result.mjs

@@ -0,0 +1,21 @@
+import "../core/exit-codes.mjs";
+//#region src/mirror/cli-result.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function exitCodeForMirrorSyncResult(stats) {
+	return stats.packagesErrored > 0 ? 1 : 0;
+}
+/**
+* @since 0.3.16-canary.0
+*/
+function formatMirrorSyncJsonOutput(stats, elapsedSeconds) {
+	return JSON.stringify({
+		schemaVersion: 1,
+		ok: stats.packagesErrored === 0,
+		elapsedSeconds,
+		stats
+	});
+}
+//#endregion
+export { exitCodeForMirrorSyncResult, formatMirrorSyncJsonOutput };

package/dist/{lib/mirror/presentation/mirror-cli.schema.mjs → mirror/cli-schema.mjs}

@@ -1,10 +1,10 @@
 import { z } from "zod";
-//#region src/lib/mirror/presentation/mirror-cli.schema.ts
+//#region src/mirror/cli-schema.ts
+/**
+* @since 0.3.16-canary.0
+*/
 const mirrorSyncRunRequestSchema = z.object({
 	rootDir: z.string().min(1),
-	verbose: z.boolean().optional(),
-	noColor: z.boolean().optional(),
-	json: z.boolean().optional(),
 	packageFilter: z.string().optional(),
 	config: z.unknown().optional()
 });

package/dist/mirror/command.mjs

@@ -0,0 +1,57 @@
+import { parseWithSchema } from "../core/schema-parse.mjs";
+import { logger } from "../core/logger.mjs";
+import { consumeCliAppError } from "../core/cli/result-handle.mjs";
+import { nodeFilesystem } from "../core/filesystem/node.mjs";
+import { readOptionalPositionalArg } from "../core/cli/positional.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 { MirrorSyncProgressPresenter } from "./output.mjs";
+import process from "node:process";
+import { Command } from "commander";
+//#region src/mirror/command.ts
+/**
+* @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) => {
+		const globalOptionsOutcome = parseWithSchema(globalCliCommanderOptionsSchema, command.optsWithGlobals?.() ?? command.opts());
+		if (!consumeCliAppError(globalOptionsOutcome)) return;
+		const prelude = await prepareMirrorSync(nodeFilesystem, {
+			currentWorkingDirectory: process.cwd(),
+			packageArg: readOptionalPositionalArg(packageArg),
+			globals: globalOptionsOutcome.value
+		});
+		if (!consumeCliAppError(prelude)) return;
+		const { rootDir, config, packageFilter } = prelude.value;
+		const parsed = parseWithSchema(mirrorSyncRunRequestSchema, {
+			rootDir,
+			config: config.mirror ?? {},
+			packageFilter
+		});
+		if (!consumeCliAppError(parsed)) return;
+		const json = !!opts.json;
+		const noColor = globalOptionsOutcome.value.color === false;
+		const verbose = !!opts.verbose;
+		const progressPresenter = new MirrorSyncProgressPresenter();
+		const listener = json ? void 0 : progressPresenter;
+		if (!json) progressPresenter.configure({
+			noColor,
+			verbose
+		});
+		const startTime = performance.now();
+		const outcome = await runMirrorSync(nodeFilesystem, {
+			...parsed.value,
+			listener
+		});
+		if (!consumeCliAppError(outcome)) return;
+		if (json) logger.out(formatMirrorSyncJsonOutput(outcome.value, (performance.now() - startTime) / 1e3));
+		process.exitCode = exitCodeForMirrorSyncResult(outcome.value);
+	});
+	return cmd;
+}
+//#endregion
+export { createMirrorCommand };

package/dist/mirror/dist-filesystem-impl.mjs

@@ -0,0 +1,42 @@
+import { normalizePath } from "./domain/path-normalizer.mjs";
+import { isDirentList } from "./domain/dirent-guard.mjs";
+import path from "node:path";
+//#region src/mirror/dist-filesystem-impl.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function createMirrorDistFilesystem(fs) {
+	return {
+		async listRelativeFilesRecursively(dirPath) {
+			try {
+				const raw = await fs.readdir(dirPath, {
+					recursive: true,
+					withFileTypes: true
+				});
+				if (!isDirentList(raw)) return [];
+				return raw.filter((dirent) => dirent.isFile()).map((dirent) => {
+					const fullPath = path.join(dirent.parentPath, dirent.name);
+					return normalizePath(path.relative(dirPath, fullPath));
+				});
+			} catch (caughtError) {
+				if (isKnownReadDirError(caughtError)) return [];
+				throw caughtError;
+			}
+		},
+		async isDirectoryCssOnly(distDir, dirPath) {
+			try {
+				const raw = await fs.readdir(path.join(distDir, dirPath), { withFileTypes: true });
+				if (!isDirentList(raw)) return false;
+				if (raw.length === 0) return true;
+				return raw.every((dirent) => dirent.isFile() && dirent.name.endsWith(".css"));
+			} catch {
+				return false;
+			}
+		}
+	};
+}
+function isKnownReadDirError(caughtError) {
+	return typeof caughtError === "object" && caughtError !== null && "code" in caughtError && (caughtError.code === "ENOENT" || caughtError.code === "EACCES");
+}
+//#endregion
+export { createMirrorDistFilesystem };

package/dist/{lib/mirror/domain/constants.domain.mjs → mirror/domain/constants.mjs}

@@ -1,16 +1,31 @@
-//#region src/lib/mirror/domain/constants.domain.ts
+//#region src/mirror/domain/constants.ts
+/**
+* @since 0.3.16-canary.0
+*/
 const DIST_DIR = "dist";
+/**
+* @since 0.3.16-canary.0
+*/
 const PACKAGE_JSON = "package.json";
+/**
+* @since 0.3.16-canary.0
+*/
 const VALID_JS_EXTENSIONS = new Set([
 	".js",
 	".mjs",
 	".cjs"
 ]);
+/**
+* @since 0.3.16-canary.0
+*/
 const VALID_DTS_EXTENSIONS = new Set([
 	".d.ts",
 	".d.mts",
 	".d.cts"
 ]);
+/**
+* @since 0.3.16-canary.0
+*/
 const PACKAGE_JSON_EXPORT = "./package.json";
 //#endregion
 export { DIST_DIR, PACKAGE_JSON, PACKAGE_JSON_EXPORT, VALID_DTS_EXTENSIONS, VALID_JS_EXTENSIONS };

package/dist/{lib/mirror/infrastructure/dirent-list.guard.mjs → mirror/domain/dirent-guard.mjs}

@@ -1,10 +1,13 @@
-//#region src/lib/mirror/infrastructure/dirent-list.guard.ts
+//#region src/mirror/domain/dirent-guard.ts
 /**
 * Narrow `fs.promises.readdir` overload result to `Dirent[]` when `withFileTypes: true`.
 * Accepts both historical checks (`isFile` / `isDirectory`) in one guard.
 * Returning `true` for an empty array is intentional: callers treat empty lists
 * the same regardless of the element type, so `[]` is safely accepted as `Dirent[]`.
-*/ function isDirentList(x) {
+*
+* @since 0.3.16-canary.0
+*/
+function isDirentList(x) {
 	if (x.length === 0) return true;
 	const first = x[0];
 	return typeof first === "object" && first !== null && "isFile" in first && "isDirectory" in first;

package/dist/{lib/mirror/domain/errors.domain.mjs → mirror/domain/errors.mjs}

@@ -1,8 +1,14 @@
-//#region src/lib/mirror/domain/errors.domain.ts
+//#region src/mirror/domain/errors.ts
+/**
+* @since 0.3.16-canary.0
+*/
 const MirrorErrorCode = {
 	FATAL: "FATAL",
 	PACKAGE_WRITE: "PACKAGE_WRITE"
 };
+/**
+* @since 0.3.16-canary.0
+*/
 var MirrorError = class extends Error {
 	code;
 	constructor(code, message, options) {

package/dist/{lib/mirror/application/services/generate-mirror-exports.service.mjs → mirror/domain/exports.mjs}

@@ -1,10 +1,11 @@
-import { PACKAGE_JSON_EXPORT, VALID_DTS_EXTENSIONS, VALID_JS_EXTENSIONS } from "../../domain/constants.domain.mjs";
-//#region src/lib/mirror/application/services/generate-mirror-exports.service.ts
+import { PACKAGE_JSON_EXPORT, VALID_DTS_EXTENSIONS, VALID_JS_EXTENSIONS } from "./constants.mjs";
+import * as nodePath from "node:path";
+//#region src/mirror/domain/exports.ts
 function resolvePackageScopedConfig(configMap, pkgMeta) {
 	if (!configMap) return;
 	return configMap[pkgMeta.packageName];
 }
-function groupFilesByModule(files, pathService) {
+function groupFilesByModule(files) {
 	const modules = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		let ext;
@@ -14,11 +15,11 @@ function groupFilesByModule(files, pathService) {
 			ext = dtsExt;
 			modulePath = file.slice(0, -dtsExt.length);
 		} else {
-			ext = pathService.extname(file);
+			ext = nodePath.extname(file);
 			if (!VALID_JS_EXTENSIONS.has(ext)) continue;
 			modulePath = file.slice(0, -ext.length);
 		}
-		if (!pathService.basename(modulePath)) continue;
+		if (!nodePath.basename(modulePath)) continue;
 		let distModule = modules.get(modulePath);
 		if (!distModule) {
 			distModule = {
@@ -103,6 +104,9 @@ function getExportGroup(exportPath, pathTransform) {
 		1
 	];
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function createPathTransform(config, pkgMeta) {
 	const pathConfig = resolvePackageScopedConfig(config?.pathTransformations, pkgMeta);
 	if (!pathConfig) return null;
@@ -131,7 +135,7 @@ function compareTuples(left, right) {
 	if (left[3] !== right[3]) return left[3] < right[3] ? -1 : 1;
 	return 0;
 }
-async function generateCssExports(pathService, fileSystemService, distDir, cssConfig) {
+async function generateCssExports(fileSystemService, distDir, cssConfig) {
 	if (cssConfig === false) return {};
 	if (cssConfig === true) cssConfig = { enabled: true };
 	if (!cssConfig || cssConfig.enabled === false) return {};
@@ -141,7 +145,7 @@ async function generateCssExports(pathService, fileSystemService, distDir, cssCo
 	const cssByDir = /* @__PURE__ */ new Map();
 	const rootCss = [];
 	for (const file of cssFiles) {
-		const dirName = pathService.dirname(file).split(pathService.separator).join("/");
+		const dirName = nodePath.dirname(file).split(nodePath.sep).join("/");
 		if (dirName === ".") rootCss.push(file);
 		else {
 			const arr = cssByDir.get(dirName) || [];
@@ -164,7 +168,10 @@ async function generateCssExports(pathService, fileSystemService, distDir, cssCo
 }
 /**
 * Compute `package.json#exports` from a built `dist/` tree. No logging; no writes.
-*/ async function generateExports(pathService, fileSystemService, distDir, pathTransform, cssConfig, customExports) {
+*
+* @since 0.3.16-canary.0
+*/
+async function generateExports(fileSystemService, distDir, pathTransform, cssConfig, customExports) {
 	const files = await fileSystemService.listRelativeFilesRecursively(distDir);
 	if (!files.length) return {
 		exports: { [PACKAGE_JSON_EXPORT]: PACKAGE_JSON_EXPORT },
@@ -172,7 +179,7 @@ async function generateCssExports(pathService, fileSystemService, distDir, cssCo
 		jsCount: 0,
 		cssCount: 0
 	};
-	const modules = groupFilesByModule(files, pathService);
+	const modules = groupFilesByModule(files);
 	const validModules = Array.from(modules.values()).filter((moduleEntry) => (moduleEntry.files.js || moduleEntry.files.mjs) && moduleEntry.files.dts);
 	if (!validModules.length) return {
 		exports: { [PACKAGE_JSON_EXPORT]: PACKAGE_JSON_EXPORT },
@@ -198,7 +205,7 @@ async function generateCssExports(pathService, fileSystemService, distDir, cssCo
 	let sortedKeys = Object.keys(exportsObj).sort((pathA, pathB) => compareTuples(getSortTuple(pathA, pathTransform), getSortTuple(pathB, pathTransform)));
 	const sortedExports = {};
 	for (const exportKey of sortedKeys) sortedExports[exportKey] = exportsObj[exportKey];
-	const cssExports = await generateCssExports(pathService, fileSystemService, distDir, cssConfig ?? { enabled: true });
+	const cssExports = await generateCssExports(fileSystemService, distDir, cssConfig ?? { enabled: true });
 	Object.assign(sortedExports, cssExports);
 	for (const [specifier, mappedPath] of Object.entries(customExports || {})) if (specifier !== "./package.json") sortedExports[specifier] = mappedPath;
 	for (const cssSpecifier of Object.keys(cssExports)) if (!(cssSpecifier in originalPathBySpecifier)) originalPathBySpecifier[cssSpecifier] = cssSpecifier;

package/dist/{lib/mirror/domain/package-display-name.policy.mjs → mirror/domain/package-display-name.mjs}

@@ -1,7 +1,10 @@
-//#region src/lib/mirror/domain/package-display-name.policy.ts
+//#region src/mirror/domain/package-display-name.ts
 /**
 * Domain rule: prefer `package.json#name` when it is present, otherwise use folder basename.
-*/ function resolvePackageDisplayName(packageJson, folderBasename) {
+*
+* @since 0.3.16-canary.0
+*/
+function resolvePackageDisplayName(packageJson, folderBasename) {
 	const declaredName = packageJson.name;
 	return typeof declaredName === "string" && declaredName.length > 0 ? declaredName : folderBasename;
 }

package/dist/{lib/mirror/domain/path-normalizer.value-object.mjs → mirror/domain/path-normalizer.mjs}

@@ -1,5 +1,8 @@
 import path from "node:path";
-//#region src/lib/mirror/domain/path-normalizer.value-object.ts
+//#region src/mirror/domain/path-normalizer.ts
+/**
+* @since 0.3.16-canary.0
+*/
 function normalizePath(pathString) {
 	return pathString.split(path.sep).join("/").replace(/\\/g, "/");
 }

package/dist/mirror/output.mjs

@@ -0,0 +1,45 @@
+import { logger } from "../core/logger.mjs";
+import { MirrorSyncReporter } from "./sync-reporter.mjs";
+//#region src/mirror/output.ts
+const cliLogger = logger;
+/**
+* @since 0.3.16-canary.0
+*/
+var MirrorSyncProgressPresenter = class {
+	reporter = new MirrorSyncReporter();
+	verbose = false;
+	configure(options) {
+		this.verbose = options.verbose;
+		this.reporter.configureMirrorColors(options.noColor);
+	}
+	onBanner() {
+		this.reporter.mirrorBanner(cliLogger);
+	}
+	onProcessingMode(mode) {
+		this.reporter.mirrorProcessingMode(cliLogger, mode);
+	}
+	onNoPackages() {
+		this.reporter.mirrorNoPackages(cliLogger);
+	}
+	onPackageComplete(pkgStats, ordinal, total) {
+		if (pkgStats.skipped) {
+			this.reporter.logSkippedWorkspacePackage(cliLogger, ordinal, total, pkgStats.name, pkgStats.skipReason);
+			return;
+		}
+		if (pkgStats.error !== null) {
+			this.reporter.logPackageError(cliLogger, ordinal, total, pkgStats.name, pkgStats.error, this.verbose);
+			return;
+		}
+		for (const exportSpecifier of pkgStats.prunedExportKeys) this.reporter.logPrunedStaleExport(cliLogger, exportSpecifier);
+		this.reporter.logPackageSuccess(cliLogger, ordinal, total, pkgStats, {
+			jsCount: pkgStats.jsModules,
+			cssCount: pkgStats.cssExports
+		}, this.verbose);
+	}
+	onComplete(stats, elapsedSeconds) {
+		this.reporter.mirrorSummarySeparator(cliLogger);
+		this.reporter.mirrorSummary(cliLogger, stats, elapsedSeconds);
+	}
+};
+//#endregion
+export { MirrorSyncProgressPresenter };

package/dist/mirror/package-path.mjs

@@ -0,0 +1,32 @@
+import { AppError } from "../core/errors.mjs";
+import { err, ok } from "../core/result.mjs";
+import { normalizePath } from "./domain/path-normalizer.mjs";
+import path from "node:path";
+//#region src/mirror/package-path.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function resolveMirrorPackageFromCliArg(fs, args) {
+	const { rootDir, packageArg, currentWorkingDirectory } = args;
+	if (!packageArg) return ok(void 0);
+	const rootReal = fs.canonicalPathSync(path.resolve(rootDir));
+	const cwdReal = fs.canonicalPathSync(currentWorkingDirectory);
+	const resolved = path.isAbsolute(packageArg) ? path.resolve(packageArg) : path.resolve(cwdReal, packageArg);
+	const targetReal = fs.canonicalPathSync(resolved);
+	const normalized = normalizePath(path.relative(rootReal, targetReal));
+	if (normalized.startsWith("..") || path.isAbsolute(normalized) || normalized === "" || normalized === ".") return err(new AppError("VALIDATION_ERROR", `Package path must be a subdirectory under monorepo root: ${rootDir}`));
+	return ok(normalized);
+}
+/**
+* @since 0.3.16-canary.0
+*/
+function resolvePackageFilterUnderRoot(fs, rootDir, packageFilter) {
+	const rootResolved = path.resolve(rootDir);
+	const rootReal = fs.canonicalPathSync(rootResolved);
+	const resolved = path.isAbsolute(packageFilter) ? fs.canonicalPathSync(path.resolve(packageFilter)) : fs.canonicalPathSync(path.join(rootReal, packageFilter));
+	const normalized = normalizePath(path.relative(rootReal, resolved));
+	if (normalized.startsWith("..") || path.isAbsolute(normalized) || normalized === "" || normalized === ".") return err(new AppError("VALIDATION_ERROR", `Package path must be a subdirectory under monorepo root: ${rootDir}`));
+	return ok(normalized);
+}
+//#endregion
+export { resolveMirrorPackageFromCliArg, resolvePackageFilterUnderRoot };

package/dist/mirror/prepare.mjs

@@ -0,0 +1,33 @@
+import { AppError, messageFrom } from "../core/errors.mjs";
+import { err, ok } from "../core/result.mjs";
+import { loadCodefastConfig } from "../core/config.mjs";
+import { findRepoRoot } from "../core/workspace/resolver.mjs";
+import { resolveMirrorPackageFromCliArg } from "./package-path.mjs";
+//#region src/mirror/prepare.ts
+/**
+* @since 0.3.16-canary.0
+*/
+async function prepareMirrorSync(fs, args) {
+	let rootDir;
+	try {
+		rootDir = findRepoRoot(args.currentWorkingDirectory, fs);
+	} catch (caughtError) {
+		return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+	}
+	const filterOutcome = resolveMirrorPackageFromCliArg(fs, {
+		rootDir,
+		packageArg: args.packageArg,
+		currentWorkingDirectory: args.currentWorkingDirectory
+	});
+	if (!filterOutcome.ok) return filterOutcome;
+	const loadedOutcome = await loadCodefastConfig(rootDir, fs);
+	if (!loadedOutcome.ok) return loadedOutcome;
+	return ok({
+		globals: args.globals,
+		rootDir,
+		config: loadedOutcome.value.config,
+		packageFilter: filterOutcome.value
+	});
+}
+//#endregion
+export { prepareMirrorSync };