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

package/dist/lib/core/application/architecture-boundaries.policy.mjs

@@ -0,0 +1,311 @@
+//#region src/lib/core/application/architecture-boundaries.policy.ts
+/** Product bounded contexts: no direct cross-imports between these (domain + application rules). */ const PRODUCT_BOUNDED_CONTEXTS = new Set([
+	"arrange",
+	"mirror",
+	"tag"
+]);
+const SHARED_SOURCE_CODE_CONTEXT = "shared-source-code";
+const PATH_SEPARATOR = "/";
+const LAYERS = new Set([
+	"domain",
+	"application",
+	"infra",
+	"presentation"
+]);
+/** Import roots that any product slice may depend on without going "through" another slice. */ const NEUTRAL_LIB_IMPORT_ROOTS = new Set([
+	"core",
+	"config",
+	"infra",
+	"shared"
+]);
+/** Internal imports: tsconfig `#/*` → `src/*`. */ const INTERNAL_LIB_PREFIX = "#/lib/";
+function pathAfterInternalLibPrefix(specifier) {
+	if (!specifier.startsWith(INTERNAL_LIB_PREFIX)) return null;
+	return specifier.slice(6);
+}
+function internalLibSpecifierSegmentList(specifier) {
+	const afterPrefix = pathAfterInternalLibPrefix(specifier);
+	if (afterPrefix === null) return null;
+	const segments = afterPrefix.split(PATH_SEPARATOR).filter(Boolean);
+	return segments.length === 0 ? null : segments;
+}
+function normalizePathSeparators(pathValue) {
+	return pathValue.split("\\").join(PATH_SEPARATOR);
+}
+function splitPath(pathValue) {
+	return normalizePathSeparators(pathValue).split(PATH_SEPARATOR).filter(Boolean);
+}
+function basenamePath(pathValue) {
+	const parts = splitPath(pathValue);
+	return parts.length === 0 ? "" : parts[parts.length - 1] ?? "";
+}
+function dirnamePath(pathValue) {
+	const parts = normalizePathSeparators(pathValue).split(PATH_SEPARATOR);
+	parts.pop();
+	if (parts.length === 0) return PATH_SEPARATOR;
+	const joined = parts.join(PATH_SEPARATOR);
+	return joined === "" ? PATH_SEPARATOR : joined;
+}
+function joinPath(...segments) {
+	return segments.map((segment) => normalizePathSeparators(segment)).join(PATH_SEPARATOR).replace(/\/+/g, PATH_SEPARATOR);
+}
+function normalizeDotSegments(pathValue) {
+	const normalized = normalizePathSeparators(pathValue);
+	const isAbsolute = normalized.startsWith(PATH_SEPARATOR);
+	const segments = normalized.split(PATH_SEPARATOR);
+	const stack = [];
+	for (const segment of segments) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") {
+			if (stack.length > 0) stack.pop();
+			continue;
+		}
+		stack.push(segment);
+	}
+	const suffix = stack.join(PATH_SEPARATOR);
+	return isAbsolute ? `${PATH_SEPARATOR}${suffix}` : suffix;
+}
+function sharedSourceCodeLayerFromSpecifier(segments) {
+	if (segments.length < 3 || segments[0] !== "shared" || segments[1] !== "source-code") return null;
+	return segments[2] ?? null;
+}
+/**
+* Extract `#/lib/...` and relative import specifiers from TypeScript source
+* (static `from` / `import("...")` only).
+*/ function extractImportSpecifiers(sourceText) {
+	const specifiers = [];
+	const fromPattern = /\bfrom\s+["']([^"']+)["']/g;
+	let fromMatch;
+	while ((fromMatch = fromPattern.exec(sourceText)) !== null) {
+		const cap = fromMatch[1];
+		if (cap !== void 0) specifiers.push(cap);
+	}
+	const importOnlyPattern = /^\s*import\s+["']([^"']+)["']\s*;/gm;
+	let importOnlyMatch;
+	while ((importOnlyMatch = importOnlyPattern.exec(sourceText)) !== null) {
+		const cap = importOnlyMatch[1];
+		if (cap !== void 0) specifiers.push(cap);
+	}
+	const importCallPattern = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+	let importCallMatch;
+	while ((importCallMatch = importCallPattern.exec(sourceText)) !== null) {
+		const cap = importCallMatch[1];
+		if (cap !== void 0) specifiers.push(cap);
+	}
+	return specifiers;
+}
+function pathUnderCliSrcLib(absolutePath) {
+	const normalized = normalizePathSeparators(absolutePath);
+	const marker = `${PATH_SEPARATOR}src${PATH_SEPARATOR}lib${PATH_SEPARATOR}`;
+	const index = normalized.lastIndexOf(marker);
+	if (index === -1) return null;
+	return normalized.slice(index + marker.length);
+}
+function parseLibSourceLocation(absoluteFilePath) {
+	const tail = pathUnderCliSrcLib(absoluteFilePath);
+	if (tail === null) return null;
+	const parts = tail.split(PATH_SEPARATOR).filter(Boolean);
+	if (parts.length < 2) return null;
+	if (parts[0] === "shared" && parts[1] === "source-code" && parts.length >= 3) {
+		const layer = parts[2];
+		if (layer === void 0 || !LAYERS.has(layer)) return null;
+		const rest = parts.slice(3);
+		if (layer === "domain" && rest[0] === "__tests__") return {
+			context: SHARED_SOURCE_CODE_CONTEXT,
+			layer: "domain"
+		};
+		return {
+			context: SHARED_SOURCE_CODE_CONTEXT,
+			layer
+		};
+	}
+	const context = parts[0];
+	const layer = parts[1];
+	const rest = parts.slice(2);
+	if (context === void 0 || layer === void 0 || !LAYERS.has(layer)) return null;
+	if (layer === "domain" && rest[0] === "__tests__") return {
+		context,
+		layer
+	};
+	return {
+		context,
+		layer
+	};
+}
+function isArchitectureExcludedSourceFile(absoluteFilePath) {
+	const base = basenamePath(absoluteFilePath);
+	if (base.endsWith(".test.ts") || base.endsWith(".integration.test.ts")) return true;
+	return normalizePathSeparators(absoluteFilePath).split(PATH_SEPARATOR).includes("__tests__");
+}
+function resolveRelativeSpecifier(fromAbsoluteFile, specifier) {
+	if (!specifier.startsWith(".")) return null;
+	return normalizeDotSegments(joinPath(dirnamePath(fromAbsoluteFile), specifier));
+}
+function libTailAfterResolution(absoluteResolved) {
+	const tail = pathUnderCliSrcLib(absoluteResolved);
+	if (tail === null) return null;
+	return tail.split(PATH_SEPARATOR).filter(Boolean);
+}
+function lastSegmentOfLibSpecifier(specifier) {
+	const segments = internalLibSpecifierSegmentList(specifier);
+	if (segments === null) return null;
+	return segments[segments.length - 1] ?? null;
+}
+function importedModuleStem(specifier, fromAbsoluteFile) {
+	if (pathAfterInternalLibPrefix(specifier) !== null) return lastSegmentOfLibSpecifier(specifier);
+	const resolved = resolveRelativeSpecifier(fromAbsoluteFile, specifier);
+	if (resolved === null) return null;
+	const baseName = basenamePath(resolved.endsWith(".ts") ? resolved : `${resolved}.ts`);
+	return baseName.endsWith(".ts") ? baseName.slice(0, -3) : baseName;
+}
+function isPureDomainOrModelFileName(fileBaseName) {
+	return /\.(domain|model)\.ts$/.test(fileBaseName);
+}
+function isRuleAForbiddenImportedStem(moduleStem) {
+	return moduleStem.includes(".use-case") || moduleStem.includes(".adapter") || moduleStem.includes(".presenter");
+}
+function isRuleBForbiddenImportedStem(moduleStem) {
+	return moduleStem.includes(".adapter") || moduleStem.includes(".presenter");
+}
+function violationRuleAPureDomainModel(absoluteFilePath, fileBaseName, specifier) {
+	if (!isPureDomainOrModelFileName(fileBaseName)) return null;
+	const stem = importedModuleStem(specifier, absoluteFilePath);
+	if (stem === null || !isRuleAForbiddenImportedStem(stem)) return null;
+	return `${absoluteFilePath}: Rule A (pure domain/model) must not import orchestration or IO modules — blocked ${specifier} (stem "${stem}")`;
+}
+function violationRuleBApplicationIsolation(loc, absoluteFilePath, specifier) {
+	if (loc.layer !== "application") return null;
+	const stem = importedModuleStem(specifier, absoluteFilePath);
+	if (stem === null || !isRuleBForbiddenImportedStem(stem)) return null;
+	return `${absoluteFilePath}: Rule B (application isolation) must not import adapters or presenters — blocked ${specifier} (stem "${stem}")`;
+}
+function violationRuleCAntiCrossSlice(loc, specifier, fromAbsoluteFile) {
+	if (!PRODUCT_BOUNDED_CONTEXTS.has(loc.context)) return null;
+	const ruleCSegments = internalLibSpecifierSegmentList(specifier);
+	if (ruleCSegments !== null) {
+		const importedRoot = ruleCSegments[0];
+		if (importedRoot === void 0 || NEUTRAL_LIB_IMPORT_ROOTS.has(importedRoot)) return null;
+		if (importedRoot === loc.context) return null;
+		if (PRODUCT_BOUNDED_CONTEXTS.has(importedRoot)) return `${fromAbsoluteFile}: Rule C (slice isolation) context "${loc.context}" must not import "${specifier}" — use #/lib/shared/... or neutral roots (core, config, infra) instead`;
+		return null;
+	}
+	const resolved = resolveRelativeSpecifier(fromAbsoluteFile, specifier);
+	if (resolved === null) return null;
+	const parts = libTailAfterResolution(resolved.endsWith(".ts") ? resolved : `${resolved}.ts`);
+	if (parts === null || parts.length === 0) return null;
+	const importedContext = parts[0];
+	if (importedContext === void 0 || NEUTRAL_LIB_IMPORT_ROOTS.has(importedContext)) return null;
+	if (importedContext === loc.context) return null;
+	if (PRODUCT_BOUNDED_CONTEXTS.has(importedContext)) return `${fromAbsoluteFile}: Rule C (slice isolation) context "${loc.context}" must not resolve into sibling slice via ${specifier}`;
+	return null;
+}
+function violationDomainLayer(loc, specifier, fromAbsoluteFile) {
+	const domainSegments = internalLibSpecifierSegmentList(specifier);
+	if (domainSegments !== null) {
+		const segments = domainSegments;
+		if (segments[0] === "infra") return `${fromAbsoluteFile}: domain must not import ${specifier}`;
+		const sharedLayerImported = sharedSourceCodeLayerFromSpecifier(segments);
+		if (sharedLayerImported !== null && sharedLayerImported !== "domain") return `${fromAbsoluteFile}: domain must not import ${specifier}`;
+		if (segments[0] === loc.context && segments.length >= 2) {
+			const importLayer = segments[1];
+			if (importLayer === "application" || importLayer === "infra" || importLayer === "presentation") return `${fromAbsoluteFile}: domain must not import ${specifier}`;
+		}
+		const segmentZero = segments[0];
+		if (segments.length >= 2 && segments[1] === "domain" && segmentZero !== void 0 && PRODUCT_BOUNDED_CONTEXTS.has(segmentZero) && segmentZero !== loc.context) return `${fromAbsoluteFile}: domain (${loc.context}) must not import other bounded context domain ${specifier}`;
+		if (loc.context === "core" && segments.length >= 2 && segments[1] === "domain" && segmentZero !== void 0 && PRODUCT_BOUNDED_CONTEXTS.has(segmentZero)) return `${fromAbsoluteFile}: core/domain must not import bounded context domain ${specifier}`;
+		if (loc.context === "config" && segments.length >= 2 && segments[1] === "domain" && segmentZero !== void 0 && PRODUCT_BOUNDED_CONTEXTS.has(segmentZero)) return `${fromAbsoluteFile}: config/domain must not import bounded context domain ${specifier}`;
+		if (loc.context === SHARED_SOURCE_CODE_CONTEXT && segmentZero !== void 0 && PRODUCT_BOUNDED_CONTEXTS.has(segmentZero)) return `${fromAbsoluteFile}: shared source-code domain must not import product context ${specifier}`;
+		return null;
+	}
+	const resolved = resolveRelativeSpecifier(fromAbsoluteFile, specifier);
+	if (resolved === null) return null;
+	const parts = libTailAfterResolution(resolved);
+	if (parts === null || parts.length < 2) return null;
+	const relCtx = parts[0];
+	const relLayer = parts[1];
+	if (relCtx === void 0 || relLayer === void 0) return null;
+	if (relCtx === "infra") return `${fromAbsoluteFile}: domain must not resolve into infra via ${specifier}`;
+	if (relCtx === loc.context) {
+		if (relLayer === "application" || relLayer === "infra" || relLayer === "presentation") return `${fromAbsoluteFile}: domain must not resolve into ${relLayer} via ${specifier}`;
+	}
+	if (relLayer === "domain" && PRODUCT_BOUNDED_CONTEXTS.has(relCtx) && relCtx !== loc.context) return `${fromAbsoluteFile}: domain must not resolve into other bounded context domain via ${specifier}`;
+	if (loc.context === "core" && relLayer === "domain" && PRODUCT_BOUNDED_CONTEXTS.has(relCtx)) return `${fromAbsoluteFile}: core/domain must not resolve into bounded context domain via ${specifier}`;
+	return null;
+}
+function violationApplicationLayer(loc, specifier, fromAbsoluteFile) {
+	const applicationSegments = internalLibSpecifierSegmentList(specifier);
+	if (applicationSegments !== null) {
+		const segments = applicationSegments;
+		if (segments[0] === "infra") return `${fromAbsoluteFile}: application must not import ${specifier}`;
+		const sharedLayerImported = sharedSourceCodeLayerFromSpecifier(segments);
+		if (sharedLayerImported === "infra" || sharedLayerImported === "presentation" || sharedLayerImported === "application") return `${fromAbsoluteFile}: application must not import ${specifier}`;
+		if (segments.length >= 2 && (segments[1] === "infra" || segments[1] === "presentation")) return `${fromAbsoluteFile}: application must not import ${specifier}`;
+		const appSegmentZero = segments[0];
+		if (PRODUCT_BOUNDED_CONTEXTS.has(loc.context) && appSegmentZero !== void 0 && PRODUCT_BOUNDED_CONTEXTS.has(appSegmentZero) && appSegmentZero !== loc.context) return `${fromAbsoluteFile}: application (${loc.context}) must not import ${specifier}`;
+		return null;
+	}
+	const resolved = resolveRelativeSpecifier(fromAbsoluteFile, specifier);
+	if (resolved === null) return null;
+	const parts = libTailAfterResolution(resolved);
+	if (parts === null || parts.length < 2) return null;
+	const relCtx = parts[0];
+	const relLayer = parts[1];
+	if (relCtx === void 0 || relLayer === void 0) return null;
+	if (relCtx === "infra") return `${fromAbsoluteFile}: application must not resolve into infra via ${specifier}`;
+	if (relLayer === "infra" || relLayer === "presentation") return `${fromAbsoluteFile}: application must not resolve into ${relLayer} via ${specifier}`;
+	return null;
+}
+/**
+* Returns human-readable violations for a single file's imports (for unit tests and tooling).
+*/ function violationsForFileContent(absoluteFilePath, loc, sourceText) {
+	const violations = [];
+	const fileBaseName = basenamePath(absoluteFilePath);
+	for (const specifier of extractImportSpecifiers(sourceText)) {
+		const ruleA = violationRuleAPureDomainModel(absoluteFilePath, fileBaseName, specifier);
+		if (ruleA !== null) violations.push(ruleA);
+		const ruleB = violationRuleBApplicationIsolation(loc, absoluteFilePath, specifier);
+		if (ruleB !== null) violations.push(ruleB);
+		const ruleC = violationRuleCAntiCrossSlice(loc, specifier, absoluteFilePath);
+		if (ruleC !== null) violations.push(ruleC);
+		if (loc.layer === "domain") {
+			const domainViolation = violationDomainLayer(loc, specifier, absoluteFilePath);
+			if (domainViolation !== null) violations.push(domainViolation);
+		} else if (loc.layer === "application") {
+			const appViolation = violationApplicationLayer(loc, specifier, absoluteFilePath);
+			if (appViolation !== null) violations.push(appViolation);
+		}
+	}
+	return [...new Set(violations)];
+}
+function walkNonTestTsFiles(rootDir, fs) {
+	const results = [];
+	const scan = (dir) => {
+		for (const entryName of fs.readdirSync(dir)) {
+			const full = joinPath(dir, entryName);
+			const stat = fs.statSync(full);
+			if (stat.isDirectory()) {
+				if (entryName === "node_modules" || entryName === "dist") continue;
+				scan(full);
+			} else if (stat.isFile() && entryName.endsWith(".ts")) {
+				if (!isArchitectureExcludedSourceFile(full)) results.push(full);
+			}
+		}
+	};
+	scan(rootDir);
+	return results;
+}
+/**
+* Scans `packages/cli/src/lib` for explicit-architecture boundary violations (non-test sources only).
+*/ function scanCliPackageArchitectureViolations(cliPackageRoot, fs, pathService) {
+	const libRoot = pathService.join(cliPackageRoot, "src", "lib");
+	const violations = [];
+	for (const absoluteFilePath of walkNonTestTsFiles(libRoot, fs)) {
+		const loc = parseLibSourceLocation(absoluteFilePath);
+		if (loc === null) continue;
+		const sourceText = fs.readFileSync(absoluteFilePath, "utf8");
+		violations.push(...violationsForFileContent(absoluteFilePath, loc, sourceText));
+	}
+	return violations;
+}
+//#endregion
+export { extractImportSpecifiers, isArchitectureExcludedSourceFile, parseLibSourceLocation, scanCliPackageArchitectureViolations, violationsForFileContent };

