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

package/dist/lib/shared/source-code/domain/text-edit.model.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pure string utilities for applying non-overlapping text edits and reading line indentation.
+ */
+export type SourceTextEdit = Readonly<{
+    start: number;
+    end: number;
+    replacement: string;
+}>;
+/**
+ * Returns only the leading whitespace (tabs / spaces) of the line containing `pos`.
+ */
+export declare function indentOfLineContaining(source: string, pos: number): string;
+export declare function applyEditsDescending(sourceText: string, edits: ReadonlyArray<SourceTextEdit>): string;
+//# sourceMappingURL=text-edit.model.d.ts.map

package/dist/lib/shared/source-code/domain/text-edit.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-edit.model.d.ts","sourceRoot":"","sources":["../../../../../src/lib/shared/source-code/domain/text-edit.model.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAoB1E;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,GACnC,MAAM,CAOR"}

package/dist/lib/shared/source-code/domain/text-edit.model.js

@@ -0,0 +1,30 @@
+/**
+ * Pure string utilities for applying non-overlapping text edits and reading line indentation.
+ */
+/**
+ * Returns only the leading whitespace (tabs / spaces) of the line containing `pos`.
+ */
+export function indentOfLineContaining(source, pos) {
+    const searchPos = Math.max(0, Math.min(pos, source.length));
+    const prevLineBreak = Math.max(source.lastIndexOf("\n", searchPos - 1), source.lastIndexOf("\r", searchPos - 1));
+    const lineStart = prevLineBreak === -1 ? 0 : prevLineBreak + 1;
+    let lineEnd = source.length;
+    for (let i = lineStart; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "\n" || ch === "\r") {
+            lineEnd = i;
+            break;
+        }
+    }
+    const line = source.slice(lineStart, lineEnd);
+    const indentMatch = /^[\t ]*/.exec(line);
+    return indentMatch?.[0] ?? "";
+}
+export function applyEditsDescending(sourceText, edits) {
+    const sorted = [...edits].sort((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/lib/shared/source-code/infra/tsx-file-walk.adapter.d.ts

@@ -0,0 +1,4 @@
+import type { CliFs } from "#lib/core/application/ports/cli-io.port";
+export declare const DEFAULT_SKIP_DIRS: Set<string>;
+export declare function walkTsxFiles(rootDirectoryPath: string, fs: CliFs): string[];
+//# sourceMappingURL=tsx-file-walk.adapter.d.ts.map

package/dist/lib/shared/source-code/infra/tsx-file-walk.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsx-file-walk.adapter.d.ts","sourceRoot":"","sources":["../../../../../src/lib/shared/source-code/infra/tsx-file-walk.adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAErE,eAAO,MAAM,iBAAiB,aAY5B,CAAC;AAEH,wBAAgB,YAAY,CAAC,iBAAiB,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,EAAE,CAsB3E"}

package/dist/lib/shared/source-code/infra/tsx-file-walk.adapter.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+export const DEFAULT_SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    ".git",
+    ".turbo",
+    ".next",
+    ".cache",
+    "out",
+    "build",
+    "coverage",
+    ".vercel",
+    ".output",
+]);
+export function walkTsxFiles(rootDirectoryPath, fs) {
+    const result = [];
+    const visit = (entryPath) => {
+        const entryStats = fs.statSync(entryPath);
+        if (entryStats.isDirectory()) {
+            for (const childName of fs.readdirSync(entryPath)) {
+                if (DEFAULT_SKIP_DIRS.has(childName)) {
+                    continue;
+                }
+                visit(path.join(entryPath, childName));
+            }
+            return;
+        }
+        if (entryPath.endsWith(".d.ts")) {
+            return;
+        }
+        if (entryPath.endsWith(".tsx") || entryPath.endsWith(".ts")) {
+            result.push(entryPath);
+        }
+    };
+    visit(rootDirectoryPath);
+    return result;
+}

package/dist/lib/tag/application/ports/target-resolver.port.d.ts

@@ -0,0 +1,6 @@
+import type { CliFs } from "#lib/core/application/ports/cli-io.port";
+import type { TagTargetCandidate } from "#lib/tag/domain/types.domain";
+export interface TagTargetResolverPort {
+    resolveTagTargetCandidates(rootDir: string, explicitTarget: string | undefined, fileSystem: CliFs): Promise<TagTargetCandidate[]>;
+}
+//# sourceMappingURL=target-resolver.port.d.ts.map

package/dist/lib/tag/application/ports/target-resolver.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-resolver.port.d.ts","sourceRoot":"","sources":["../../../../../src/lib/tag/application/ports/target-resolver.port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,0BAA0B,CACxB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,UAAU,EAAE,KAAK,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;CAClC"}

package/dist/lib/tag/application/ports/target-resolver.port.js

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

package/dist/lib/tag/application/ports/typescript-tree-walk.port.d.ts

@@ -0,0 +1,6 @@
+import type { CliFs } from "#lib/core/application/ports/cli-io.port";
+/** Lists `.ts` / `.tsx` files under a directory (implementation may live in another bounded context’s infra). */
+export type TypeScriptTreeWalkPort = {
+    walkTsxFiles(rootDirectoryPath: string, fs: CliFs): string[];
+};
+//# sourceMappingURL=typescript-tree-walk.port.d.ts.map

package/dist/lib/tag/application/ports/typescript-tree-walk.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-tree-walk.port.d.ts","sourceRoot":"","sources":["../../../../../src/lib/tag/application/ports/typescript-tree-walk.port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAErE,iHAAiH;AACjH,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,iBAAiB,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,EAAE,CAAC;CAC9D,CAAC"}

package/dist/lib/tag/application/ports/typescript-tree-walk.port.js

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

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

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const TagSyncRunRequestSchema: z.ZodObject<{
+    rootDir: z.ZodString;
+    write: z.ZodBoolean;
+    targetPath: z.ZodOptional<z.ZodString>;
+    skipPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type TagSyncRunRequest = z.infer<typeof TagSyncRunRequestSchema>;
+//# sourceMappingURL=tag-sync.request.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tag-sync.request.d.ts","sourceRoot":"","sources":["../../../../../src/lib/tag/application/requests/tag-sync.request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,uBAAuB;;;;;;iBAMlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

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

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export const TagSyncRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    write: z.boolean(),
+    targetPath: z.string().optional(),
+    skipPackages: z.array(z.string()).optional(),
+    config: z.unknown().optional(),
+});

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

