@codefast/cli 0.3.12 → 0.3.13-canary.1

package/dist/lib/mirror/infra/workspace-packages.mjs

@@ -0,0 +1,159 @@
+import { messageFromCaughtUnknown } from "../../infra/caught-unknown-message.mjs";
+import { normalizePath } from "./path-normalizer.mjs";
+import { mirrorGlobWarning } from "../presentation/reporter.mjs";
+import { globSync } from "node:fs";
+import path from "node:path";
+import picomatch from "picomatch";
+import { parse } from "yaml";
+//#region src/lib/mirror/infra/workspace-packages.ts
+const PNPM_WORKSPACE = "pnpm-workspace.yaml";
+/** Default when the workspace file is missing or has no `packages` key. */
+const DEFAULT_INCLUDE = ["packages/*"];
+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";
+}
+/** Turn a pnpm `packages` glob into a `globSync` pattern that finds `package.json` files. */
+function workspacePatternToPackageJsonGlob(pattern) {
+	const normalizedPattern = toPosix(pattern.trim()).replace(/\/+$/, "");
+	if (!normalizedPattern) return "**/package.json";
+	return `${normalizedPattern}/package.json`;
+}
+function splitWorkspacePackageEntries(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
+	};
+}
+/**
+* Reads `packages` from a parsed pnpm workspace document.
+* @throws If the document is invalid or `packages` is present but not an array.
+*/
+function parsePnpmWorkspaceDocument(doc) {
+	if (doc === null || doc === void 0) throw new Error(`${PNPM_WORKSPACE} root document must be an object (got empty or null)`);
+	if (typeof doc !== "object" || Array.isArray(doc)) throw new Error(`${PNPM_WORKSPACE} 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(`${PNPM_WORKSPACE} field "packages" must be an array`);
+	if (pkgs.length === 0) return {
+		include: [],
+		exclude: [],
+		hasPackagesKey: true,
+		isEmptyPackagesArray: true
+	};
+	return {
+		...splitWorkspacePackageEntries(pkgs),
+		hasPackagesKey: true,
+		isEmptyPackagesArray: false
+	};
+}
+async function readWorkspaceYaml(rootDir, fs) {
+	const workspaceYamlPath = path.join(rootDir, PNPM_WORKSPACE);
+	if (!fs.existsSync(workspaceYamlPath)) return { exists: false };
+	let raw;
+	try {
+		raw = await fs.readFile(workspaceYamlPath, "utf8");
+	} catch (caughtReadError) {
+		throw new Error(`Failed to read ${PNPM_WORKSPACE}: ${messageFromCaughtUnknown(caughtReadError)}`);
+	}
+	let doc;
+	try {
+		doc = parse(raw);
+	} catch (caughtYamlParseError) {
+		throw new Error(`Failed to parse ${PNPM_WORKSPACE}: ${messageFromCaughtUnknown(caughtYamlParseError)}`);
+	}
+	if (doc === null || doc === void 0) throw new Error(`${PNPM_WORKSPACE} must define a mapping at the document root`);
+	return {
+		exists: true,
+		doc
+	};
+}
+/**
+* Workspace package directories relative to `rootDir` (POSIX slashes), sorted.
+* Reads `pnpm-workspace.yaml` when present; otherwise uses `packages/*`.
+* Only paths with a `package.json` are returned (same practical rule as pnpm).
+*/
+async function findWorkspacePackageRelPaths(rootDir, fs, logger) {
+	const workspaceYaml = await readWorkspaceYaml(rootDir, fs);
+	let include;
+	let exclude;
+	let multiSource;
+	if (!workspaceYaml.exists) {
+		include = [...DEFAULT_INCLUDE];
+		exclude = [];
+		multiSource = "default-patterns";
+	} else {
+		const parsed = parsePnpmWorkspaceDocument(workspaceYaml.doc);
+		if (!parsed.hasPackagesKey) {
+			include = [...DEFAULT_INCLUDE];
+			exclude = [];
+			multiSource = "default-patterns";
+		} else if (parsed.isEmptyPackagesArray) return {
+			relPaths: [],
+			multiSource: "declared-empty"
+		};
+		else {
+			include = parsed.include;
+			exclude = parsed.exclude;
+			multiSource = "pnpm-workspace-yaml";
+		}
+	}
+	const found = /* @__PURE__ */ new Set();
+	const globOpts = {
+		cwd: rootDir,
+		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)) {
+				mirrorGlobWarning(logger, `Skipping workspace glob "${pattern}" (${messageFromCaughtUnknown(caughtGlobError)})`);
+				continue;
+			}
+			throw new Error(`Invalid workspace glob "${pattern}": ${messageFromCaughtUnknown(caughtGlobError)}`);
+		}
+		for (const matchedPath of matches) {
+			const posix = toPosix(matchedPath);
+			if (!posix.endsWith("/package.json")) continue;
+			const rel = posix.slice(0, -13);
+			if (!rel) continue;
+			found.add(normalizePath(rel));
+		}
+	}
+	const excludeMatchers = exclude.map((pat) => picomatch(pat, { dot: true }));
+	const relPaths = [...found].filter((rel) => !excludeMatchers.some((isMatch) => isMatch(rel)));
+	relPaths.sort((a, b) => a.localeCompare(b));
+	return {
+		relPaths,
+		multiSource
+	};
+}
+//#endregion
+export { findWorkspacePackageRelPaths, parsePnpmWorkspaceDocument, splitWorkspacePackageEntries, workspacePatternToPackageJsonGlob };