package/dist/lib/core/application/ports/path.port.mjs

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

package/dist/lib/core/application/schema-parse.util.mjs

@@ -0,0 +1,17 @@
+import { appError } from "../domain/errors.domain.mjs";
+import { err, ok } from "../domain/result.model.mjs";
+//#region src/lib/core/application/schema-parse.util.ts
+function formatSchemaIssues(issues) {
+	return issues.map((issue) => {
+		return `${issue.path.length > 0 ? `${issue.path.join(".")}: ` : ""}${issue.message}`;
+	}).join("; ");
+}
+/**
+* Validates `input` with `schema`, returning {@link AppError} with code `VALIDATION_ERROR` on failure.
+*/ function parseWithSchema(schema, input) {
+	const parsed = schema.safeParse(input);
+	if (!parsed.success) return err(appError("VALIDATION_ERROR", formatSchemaIssues(parsed.error.issues)));
+	return ok(parsed.data);
+}
+//#endregion
+export { parseWithSchema };

package/dist/lib/core/application/utils/caught-unknown-message.util.mjs

@@ -0,0 +1,19 @@
+//#region src/lib/core/application/utils/caught-unknown-message.util.ts
+/**
+* Stable, user-facing text for values caught as `unknown`.
+* Avoids `String(unknown)` / `[object Object]` and satisfies strict `no-base-to-string`.
+*/ function messageFromCaughtUnknown(value) {
+	if (value instanceof Error) return value.message;
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return String(value);
+	if (typeof value === "symbol") return String(value);
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	try {
+		const serialized = JSON.stringify(value);
+		if (typeof serialized === "string") return serialized;
+	} catch {}
+	return "[unserializable non-Error value]";
+}
+//#endregion
+export { messageFromCaughtUnknown };