@@ -0,0 +1,23 @@
+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 { TagSyncRunRequest } from "#lib/tag/application/requests/tag-sync.request";
+import type { TagTargetResolverPort } from "#lib/tag/application/ports/target-resolver.port";
+import type { TypeScriptTreeWalkPort } from "#lib/tag/application/ports/typescript-tree-walk.port";
+import type { TagProgressListener, TagRunOptions, TagRunResult, TagSyncResult } from "#lib/tag/domain/types.domain";
+export type TagSyncRunDeps = {
+    readonly fs: CliFs;
+    readonly targetResolver: TagTargetResolverPort;
+    readonly typeScriptTreeWalk: TypeScriptTreeWalkPort;
+};
+export type TagSyncExecutionInput = TagSyncRunRequest & {
+    listener?: TagProgressListener;
+};
+export declare function resolveNearestPackageVersion(targetPath: string, fs: CliFs): string;
+export declare function runTagOnTarget(targetPath: string, opts: TagRunOptions, fs: CliFs, typeScriptTreeWalk: TypeScriptTreeWalkPort): TagRunResult;
+/**
+ * CLI entry: run tagging and optional `onAfterWrite` using config injected by the command layer.
+ * Returns structured execution data; presentation/logging belongs to command layer.
+ */
+export declare function runTagSync(input: TagSyncExecutionInput, deps: TagSyncRunDeps): Promise<Result<TagSyncResult, AppError>>;
+//# sourceMappingURL=run-tag-sync.use-case.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-tag-sync.use-case.d.ts","sourceRoot":"","sources":["../../../../../src/lib/tag/application/use-cases/run-tag-sync.use-case.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAMrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAErE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACxF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAC7F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AACnG,OAAO,KAAK,EAEV,mBAAmB,EAInB,aAAa,EACb,YAAY,EACZ,aAAa,EAEd,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG;IACtD,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC,CAAC;AA2NF,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,CAwBlF;AAED,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,KAAK,EACT,kBAAkB,EAAE,sBAAsB,GACzC,YAAY,CAyBd;AAoJD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAiE1C"}

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