package/dist/lib/mirror/presentation/reporter.mjs

@@ -0,0 +1,111 @@
+import { messageFromCaughtUnknown } from "../../infra/caught-unknown-message.mjs";
+import { printConfigSchemaWarnings } from "../../infra/config-reporter.mjs";
+import process from "node:process";
+//#region src/lib/mirror/presentation/reporter.ts
+const Colors = {
+	RESET: "\x1B[0m",
+	BOLD: "\x1B[1m",
+	DIM: "\x1B[2m",
+	GREEN: "\x1B[32m",
+	YELLOW: "\x1B[33m",
+	CYAN: "\x1B[36m",
+	GRAY: "\x1B[90m",
+	MAGENTA: "\x1B[35m",
+	BRIGHT_GREEN: "\x1B[92m",
+	BRIGHT_YELLOW: "\x1B[93m",
+	BRIGHT_CYAN: "\x1B[96m",
+	disable() {
+		for (const key of Object.keys(this)) if (typeof this[key] === "string") this[key] = "";
+	}
+};
+function configureMirrorColors(noColor) {
+	if (!process.stdout.isTTY || noColor) Colors.disable();
+}
+function printMirrorConfigWarnings(logger, warnings) {
+	printConfigSchemaWarnings(logger, warnings);
+}
+function mirrorGlobWarning(logger, message) {
+	const { out } = logger;
+	out(`${Colors.YELLOW}⚠ ${message}${Colors.RESET}`);
+}
+function logSkippedWorkspacePackage(logger, index, total, displayName, reason) {
+	const { out } = logger;
+	out(`${`${Colors.DIM}[${index}/${total}]${Colors.RESET}`} ${Colors.GRAY}○${Colors.RESET} ${Colors.DIM}${displayName}${Colors.RESET}`);
+	out(`  ${Colors.DIM}└─${Colors.RESET} ${Colors.GRAY}Skipped: ${reason}${Colors.RESET}`);
+	out("");
+}
+function mirrorBanner(logger) {
+	const { out } = logger;
+	out(`\n${Colors.BOLD}${Colors.CYAN}📦 Mirror — package exports${Colors.RESET}`);
+	out(`${Colors.DIM}${"═".repeat(60)}${Colors.RESET}\n`);
+}
+function mirrorProcessingMode(logger, mode) {
+	const { out } = logger;
+	if (mode.kind === "single") {
+		out(`${Colors.DIM}Processing single package...${Colors.RESET}\n`);
+		return;
+	}
+	switch (mode.source) {
+		case "default-patterns":
+			out(`${Colors.DIM}Discovering workspace packages using default patterns (packages/*)…${Colors.RESET}\n`);
+			break;
+		case "pnpm-workspace-yaml":
+			out(`${Colors.DIM}Discovering workspace packages from pnpm-workspace.yaml…${Colors.RESET}\n`);
+			break;
+		case "declared-empty":
+			out(`${Colors.DIM}pnpm-workspace.yaml declares an empty workspace package list.${Colors.RESET}\n`);
+			break;
+	}
+}
+function mirrorNoPackages(logger) {
+	logger.out(`${Colors.YELLOW}⚠ No packages found${Colors.RESET}`);
+}
+function logPackageSuccess(logger, index, total, pkgStats, generatedDistAssetCounts, verbose) {
+	const { out } = logger;
+	out(`${`${Colors.DIM}[${index}/${total}]${Colors.RESET}`} ${Colors.BRIGHT_GREEN}✓${Colors.RESET} ${Colors.BOLD}${pkgStats.name}${Colors.RESET}`);
+	if (verbose) {
+		out(`  ${Colors.DIM}├─${Colors.RESET} Path: ${pkgStats.path}`);
+		if (pkgStats.hasTransform) out(`  ${Colors.DIM}├─${Colors.RESET} ${Colors.CYAN}Custom path transformation${Colors.RESET}`);
+		if (pkgStats.cssConfigStatus) out(`  ${Colors.DIM}├─${Colors.RESET} ${Colors.CYAN}${pkgStats.cssConfigStatus === "disabled" ? "CSS disabled" : "CSS configured"}${Colors.RESET}`);
+	}
+	const breakdown = [];
+	if (generatedDistAssetCounts.jsCount > 0) breakdown.push(`${Colors.GREEN}${generatedDistAssetCounts.jsCount} modules${Colors.RESET}`);
+	if (generatedDistAssetCounts.cssCount > 0) breakdown.push(`${Colors.MAGENTA}${generatedDistAssetCounts.cssCount} CSS${Colors.RESET}`);
+	if (pkgStats.customExports > 0) breakdown.push(`${Colors.YELLOW}${pkgStats.customExports} custom${Colors.RESET}`);
+	if (breakdown.length > 0) out(`  ${Colors.DIM}└─${Colors.RESET} ${breakdown.join(" + ")} = ${Colors.BRIGHT_CYAN}${pkgStats.totalExports} exports${Colors.RESET}`);
+	else out(`  ${Colors.DIM}└─${Colors.RESET} ${Colors.BRIGHT_CYAN}${pkgStats.totalExports} exports${Colors.RESET}`);
+	out("");
+}
+function logPrunedStaleExport(logger, exportSpecifier) {
+	logger.out(`  ${Colors.DIM}└─${Colors.RESET} ${Colors.GRAY}Pruned stale export: ${exportSpecifier}${Colors.RESET}`);
+}
+function logPackageError(logger, index, total, displayName, errValue, verbose) {
+	const { out, err: errLine } = logger;
+	out(`${Colors.DIM}[${index}/${total}]${Colors.RESET} ${Colors.YELLOW}✗${Colors.RESET} ${Colors.BOLD}${displayName}${Colors.RESET}`);
+	out(`  ${Colors.DIM}└─${Colors.RESET} ${Colors.YELLOW}Error: ${messageFromCaughtUnknown(errValue)}${Colors.RESET}\n`);
+	if (verbose) errLine(errValue instanceof Error && errValue.stack ? errValue.stack : messageFromCaughtUnknown(errValue));
+}
+function mirrorSummarySeparator(logger) {
+	logger.out(`${Colors.DIM}${"═".repeat(60)}${Colors.RESET}`);
+}
+function mirrorSummary(logger, stats, elapsedSeconds) {
+	const { out } = logger;
+	out(`${Colors.BOLD}📊 Summary${Colors.RESET} ${Colors.DIM}(completed in ${elapsedSeconds.toFixed(2)}s)${Colors.RESET}\n`);
+	out(`  ${Colors.BOLD}Packages:${Colors.RESET}`);
+	out(`  ${Colors.DIM}├─${Colors.RESET} Processed: ${Colors.GREEN}${stats.packagesProcessed}${Colors.RESET}`);
+	if (stats.packagesSkipped > 0) out(`  ${Colors.DIM}├─${Colors.RESET} Skipped: ${Colors.GRAY}${stats.packagesSkipped}${Colors.RESET}`);
+	if (stats.packagesErrored > 0) out(`  ${Colors.DIM}├─${Colors.RESET} Errors: ${Colors.YELLOW}${stats.packagesErrored}${Colors.RESET}`);
+	out(`  ${Colors.DIM}└─${Colors.RESET} Total found: ${stats.packagesFound}\n`);
+	out(`  ${Colors.BOLD}Exports:${Colors.RESET}`);
+	out(`  ${Colors.DIM}├─${Colors.RESET} JS Modules: ${Colors.CYAN}${stats.totalJsModules}${Colors.RESET}`);
+	out(`  ${Colors.DIM}├─${Colors.RESET} CSS Files: ${Colors.MAGENTA}${stats.totalCssExports}${Colors.RESET}`);
+	out(`  ${Colors.DIM}└─${Colors.RESET} Total: ${Colors.BRIGHT_CYAN}${stats.totalExports}${Colors.RESET}\n`);
+	out(`${Colors.DIM}${"═".repeat(60)}${Colors.RESET}\n`);
+}
+function mirrorFatalError(logger, caughtError) {
+	const { out, err: errLine } = logger;
+	out(`${Colors.YELLOW}Fatal error: ${messageFromCaughtUnknown(caughtError)}${Colors.RESET}`);
+	errLine(caughtError instanceof Error && caughtError.stack ? caughtError.stack : messageFromCaughtUnknown(caughtError));
+}
+//#endregion
+export { configureMirrorColors, logPackageError, logPackageSuccess, logPrunedStaleExport, logSkippedWorkspacePackage, mirrorBanner, mirrorFatalError, mirrorGlobWarning, mirrorNoPackages, mirrorProcessingMode, mirrorSummary, mirrorSummarySeparator, printMirrorConfigWarnings };