package/dist/lib/core/application/utils/verbose-diagnostics.util.mjs

@@ -0,0 +1,9 @@
+//#region src/lib/core/application/utils/verbose-diagnostics.util.ts
+/**
+* When true, infrastructure failures may log full stack traces (e.g. in {@link consumeCliAppError}).
+*/ function isVerboseInfraDiagnostics() {
+	const raw = process.env.CODEFAST_VERBOSE;
+	return raw === "1" || raw === "true";
+}
+//#endregion
+export { isVerboseInfraDiagnostics };

package/dist/lib/core/contracts/presentation.contract.mjs

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

package/dist/lib/core/contracts/tokens.mjs

@@ -0,0 +1,5 @@
+import { token } from "@codefast/di";
+//#region src/lib/core/contracts/tokens.ts
+const TryLoadCodefastConfigPresenterToken = token("TryLoadCodefastConfigPresenter");
+//#endregion
+export { TryLoadCodefastConfigPresenterToken };

package/dist/lib/core/core.module.mjs

@@ -0,0 +1,9 @@
+import { CliPathToken } from "./operational/contracts/tokens.mjs";
+import { nodeCliPath } from "./infra/path.adapter.mjs";
+import { Module } from "@codefast/di";
+//#region src/lib/core/core.module.ts
+const CoreModule = Module.create("cli-core", (moduleBuilder) => {
+	moduleBuilder.bind(CliPathToken).toConstantValue(nodeCliPath);
+});
+//#endregion
+export { CoreModule };