@@ -0,0 +1,357 @@
+import path from "node:path";
+import ts from "typescript";
+import { appError } from "#lib/core/domain/errors.domain";
+import { err, ok } from "#lib/core/domain/result.model";
+import { applyEditsDescending, indentOfLineContaining, } from "#lib/shared/source-code/domain/text-edit.model";
+import { messageFromCaughtUnknown } from "#lib/core/application/utils/caught-unknown-message.util";
+const PACKAGE_JSON = "package.json";
+const VERSION_TAG = "@since";
+function hasExportModifier(node) {
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    return modifiers?.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 = 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 = 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 rawBody = commentText.replace(/^\/\*\*\s?/, "").replace(/\s*\*\/$/, "");
+    const normalizedBodyLines = rawBody
+        .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 formattedBody = normalizedBodyLines.length > 0
+        ? `${normalizedBodyLines.map((line) => `${baseIndent} * ${line}`).join("\n")}\n${baseIndent} *\n`
+        : "";
+    const replacement = `/**\n${formattedBody}${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) {
+    const jsDocTags = ts.getJSDocTags(declaration);
+    if (jsDocTags.some((tag) => tag.tagName.text === "since")) {
+        return undefined;
+    }
+    const jsDocComments = ts.getJSDocCommentsAndTags(declaration).filter(ts.isJSDoc);
+    const lastJsDoc = jsDocComments.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,
+    };
+}
+export function resolveNearestPackageVersion(targetPath, fs) {
+    const resolved = path.resolve(targetPath);
+    const startDir = fs.statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
+    let current = startDir;
+    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}`);
+}
+export function runTagOnTarget(targetPath, opts, fs, typeScriptTreeWalk) {
+    const resolvedTarget = path.resolve(targetPath);
+    const version = resolveNearestPackageVersion(resolvedTarget, fs);
+    const files = fs.statSync(resolvedTarget).isDirectory()
+        ? typeScriptTreeWalk.walkTsxFiles(resolvedTarget, fs)
+        : [resolvedTarget];
+    const tsFiles = files.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, typeScriptTreeWalk, 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 runResult = runTagOnTarget(absoluteTargetPath, { write }, fs, typeScriptTreeWalk);
+        const targetRunResult = {
+            target: resolvedTarget,
+            targetExists: true,
+            runError: null,
+            result: runResult,
+        };
+        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.
+ */
+export async function runTagSync(input, deps) {
+    try {
+        const { fs, targetResolver, typeScriptTreeWalk } = deps;
+        const tagConfig = input.config;
+        const targetCandidates = await targetResolver.resolveTagTargetCandidates(input.rootDir, input.targetPath, fs);
+        const { includedCandidates, skippedPackages } = filterSkippedCandidates(targetCandidates, input.skipPackages);
+        const selectedTargets = includedCandidates.map((candidate) => resolveTargetSelection(candidate, input.rootDir, fs));
+        const targetResults = await Promise.all(selectedTargets.map((resolvedTarget) => runOnResolvedTarget(resolvedTarget, input.write, fs, typeScriptTreeWalk, input.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 = input.write && modifiedFiles.length > 0
+            ? await runTagOnAfterWriteHook(tagConfig?.onAfterWrite, modifiedFiles)
+            : null;
+        const distinctVersions = [...extractDistinctVersions(targetResults)].sort((left, right) => left.localeCompare(right));
+        return ok({
+            mode: input.write ? "applied" : "dry-run",
+            selectedTargets,
+            resolvedTargets: selectedTargets,
+            skippedPackages,
+            targetResults,
+            filesScanned,
+            filesChanged,
+            taggedDeclarations,
+            versionSummary: summarizeVersions(targetResults),
+            distinctVersions,
+            modifiedFiles,
+            hookError,
+        });
+    }
+    catch (caughtError) {
+        return err(appError("INFRA_FAILURE", messageFromCaughtUnknown(caughtError), caughtError));
+    }
+}

package/dist/lib/tag/domain/types.domain.d.ts

@@ -0,0 +1,56 @@
+export type TagFileResult = {
+    filePath: string;
+    taggedDeclarations: number;
+    changed: boolean;
+};
+export type TagRunResult = {
+    version: string;
+    filesScanned: number;
+    filesChanged: number;
+    taggedDeclarations: number;
+    fileResults: TagFileResult[];
+};
+export type TagRunOptions = {
+    write: boolean;
+};
+export type TagTargetCandidateSource = "explicit-target" | "workspace-package" | "repo-src-fallback";
+export type TagTargetSource = "explicit-target" | "workspace-package-selected-src" | "workspace-package-selected-root" | "repo-src-fallback";
+export type TagTargetCandidate = {
+    candidatePath: string;
+    rootRelativeCandidatePath: string;
+    source: TagTargetCandidateSource;
+    packageDir: string | null;
+    packageName: string | null;
+};
+export type TagResolvedTarget = {
+    targetPath: string;
+    rootRelativeTargetPath: string;
+    source: TagTargetSource;
+    packageDir: string | null;
+    packageName: string | null;
+};
+export type TagTargetExecutionResult = {
+    target: TagResolvedTarget;
+    targetExists: boolean;
+    runError: string | null;
+    result: TagRunResult | null;
+};
+export interface TagProgressListener {
+    onTargetStarted: (target: TagResolvedTarget) => void;
+    onTargetCompleted: (target: TagResolvedTarget, result: TagTargetExecutionResult) => void;
+}
+export type TagSyncResult = {
+    mode: "applied" | "dry-run";
+    selectedTargets: TagResolvedTarget[];
+    resolvedTargets: TagResolvedTarget[];
+    skippedPackages: string[];
+    targetResults: TagTargetExecutionResult[];
+    filesScanned: number;
+    filesChanged: number;
+    taggedDeclarations: number;
+    versionSummary: string;
+    distinctVersions: string[];
+    modifiedFiles: string[];
+    hookError: string | null;
+};
+//# sourceMappingURL=types.domain.d.ts.map

package/dist/lib/tag/domain/types.domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.domain.d.ts","sourceRoot":"","sources":["../../../../src/lib/tag/domain/types.domain.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,aAAa,EAAE,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAChC,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,gCAAgC,GAChC,iCAAiC,GACjC,mBAAmB,CAAC;AAExB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB,EAAE,MAAM,CAAC;IAClC,MAAM,EAAE,wBAAwB,CAAC;IACjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACrD,iBAAiB,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAC;CAC1F;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrC,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,wBAAwB,EAAE,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC"}

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

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

package/dist/lib/tag/index.d.ts

@@ -0,0 +1,14 @@
+import type { CliFs } from "#lib/core/application/ports/cli-io.port";
+import { resolveNearestPackageVersion, runTagSync } from "#lib/tag/application/use-cases/run-tag-sync.use-case";
+import type { TagRunOptions, TagRunResult } from "#lib/tag/domain/types.domain";
+export { createNodeCliFs, createNodeCliLogger } from "#lib/infra/node-io.adapter";
+/** Default composition: uses the shared TS/TSX tree walk adapter. */
+export declare function runTagOnTarget(targetPath: string, opts: TagRunOptions, fs: CliFs): TagRunResult;
+export { runTagSync, resolveNearestPackageVersion };
+export type { TagSyncExecutionInput, TagSyncRunDeps, } from "#lib/tag/application/use-cases/run-tag-sync.use-case";
+export { tagTargetResolverAdapter } from "#lib/tag/infra/tag-target-resolver.adapter";
+export type { TagFileResult, TagProgressListener, TagResolvedTarget, TagRunOptions, TagRunResult, TagSyncResult, TagTargetExecutionResult, } from "#lib/tag/domain/types.domain";
+export type { TagSyncOptions } from "#lib/tag/infra/tag-sync-cli-options.adapter";
+export { createTagProgressListener, formatProgress, formatSummary, formatTargetTable, formatWarningsAndErrors, } from "#lib/tag/presentation/tag-sync.presenter";
+export type { TagProgressEvent } from "#lib/tag/presentation/tag-sync.presenter";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/tag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/tag/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AACrE,OAAO,EACL,4BAA4B,EAE5B,UAAU,EACX,MAAM,sDAAsD,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAElF,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,KAAK,GAAG,YAAY,CAE/F;AAED,OAAO,EAAE,UAAU,EAAE,4BAA4B,EAAE,CAAC;AACpD,YAAY,EACV,qBAAqB,EACrB,cAAc,GACf,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AACtF,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAClF,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,0CAA0C,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC"}

package/dist/lib/tag/index.js

@@ -0,0 +1,10 @@
+import { resolveNearestPackageVersion, runTagOnTarget as runTagOnTargetWithTreeWalk, runTagSync, } from "#lib/tag/application/use-cases/run-tag-sync.use-case";
+import { tagTypeScriptTreeWalkAdapter } from "#lib/tag/infra/typescript-tree-walk.adapter";
+export { createNodeCliFs, createNodeCliLogger } from "#lib/infra/node-io.adapter";
+/** Default composition: uses the shared TS/TSX tree walk adapter. */
+export function runTagOnTarget(targetPath, opts, fs) {
+    return runTagOnTargetWithTreeWalk(targetPath, opts, fs, tagTypeScriptTreeWalkAdapter);
+}
+export { runTagSync, resolveNearestPackageVersion };
+export { tagTargetResolverAdapter } from "#lib/tag/infra/tag-target-resolver.adapter";
+export { createTagProgressListener, formatProgress, formatSummary, formatTargetTable, formatWarningsAndErrors, } from "#lib/tag/presentation/tag-sync.presenter";

package/dist/lib/tag/infra/tag-sync-cli-options.adapter.d.ts

@@ -0,0 +1,14 @@
+import type { CodefastTagConfig } from "#lib/config/domain/schema.domain";
+import type { CliFs } from "#lib/infra/fs-contract.port";
+import type { TagProgressListener } from "#lib/tag/domain/types.domain";
+/** CLI / container wiring: filesystem injected at the boundary. */
+export type TagSyncOptions = {
+    rootDir: string;
+    config?: CodefastTagConfig;
+    skipPackages?: string[];
+    targetPath?: string;
+    write: boolean;
+    fs: CliFs;
+    listener?: TagProgressListener;
+};
+//# sourceMappingURL=tag-sync-cli-options.adapter.d.ts.map

package/dist/lib/tag/infra/tag-sync-cli-options.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-sync-cli-options.adapter.d.ts","sourceRoot":"","sources":["../../../../src/lib/tag/infra/tag-sync-cli-options.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,mEAAmE;AACnE,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,EAAE,KAAK,CAAC;IACV,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC,CAAC"}