package/dist/lib/tag/application/engine.mjs

@@ -0,0 +1,287 @@
+import { messageFromCaughtUnknown } from "../../infra/caught-unknown-message.mjs";
+import { applyEditsDescending, indentOfLineContaining } from "../../arrange/domain/ast/ast-helpers.mjs";
+import { walkTsxFiles } from "../../arrange/infra/walk.mjs";
+import "../../arrange/index.mjs";
+import { resolveTagTargetCandidates } from "../infra/target-resolver.mjs";
+import path from "node:path";
+import ts from "typescript";
+//#region src/lib/tag/application/engine.ts
+const PACKAGE_JSON = "package.json";
+const VERSION_TAG = "@since";
+function hasExportModifier(node) {
+	return (ts.canHaveModifiers(node) ? ts.getModifiers(node) : void 0)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+function isTaggableDeclaration(node) {
+	return ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isVariableStatement(node);
+}
+function addDeclarationName(registry, name, declaration) {
+	if (!registry.has(name)) {
+		registry.set(name, new Set([declaration]));
+		return;
+	}
+	registry.get(name).add(declaration);
+}
+function collectLocalNamedDeclarations(sf) {
+	const declarations = /* @__PURE__ */ new Map();
+	for (const statement of sf.statements) {
+		if (ts.isFunctionDeclaration(statement) && statement.name) {
+			addDeclarationName(declarations, statement.name.text, statement);
+			continue;
+		}
+		if (ts.isClassDeclaration(statement) && statement.name) {
+			addDeclarationName(declarations, statement.name.text, statement);
+			continue;
+		}
+		if (ts.isInterfaceDeclaration(statement)) {
+			addDeclarationName(declarations, statement.name.text, statement);
+			continue;
+		}
+		if (ts.isTypeAliasDeclaration(statement)) {
+			addDeclarationName(declarations, statement.name.text, statement);
+			continue;
+		}
+		if (ts.isEnumDeclaration(statement)) {
+			addDeclarationName(declarations, statement.name.text, statement);
+			continue;
+		}
+		if (!ts.isVariableStatement(statement)) continue;
+		for (const declaration of statement.declarationList.declarations) if (ts.isIdentifier(declaration.name)) addDeclarationName(declarations, declaration.name.text, statement);
+	}
+	return declarations;
+}
+function collectExportedDeclarations(sf) {
+	const exported = /* @__PURE__ */ new Set();
+	const localNamed = collectLocalNamedDeclarations(sf);
+	for (const statement of sf.statements) {
+		if (isTaggableDeclaration(statement) && hasExportModifier(statement)) {
+			exported.add(statement);
+			continue;
+		}
+		if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+			for (const element of statement.exportClause.elements) {
+				const localName = element.propertyName?.text ?? element.name.text;
+				const declarations = localNamed.get(localName);
+				if (!declarations) continue;
+				for (const declaration of declarations) exported.add(declaration);
+			}
+			continue;
+		}
+		if (!ts.isExportAssignment(statement) || !ts.isIdentifier(statement.expression)) continue;
+		const declarations = localNamed.get(statement.expression.text);
+		if (!declarations) continue;
+		for (const declaration of declarations) exported.add(declaration);
+	}
+	return exported;
+}
+function makeJSDocSinceLine(existingComment, sourceText, version) {
+	const commentText = sourceText.slice(existingComment.pos, existingComment.end);
+	const baseIndent = indentOfLineContaining(sourceText, existingComment.pos);
+	const normalizedBodyLines = commentText.replace(/^\/\*\*\s?/, "").replace(/\s*\*\/$/, "").split("\n").map((line) => line.replace(/^\s*\*\s?/, "").replace(/\s+$/, "")).filter((line, lineIndex, lines) => {
+		if (line.length > 0) return true;
+		const hasNonEmptyBefore = lines.slice(0, lineIndex).some((value) => value.length > 0);
+		const hasNonEmptyAfter = lines.slice(lineIndex + 1).some((value) => value.length > 0);
+		return hasNonEmptyBefore && hasNonEmptyAfter;
+	});
+	const replacement = `/**\n${normalizedBodyLines.length > 0 ? `${normalizedBodyLines.map((line) => `${baseIndent} * ${line}`).join("\n")}\n${baseIndent} *\n` : ""}${baseIndent} * ${VERSION_TAG} ${version}\n${baseIndent} */`;
+	return {
+		start: existingComment.pos,
+		end: existingComment.end,
+		replacement
+	};
+}
+function makeSinceOnlyJSDocBlock(declarationIndent, version) {
+	return `/**\n${declarationIndent} * ${VERSION_TAG} ${version}\n${declarationIndent} */`;
+}
+function makeDeclarationSinceLine(declaration, sf, sourceText, version) {
+	if (ts.getJSDocTags(declaration).some((tag) => tag.tagName.text === "since")) return;
+	const lastJsDoc = ts.getJSDocCommentsAndTags(declaration).filter(ts.isJSDoc).at(-1);
+	if (lastJsDoc) return makeJSDocSinceLine(lastJsDoc, sourceText, version);
+	const start = declaration.getStart(sf);
+	const indent = indentOfLineContaining(sourceText, start);
+	return {
+		start,
+		end: start,
+		replacement: `${indent}${makeSinceOnlyJSDocBlock(indent, version)}\n${indent}`
+	};
+}
+function applySinceTagsToFile(filePath, version, fs, write) {
+	const sourceText = fs.readFileSync(filePath, "utf8");
+	const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+	const edits = [];
+	for (const declaration of collectExportedDeclarations(sf)) {
+		const edit = makeDeclarationSinceLine(declaration, sf, sourceText, version);
+		if (edit) edits.push(edit);
+	}
+	if (edits.length > 0 && write) {
+		const updated = applyEditsDescending(sourceText, edits);
+		fs.writeFileSync(filePath, updated, "utf8");
+	}
+	return {
+		filePath,
+		taggedDeclarations: edits.length,
+		changed: edits.length > 0
+	};
+}
+function resolveNearestPackageVersion(targetPath, fs) {
+	const resolved = path.resolve(targetPath);
+	let current = fs.statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
+	while (true) {
+		const packageJsonPath = path.join(current, PACKAGE_JSON);
+		if (fs.existsSync(packageJsonPath)) {
+			const raw = fs.readFileSync(packageJsonPath, "utf8");
+			const version = JSON.parse(raw).version;
+			if (typeof version === "string" && version.length > 0) return version;
+			throw new Error(`Missing or invalid version in ${packageJsonPath}`);
+		}
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	throw new Error(`Unable to locate ${PACKAGE_JSON} from target: ${targetPath}`);
+}
+function runTagOnTarget(targetPath, opts, fs) {
+	const resolvedTarget = path.resolve(targetPath);
+	const version = resolveNearestPackageVersion(resolvedTarget, fs);
+	const tsFiles = (fs.statSync(resolvedTarget).isDirectory() ? walkTsxFiles(resolvedTarget, fs) : [resolvedTarget]).filter((filePath) => filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
+	const fileResults = tsFiles.map((filePath) => applySinceTagsToFile(filePath, version, fs, opts.write));
+	const filesChanged = fileResults.filter((result) => result.changed).length;
+	const taggedDeclarations = fileResults.reduce((sum, result) => sum + result.taggedDeclarations, 0);
+	return {
+		version,
+		filesScanned: tsFiles.length,
+		filesChanged,
+		taggedDeclarations,
+		fileResults
+	};
+}
+async function runTagOnAfterWriteHook(hook, modifiedFiles) {
+	if (!hook || modifiedFiles.length === 0) return null;
+	try {
+		await hook({ files: modifiedFiles });
+		return null;
+	} catch (caughtHookError) {
+		return `[tag] onAfterWrite hook failed: ${messageFromCaughtUnknown(caughtHookError)}`;
+	}
+}
+function summarizeVersions(targetResults) {
+	const distinctVersions = extractDistinctVersions(targetResults);
+	if (distinctVersions.size === 0) return "none";
+	if (distinctVersions.size > 1) return "mixed";
+	return [...distinctVersions][0];
+}
+function extractDistinctVersions(targetResults) {
+	return new Set(targetResults.map((targetResult) => targetResult.result?.version).filter((version) => typeof version === "string" && version.length > 0));
+}
+function chooseWorkspacePackageTargetPath(candidate, fs) {
+	if (candidate.source !== "workspace-package") return {
+		targetPath: candidate.candidatePath,
+		source: candidate.source
+	};
+	const preferredSourceDir = path.join(candidate.candidatePath, "src");
+	if (fs.existsSync(preferredSourceDir) && fs.statSync(preferredSourceDir).isDirectory()) return {
+		targetPath: preferredSourceDir,
+		source: "workspace-package-selected-src"
+	};
+	return {
+		targetPath: candidate.candidatePath,
+		source: "workspace-package-selected-root"
+	};
+}
+function resolveTargetSelection(candidate, rootDir, fs) {
+	const selectedTarget = chooseWorkspacePackageTargetPath(candidate, fs);
+	const rootRelativeTargetPath = path.relative(rootDir, selectedTarget.targetPath).split(path.sep).join("/");
+	return {
+		targetPath: selectedTarget.targetPath,
+		rootRelativeTargetPath: rootRelativeTargetPath || ".",
+		source: selectedTarget.source,
+		packageDir: candidate.packageDir,
+		packageName: candidate.packageName
+	};
+}
+function filterSkippedCandidates(targetCandidates, skipPackages) {
+	if (!skipPackages || skipPackages.length === 0) return {
+		includedCandidates: targetCandidates,
+		skippedPackages: []
+	};
+	const skipPackageSet = new Set(skipPackages);
+	const includedCandidates = [];
+	const skippedPackages = [];
+	for (const candidate of targetCandidates) {
+		const packageName = candidate.packageName;
+		if (packageName && skipPackageSet.has(packageName)) {
+			skippedPackages.push(packageName);
+			continue;
+		}
+		includedCandidates.push(candidate);
+	}
+	return {
+		includedCandidates,
+		skippedPackages
+	};
+}
+async function runOnResolvedTarget(resolvedTarget, write, fs, listener) {
+	listener?.onTargetStarted(resolvedTarget);
+	const absoluteTargetPath = path.resolve(resolvedTarget.targetPath);
+	if (!fs.existsSync(absoluteTargetPath)) {
+		const missingTargetResult = {
+			target: resolvedTarget,
+			targetExists: false,
+			runError: `Not found: ${absoluteTargetPath}`,
+			result: null
+		};
+		listener?.onTargetCompleted(resolvedTarget, missingTargetResult);
+		return missingTargetResult;
+	}
+	try {
+		const targetRunResult = {
+			target: resolvedTarget,
+			targetExists: true,
+			runError: null,
+			result: runTagOnTarget(absoluteTargetPath, { write }, fs)
+		};
+		listener?.onTargetCompleted(resolvedTarget, targetRunResult);
+		return targetRunResult;
+	} catch (caughtRunError) {
+		const failedTargetRunResult = {
+			target: resolvedTarget,
+			targetExists: true,
+			runError: messageFromCaughtUnknown(caughtRunError),
+			result: null
+		};
+		listener?.onTargetCompleted(resolvedTarget, failedTargetRunResult);
+		return failedTargetRunResult;
+	}
+}
+/**
+* CLI entry: run tagging and optional `onAfterWrite` using config injected by the command layer.
+* Returns structured execution data; presentation/logging belongs to command layer.
+*/
+async function runTagSync(opts) {
+	const { fs } = opts;
+	const { includedCandidates, skippedPackages } = filterSkippedCandidates(await resolveTagTargetCandidates(opts.rootDir, opts.targetPath, fs), opts.skipPackages);
+	const selectedTargets = includedCandidates.map((candidate) => resolveTargetSelection(candidate, opts.rootDir, fs));
+	const targetResults = await Promise.all(selectedTargets.map((resolvedTarget) => runOnResolvedTarget(resolvedTarget, opts.write, fs, opts.listener)));
+	const allFileResults = targetResults.flatMap((targetResult) => targetResult.result?.fileResults ?? []);
+	const filesScanned = targetResults.reduce((sum, targetResult) => sum + (targetResult.result?.filesScanned ?? 0), 0);
+	const filesChanged = targetResults.reduce((sum, targetResult) => sum + (targetResult.result?.filesChanged ?? 0), 0);
+	const taggedDeclarations = targetResults.reduce((sum, targetResult) => sum + (targetResult.result?.taggedDeclarations ?? 0), 0);
+	const modifiedFiles = allFileResults.filter((entry) => entry.changed).map((entry) => entry.filePath);
+	const hookError = opts.write && modifiedFiles.length > 0 ? await runTagOnAfterWriteHook(opts.config?.onAfterWrite, modifiedFiles) : null;
+	const distinctVersions = [...extractDistinctVersions(targetResults)].sort((left, right) => left.localeCompare(right));
+	return {
+		mode: opts.write ? "applied" : "dry-run",
+		selectedTargets,
+		resolvedTargets: selectedTargets,
+		skippedPackages,
+		targetResults,
+		filesScanned,
+		filesChanged,
+		taggedDeclarations,
+		versionSummary: summarizeVersions(targetResults),
+		distinctVersions,
+		modifiedFiles,
+		hookError
+	};
+}
+//#endregion
+export { resolveNearestPackageVersion, runTagOnTarget, runTagSync };

package/dist/lib/tag/domain/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/lib/tag/index.mjs

@@ -0,0 +1,4 @@
+import { createNodeCliFs, createNodeCliLogger } from "../infra/node-io.mjs";
+import { resolveNearestPackageVersion, runTagOnTarget, runTagSync } from "./application/engine.mjs";
+import { createTagProgressListener, formatProgress, formatSummary, formatTargetTable, formatWarningsAndErrors } from "./presentation/tag-presenter.mjs";
+export { createNodeCliFs, createNodeCliLogger, createTagProgressListener, formatProgress, formatSummary, formatTargetTable, formatWarningsAndErrors, resolveNearestPackageVersion, runTagOnTarget, runTagSync };