package/dist/lib/core/domain/cli-exit-codes.domain.mjs

@@ -0,0 +1,11 @@
+//#region src/lib/core/domain/cli-exit-codes.domain.ts
+/**
+* Process exit codes for the `codefast` CLI.
+*
+* Conventions align with common Unix tooling: `0` success, `1` general failure,
+* `2` for invalid invocation (schema / options), matching GNU `sysexits` `EX_USAGE` spirit.
+*/ const CLI_EXIT_SUCCESS = 0;
+const CLI_EXIT_GENERAL_ERROR = 1;
+const CLI_EXIT_USAGE = 2;
+//#endregion
+export { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS, CLI_EXIT_USAGE };

package/dist/lib/core/domain/errors.domain.mjs

@@ -0,0 +1,16 @@
+//#region src/lib/core/domain/errors.domain.ts
+/**
+* Cross-context application errors for Result-based use cases (CLI orchestration).
+*/ function appError(code, message, cause) {
+	if (cause === void 0) return {
+		code,
+		message
+	};
+	return {
+		code,
+		message,
+		cause
+	};
+}
+//#endregion
+export { appError };

package/dist/lib/core/domain/result.model.mjs

@@ -0,0 +1,23 @@
+//#region src/lib/core/domain/result.model.ts
+/**
+* Lightweight functional Result type for use-case boundaries.
+*/ function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function isOk(result) {
+	return result.ok === true;
+}
+function isErr(result) {
+	return result.ok === false;
+}
+//#endregion
+export { err, isErr, isOk, ok };

package/dist/lib/core/infra/composition-root.mjs

@@ -0,0 +1,21 @@
+import { registerArrangeFeature, resolveArrangeCommand } from "../../arrange/arrange.feature.module.mjs";
+import { registerMirrorFeature, resolveMirrorCommand } from "../../mirror/mirror.feature.module.mjs";
+import { registerTagFeature, resolveTagCommand } from "../../tag/tag.feature.module.mjs";
+import { Container } from "@codefast/di";
+//#region src/lib/core/infra/composition-root.ts
+function createCliRuntimeContainer() {
+	const runtimeContainer = Container.create();
+	registerArrangeFeature(runtimeContainer);
+	registerMirrorFeature(runtimeContainer);
+	registerTagFeature(runtimeContainer);
+	return runtimeContainer;
+}
+function resolveCliCommands(runtimeContainer) {
+	return [
+		resolveArrangeCommand(runtimeContainer),
+		resolveMirrorCommand(runtimeContainer),
+		resolveTagCommand(runtimeContainer)
+	];
+}
+//#endregion
+export { createCliRuntimeContainer, resolveCliCommands };

package/dist/lib/core/infra/infra.module.mjs

@@ -0,0 +1,23 @@
+import { CliFsToken, CliLoggerToken } from "../operational/contracts/tokens.mjs";
+import { ConfigLoaderPortToken } from "../../config/contracts/tokens.mjs";
+import { configLoaderAdapter } from "../../config/infra/loader.adapter.mjs";
+import { CoreModule } from "../core.module.mjs";
+import { isCliTelemetryEnabled, withCliPortTelemetry } from "./logging-decorator.adapter.mjs";
+import { NodeCliFsAdapter as _NodeCliFsAdapter, NodeCliLoggerAdapter as _NodeCliLoggerAdapter } from "../../infra/node-io.adapter.mjs";
+import { Module } from "@codefast/di";
+//#region src/lib/core/infra/infra.module.ts
+const InfraModule = Module.create("cli-infra", (moduleBuilder) => {
+	moduleBuilder.import(CoreModule);
+	moduleBuilder.bind(CliLoggerToken).to(_NodeCliLoggerAdapter).singleton();
+	moduleBuilder.bind(CliFsToken).to(_NodeCliFsAdapter).onActivation((ctx, rawFs) => {
+		if (!isCliTelemetryEnabled()) return rawFs;
+		return withCliPortTelemetry({
+			portName: "CliFs",
+			implementation: rawFs,
+			logger: ctx.resolve(CliLoggerToken)
+		});
+	}).singleton();
+	moduleBuilder.bind(ConfigLoaderPortToken).toConstantValue(configLoaderAdapter);
+});
+//#endregion
+export { InfraModule };

package/dist/lib/core/infra/logging-decorator.adapter.mjs

@@ -0,0 +1,62 @@
+//#region src/lib/core/infra/logging-decorator.adapter.ts
+function summarizeTelemetryArg(value, maxLen = 160) {
+	if (typeof value === "string") return value.length > maxLen ? `${value.slice(0, maxLen)}…(${value.length} chars)` : value;
+	if (value === null || value === void 0) return String(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "object") try {
+		const json = JSON.stringify(value);
+		if (typeof json === "string") return json.length > maxLen ? `${json.slice(0, maxLen)}…` : json;
+	} catch {
+		return "[object]";
+	}
+	return "[value]";
+}
+function isPromiseLike(value) {
+	return value !== null && typeof value === "object" && "then" in value && typeof value.then === "function";
+}
+/**
+* Wraps a port implementation (object of functions) to log call timing and summarized arguments via `logger`.
+* Does not modify application or domain code — wire only from the composition root.
+*/ function withCliPortTelemetry(args) {
+	const { portName, implementation, logger } = args;
+	return new Proxy(implementation, { get(target, propertyKey, receiver) {
+		if (typeof propertyKey === "symbol") return Reflect.get(target, propertyKey, receiver);
+		const propertyName = String(propertyKey);
+		const value = Reflect.get(target, propertyKey, receiver);
+		if (typeof value !== "function") return value;
+		return (...callArgs) => {
+			const argSummary = callArgs.map((arg) => summarizeTelemetryArg(arg)).join(", ");
+			logger.out(`[telemetry:${portName}.${propertyName}] ← (${argSummary})`);
+			const startedAt = performance.now();
+			try {
+				const result = value.apply(target, callArgs);
+				if (isPromiseLike(result)) return result.then((resolved) => {
+					logger.out(`[telemetry:${portName}.${propertyName}] → ok ${(performance.now() - startedAt).toFixed(2)}ms`);
+					return resolved;
+				}, (rejection) => {
+					logger.out(`[telemetry:${portName}.${propertyName}] → err ${(performance.now() - startedAt).toFixed(2)}ms`);
+					throw rejection;
+				});
+				logger.out(`[telemetry:${portName}.${propertyName}] → ${(performance.now() - startedAt).toFixed(2)}ms`);
+				return result;
+			} catch (caughtSyncError) {
+				logger.out(`[telemetry:${portName}.${propertyName}] → err ${(performance.now() - startedAt).toFixed(2)}ms`);
+				throw caughtSyncError;
+			}
+		};
+	} });
+}
+function isCliTelemetryEnabled() {
+	const raw = process.env.ENABLE_TELEMETRY;
+	return raw === "1" || raw === "true";
+}
+function withOptionalPortTelemetry(portName, implementation, logger) {
+	if (!isCliTelemetryEnabled()) return implementation;
+	return withCliPortTelemetry({
+		portName,
+		implementation,
+		logger
+	});
+}
+//#endregion
+export { isCliTelemetryEnabled, withCliPortTelemetry, withOptionalPortTelemetry };

package/dist/lib/core/infra/path.adapter.mjs

@@ -0,0 +1,13 @@
+import path from "node:path";
+//#region src/lib/core/infra/path.adapter.ts
+const nodeCliPath = {
+	resolve: (...paths) => path.resolve(...paths),
+	join: (...paths) => path.join(...paths),
+	relative: (from, to) => path.relative(from, to),
+	dirname: (pathValue) => path.dirname(pathValue),
+	basename: (pathValue) => path.basename(pathValue),
+	extname: (pathValue) => path.extname(pathValue),
+	separator: path.sep
+};
+//#endregion
+export { nodeCliPath };

package/dist/lib/core/operational/contracts/tokens.mjs

@@ -0,0 +1,7 @@
+import { token } from "@codefast/di";
+//#region src/lib/core/operational/contracts/tokens.ts
+const CliFsToken = token("CliFs");
+const CliLoggerToken = token("CliLogger");
+const CliPathToken = token("CliPath");
+//#endregion
+export { CliFsToken, CliLoggerToken, CliPathToken };

package/dist/lib/core/presentation/cli-executor.presenter.mjs

@@ -0,0 +1,57 @@
+import "../domain/cli-exit-codes.domain.mjs";
+import { formatAppError } from "./format-app-error.presenter.mjs";
+import { isVerboseInfraDiagnostics } from "../application/utils/verbose-diagnostics.util.mjs";
+import process from "node:process";
+//#region src/lib/core/presentation/cli-executor.presenter.ts
+function assertExhaustiveAppErrorCode(code) {
+	return code;
+}
+/**
+* Maps {@link AppError} codes to `process.exitCode` for CLI commands.
+*/ function exitCodeForAppError(error) {
+	const { code } = error;
+	switch (code) {
+		case "NOT_FOUND": return 1;
+		case "VALIDATION_ERROR": return 2;
+		case "INFRA_FAILURE": return 1;
+		default: return assertExhaustiveAppErrorCode(code);
+	}
+}
+/**
+* When `outcome` is {@link Err}, logs via {@link formatAppError}, sets `process.exitCode`, returns `false`.
+* When `Ok`, optionally logs `successMessage` to stdout and returns `true`.
+*/ function consumeCliAppError(logger, outcome, options) {
+	if (!outcome.ok) {
+		logger.err(formatAppError(outcome.error));
+		if (isVerboseInfraDiagnostics() && outcome.error.code === "INFRA_FAILURE" && outcome.error.cause instanceof Error && outcome.error.cause.stack !== void 0) logger.err(outcome.error.cause.stack);
+		process.exitCode = exitCodeForAppError(outcome.error);
+		return false;
+	}
+	if (options?.successMessage !== void 0) logger.out(options.successMessage);
+	return true;
+}
+/**
+* Awaits a use case and applies the same handling as {@link consumeCliAppError}.
+*/ async function consumeCliAppErrorAsync(logger, outcomePromise, options) {
+	const outcome = await outcomePromise;
+	consumeCliAppError(logger, outcome, options);
+	return outcome;
+}
+/**
+* Completes CLI handling: errors are logged and `process.exitCode` is set; success runs `onSuccess`
+* and assigns `process.exitCode` from its return value (default `0`).
+*/ function runCliResult(logger, outcome, onSuccess) {
+	if (!consumeCliAppError(logger, outcome)) return;
+	const exit = onSuccess(outcome.value);
+	process.exitCode = exit === void 0 ? 0 : exit;
+}
+/**
+* Async variant of {@link runCliResult}.
+*/ async function runCliResultAsync(logger, outcomePromise, onSuccess) {
+	const outcome = await outcomePromise;
+	if (!consumeCliAppError(logger, outcome)) return;
+	const exit = await onSuccess(outcome.value);
+	process.exitCode = exit === void 0 ? 0 : exit;
+}
+//#endregion
+export { consumeCliAppError, consumeCliAppErrorAsync, exitCodeForAppError, runCliResult, runCliResultAsync };

package/dist/lib/core/presentation/command.interface.mjs

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

package/dist/lib/core/presentation/format-app-error.presenter.mjs

@@ -0,0 +1,17 @@
+//#region src/lib/core/presentation/format-app-error.presenter.ts
+function assertExhaustiveAppErrorCode(code) {
+	return `Unhandled error code: ${String(code)}`;
+}
+/**
+* Stable, user-facing line for CLI output. Exhaustive over every `AppError["code"]`.
+*/ function formatAppError(error) {
+	const { code, message } = error;
+	switch (code) {
+		case "NOT_FOUND": return `[NOT_FOUND] ${message}`;
+		case "VALIDATION_ERROR": return `[VALIDATION_ERROR] ${message}`;
+		case "INFRA_FAILURE": return `[INFRA_FAILURE] ${message}`;
+		default: return assertExhaustiveAppErrorCode(code);
+	}
+}
+//#endregion
+export { formatAppError };

package/dist/lib/core/presentation/global-cli-options.presenter.mjs

@@ -0,0 +1,9 @@
+import { parseWithSchema } from "../application/schema-parse.util.mjs";
+import { z } from "zod";
+//#region src/lib/core/presentation/global-cli-options.presenter.ts
+const globalCliOptionsSchema = z.object({ color: z.boolean().optional() });
+function parseGlobalCliOptions(raw) {
+	return parseWithSchema(globalCliOptionsSchema, raw);
+}
+//#endregion
+export { globalCliOptionsSchema, parseGlobalCliOptions };