@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/shared/id-suggestions.js

@@ -0,0 +1,48 @@
+function normalizeCloseId(value) {
+    return value.trim().toLowerCase();
+}
+function getEditDistance(left, right) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    const current = new Array(right.length + 1);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        current[0] = leftIndex + 1;
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;
+            current[rightIndex + 1] = Math.min(current[rightIndex] + 1, previous[rightIndex + 1] + 1, previous[rightIndex] + substitutionCost);
+        }
+        for (let index = 0; index < current.length; index += 1) {
+            previous[index] = current[index];
+        }
+    }
+    return previous[right.length];
+}
+/**
+ * Suggest the closest known id for a user-provided CLI value.
+ *
+ * This helper is intentionally generic so command-specific validation can keep
+ * its own wording and special-case handling while sharing typo thresholds.
+ */
+export function suggestCloseId(input, candidates, options = {}) {
+    const normalize = options.normalize ?? normalizeCloseId;
+    const normalizedInput = normalize(input);
+    if (normalizedInput.length === 0) {
+        return null;
+    }
+    const maxDistance = options.maxDistance ?? 2;
+    if (maxDistance < 0) {
+        return null;
+    }
+    let bestCandidate = null;
+    for (const candidateId of candidates) {
+        const distance = getEditDistance(normalizedInput, normalize(candidateId));
+        if (bestCandidate === null || distance < bestCandidate.distance) {
+            bestCandidate = {
+                distance,
+                id: candidateId,
+            };
+        }
+    }
+    return bestCandidate && bestCandidate.distance <= maxDistance
+        ? bestCandidate.id
+        : null;
+}

package/dist/runtime/shared/json-utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * JSON helpers shared by project-tools runtime modules.
+ *
+ * File-backed runtime JSON readers should use `safeJsonParse`,
+ * `readJsonFileSync`, or `readJsonFile` so malformed JSON reports the file path
+ * and operation context. Raw `JSON.parse` remains intentional for trusted
+ * in-memory clones, subprocess output, test fixtures, and generated workspace
+ * script templates that embed their own path-aware parse handling.
+ *
+ * This module keeps `cloneJsonValue` local instead of re-exporting the
+ * block-runtime helper so CLI runtime bundles that only need project-tools JSON
+ * readers do not need to resolve the block-runtime subpath at runtime.
+ *
+ * @module
+ */
+/**
+ * Create a deep clone of a JSON-serializable value.
+ *
+ * @remarks
+ * Values that are not JSON-serializable, such as functions, `undefined`,
+ * `BigInt`, class instances, and `Date` objects, are not preserved faithfully.
+ *
+ * @param value JSON-compatible data to clone.
+ * @returns A deep-cloned copy created with `JSON.parse(JSON.stringify(...))`.
+ */
+export declare function cloneJsonValue<T>(value: T): T;
+/**
+ * Optional metadata used to enrich JSON parse errors.
+ */
+export interface SafeJsonParseOptions {
+    /** Human-readable operation label included in parse failures. */
+    context?: string;
+    /** Source file path included in parse failures when available. */
+    filePath?: string;
+}
+/**
+ * Parse JSON and include operation/file context when decoding fails.
+ *
+ * @param source Raw JSON source text.
+ * @param options Optional file path and human-readable operation context.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ * @throws {Error} When the source is malformed JSON.
+ */
+export declare function safeJsonParse<T = unknown>(source: string, options?: SafeJsonParseOptions): T;
+/**
+ * Read and parse a JSON file synchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export declare function readJsonFileSync<T = unknown>(filePath: string, options?: Omit<SafeJsonParseOptions, "filePath">): T;
+/**
+ * Read and parse a JSON file asynchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export declare function readJsonFile<T = unknown>(filePath: string, options?: Omit<SafeJsonParseOptions, "filePath">): Promise<T>;

package/dist/runtime/shared/json-utils.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+/**
+ * JSON helpers shared by project-tools runtime modules.
+ *
+ * File-backed runtime JSON readers should use `safeJsonParse`,
+ * `readJsonFileSync`, or `readJsonFile` so malformed JSON reports the file path
+ * and operation context. Raw `JSON.parse` remains intentional for trusted
+ * in-memory clones, subprocess output, test fixtures, and generated workspace
+ * script templates that embed their own path-aware parse handling.
+ *
+ * This module keeps `cloneJsonValue` local instead of re-exporting the
+ * block-runtime helper so CLI runtime bundles that only need project-tools JSON
+ * readers do not need to resolve the block-runtime subpath at runtime.
+ *
+ * @module
+ */
+/**
+ * Create a deep clone of a JSON-serializable value.
+ *
+ * @remarks
+ * Values that are not JSON-serializable, such as functions, `undefined`,
+ * `BigInt`, class instances, and `Date` objects, are not preserved faithfully.
+ *
+ * @param value JSON-compatible data to clone.
+ * @returns A deep-cloned copy created with `JSON.parse(JSON.stringify(...))`.
+ */
+export function cloneJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function formatJsonParseTarget({ context, filePath }) {
+    const operation = context?.trim() || "JSON";
+    return filePath ? `${operation} at ${filePath}` : operation;
+}
+/**
+ * Parse JSON and include operation/file context when decoding fails.
+ *
+ * @param source Raw JSON source text.
+ * @param options Optional file path and human-readable operation context.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ * @throws {Error} When the source is malformed JSON.
+ */
+export function safeJsonParse(source, options = {}) {
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${formatJsonParseTarget(options)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Read and parse a JSON file synchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export function readJsonFileSync(filePath, options = {}) {
+    return safeJsonParse(fs.readFileSync(filePath, "utf8"), {
+        ...options,
+        filePath,
+    });
+}
+/**
+ * Read and parse a JSON file asynchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export async function readJsonFile(filePath, options = {}) {
+    return safeJsonParse(await fsp.readFile(filePath, "utf8"), {
+        ...options,
+        filePath,
+    });
+}

package/dist/runtime/shared/object-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generic record type used for JSON-like plain-object inspection.
+ */
+export type UnknownRecord<TValue = unknown> = Record<string, TValue>;
+/**
+ * Delegate plain-object detection to the shared runtime primitive owner.
+ *
+ * @param value Runtime value to inspect.
+ * @returns `true` when the value is a non-null plain object with an
+ * `Object.prototype` or `null` prototype.
+ */
+export declare function isPlainObject(value: unknown): value is UnknownRecord;
+/**
+ * Serialize JSON-like values with deterministic plain-object key ordering.
+ *
+ * Arrays preserve their declared order, while plain objects are normalized by
+ * sorting keys recursively before calling `JSON.stringify`.
+ */
+export declare function stableJsonStringify(value: unknown): string;

package/dist/runtime/shared/object-utils.js

@@ -0,0 +1,31 @@
+import { isPlainObject as isSharedPlainObject } from '@wp-typia/api-client/runtime-primitives';
+/**
+ * Delegate plain-object detection to the shared runtime primitive owner.
+ *
+ * @param value Runtime value to inspect.
+ * @returns `true` when the value is a non-null plain object with an
+ * `Object.prototype` or `null` prototype.
+ */
+export function isPlainObject(value) {
+    return isSharedPlainObject(value);
+}
+function toStableJsonValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => toStableJsonValue(entry));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort((left, right) => left < right ? -1 : left > right ? 1 : 0)
+            .map((key) => [key, toStableJsonValue(value[key])]));
+    }
+    return value;
+}
+/**
+ * Serialize JSON-like values with deterministic plain-object key ordering.
+ *
+ * Arrays preserve their declared order, while plain objects are normalized by
+ * sorting keys recursively before calling `JSON.stringify`.
+ */
+export function stableJsonStringify(value) {
+    return JSON.stringify(toStableJsonValue(value));
+}

package/dist/runtime/shared/package-json-types.d.ts

@@ -0,0 +1,12 @@
+export interface GeneratedPackageJson {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    packageManager?: string;
+    scripts?: Record<string, string>;
+    wpTypia?: {
+        projectType?: string;
+        templatePackage?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}

package/dist/runtime/shared/package-json-types.js

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

package/dist/runtime/shared/package-managers.d.ts

@@ -0,0 +1,55 @@
+export type PackageManagerId = "bun" | "npm" | "pnpm" | "yarn";
+export interface PackageManagerDefinition {
+    id: PackageManagerId;
+    label: string;
+    packageManagerField: string;
+    installCommand: string;
+    frozenInstallCommand: string;
+}
+export declare const PACKAGE_MANAGER_IDS: PackageManagerId[];
+export declare const PACKAGE_MANAGERS: Readonly<Record<PackageManagerId, PackageManagerDefinition>>;
+export declare function getPackageManager(id: string): PackageManagerDefinition;
+/**
+ * Parse a normalized package-manager id from a package.json `packageManager` field.
+ *
+ * @param packageManagerField Raw field value such as `pnpm@8.3.1`.
+ * @returns A supported package manager id, or null when the field is missing or unsupported.
+ */
+export declare function parsePackageManagerField(packageManagerField: string | undefined): PackageManagerId | null;
+/**
+ * Infer the package manager used by a project from package.json and lockfile signals.
+ *
+ * `packageManager` fields take precedence over lockfiles, then lockfile and PnP
+ * markers are checked in Bun, pnpm, Yarn, npm order. npm remains the fallback so
+ * generated projects without explicit metadata keep the historical CLI default.
+ *
+ * @param projectDir Project root to inspect.
+ * @param packageManagerField Optional already-read package.json field.
+ * @returns The inferred package manager id.
+ */
+export declare function inferPackageManagerId(projectDir: string, packageManagerField?: string): PackageManagerId;
+export declare function getPackageManagerSelectOptions(): Array<{
+    label: string;
+    value: PackageManagerId;
+    hint: string;
+}>;
+export declare function formatRunScript(packageManagerId: PackageManagerId, scriptName: string, extraArgs?: string): string;
+export declare function formatInstallCommand(packageManagerId: PackageManagerId): string;
+/**
+ * Format a package-manager-specific devDependency install command.
+ *
+ * @param packageManagerId Package manager identifier.
+ * @param packages Package specifiers to add as devDependencies.
+ * @returns Command string suitable for shell execution.
+ */
+export declare function formatAddDevDependenciesCommand(packageManagerId: PackageManagerId, packages: string[]): string;
+/**
+ * Format a package-manager-specific one-off package execution command.
+ *
+ * @param packageManagerId Package manager identifier.
+ * @param packageName Executable package name.
+ * @param extraArgs Optional extra CLI arguments appended after the package name.
+ * @returns Command string suitable for shell execution.
+ */
+export declare function formatPackageExecCommand(packageManagerId: PackageManagerId, packageName: string, extraArgs?: string): string;
+export declare function transformPackageManagerText(content: string, packageManagerId: PackageManagerId): string;

package/dist/runtime/shared/package-managers.js

@@ -0,0 +1,236 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readJsonFileSync } from "./json-utils.js";
+const PACKAGE_MANAGER_DATA = [
+    {
+        id: "bun",
+        label: "Bun",
+        packageManagerField: "bun@1.3.11",
+        installCommand: "bun install",
+        frozenInstallCommand: "bun install --frozen-lockfile",
+    },
+    {
+        id: "npm",
+        label: "npm",
+        packageManagerField: "npm@11.6.1",
+        installCommand: "npm install --no-audit",
+        frozenInstallCommand: "npm ci",
+    },
+    {
+        id: "pnpm",
+        label: "pnpm",
+        packageManagerField: "pnpm@8.3.1",
+        installCommand: "pnpm install",
+        frozenInstallCommand: "pnpm install --frozen-lockfile",
+    },
+    {
+        id: "yarn",
+        label: "Yarn",
+        packageManagerField: "yarn@3.2.4",
+        installCommand: "yarn install",
+        frozenInstallCommand: "yarn install --frozen-lockfile",
+    },
+];
+const PACKAGE_MANAGER_LOCKFILE_SIGNALS = [
+    { id: "bun", filenames: ["bun.lock", "bun.lockb"] },
+    { id: "pnpm", filenames: ["pnpm-lock.yaml"] },
+    {
+        id: "yarn",
+        filenames: ["yarn.lock", ".pnp.cjs", ".pnp.loader.mjs", ".yarnrc.yml"],
+    },
+    { id: "npm", filenames: ["package-lock.json", "npm-shrinkwrap.json"] },
+];
+export const PACKAGE_MANAGER_IDS = PACKAGE_MANAGER_DATA.map((manager) => manager.id);
+export const PACKAGE_MANAGERS = Object.freeze(Object.fromEntries(PACKAGE_MANAGER_DATA.map((manager) => [manager.id, manager])));
+const DEV_INSTALL_FLAGS = {
+    bun: "add -d",
+    npm: "install --save-dev",
+    pnpm: "add -D",
+    yarn: "add -D",
+};
+const STOP_CHARS = new Set(["\n", "\r", "`", "\"", "'", ")", "]", "}", "!", ",", "."]);
+export function getPackageManager(id) {
+    const manager = PACKAGE_MANAGERS[id];
+    if (!manager) {
+        throw new Error(`Unknown package manager "${id}". Expected one of: ${PACKAGE_MANAGER_IDS.join(", ")}`);
+    }
+    return manager;
+}
+/**
+ * Parse a normalized package-manager id from a package.json `packageManager` field.
+ *
+ * @param packageManagerField Raw field value such as `pnpm@8.3.1`.
+ * @returns A supported package manager id, or null when the field is missing or unsupported.
+ */
+export function parsePackageManagerField(packageManagerField) {
+    const packageManagerId = packageManagerField?.split("@", 1)[0];
+    return PACKAGE_MANAGER_IDS.includes(packageManagerId)
+        ? packageManagerId
+        : null;
+}
+function readPackageManagerField(projectDir) {
+    try {
+        const packageJsonPath = path.join(projectDir, "package.json");
+        if (!fs.existsSync(packageJsonPath)) {
+            return undefined;
+        }
+        const manifest = readJsonFileSync(packageJsonPath, {
+            context: "package manager manifest",
+        });
+        return typeof manifest.packageManager === "string"
+            ? manifest.packageManager
+            : undefined;
+    }
+    catch {
+        // Package manager inference intentionally falls back to lockfile signals
+        // when package.json is absent or malformed.
+        return undefined;
+    }
+}
+/**
+ * Infer the package manager used by a project from package.json and lockfile signals.
+ *
+ * `packageManager` fields take precedence over lockfiles, then lockfile and PnP
+ * markers are checked in Bun, pnpm, Yarn, npm order. npm remains the fallback so
+ * generated projects without explicit metadata keep the historical CLI default.
+ *
+ * @param projectDir Project root to inspect.
+ * @param packageManagerField Optional already-read package.json field.
+ * @returns The inferred package manager id.
+ */
+export function inferPackageManagerId(projectDir, packageManagerField) {
+    const fieldPackageManager = parsePackageManagerField(packageManagerField) ??
+        parsePackageManagerField(readPackageManagerField(projectDir));
+    if (fieldPackageManager) {
+        return fieldPackageManager;
+    }
+    for (const signal of PACKAGE_MANAGER_LOCKFILE_SIGNALS) {
+        if (signal.filenames.some((filename) => fs.existsSync(path.join(projectDir, filename)))) {
+            return signal.id;
+        }
+    }
+    return "npm";
+}
+export function getPackageManagerSelectOptions() {
+    return PACKAGE_MANAGER_DATA.map((manager) => ({
+        label: manager.label,
+        value: manager.id,
+        hint: manager.installCommand,
+    }));
+}
+export function formatRunScript(packageManagerId, scriptName, extraArgs = "") {
+    const args = extraArgs.trim();
+    if (packageManagerId === "bun") {
+        return args ? `bun run ${scriptName} ${args}` : `bun run ${scriptName}`;
+    }
+    if (packageManagerId === "npm") {
+        return args ? `npm run ${scriptName} -- ${args}` : `npm run ${scriptName}`;
+    }
+    if (packageManagerId === "pnpm") {
+        return args ? `pnpm run ${scriptName} ${args}` : `pnpm run ${scriptName}`;
+    }
+    return args ? `yarn run ${scriptName} ${args}` : `yarn run ${scriptName}`;
+}
+export function formatInstallCommand(packageManagerId) {
+    return getPackageManager(packageManagerId).installCommand;
+}
+/**
+ * Format a package-manager-specific devDependency install command.
+ *
+ * @param packageManagerId Package manager identifier.
+ * @param packages Package specifiers to add as devDependencies.
+ * @returns Command string suitable for shell execution.
+ */
+export function formatAddDevDependenciesCommand(packageManagerId, packages) {
+    if (packages.length === 0) {
+        return formatInstallCommand(packageManagerId);
+    }
+    return `${packageManagerId} ${DEV_INSTALL_FLAGS[packageManagerId]} ${packages.join(" ")}`;
+}
+/**
+ * Format a package-manager-specific one-off package execution command.
+ *
+ * @param packageManagerId Package manager identifier.
+ * @param packageName Executable package name.
+ * @param extraArgs Optional extra CLI arguments appended after the package name.
+ * @returns Command string suitable for shell execution.
+ */
+export function formatPackageExecCommand(packageManagerId, packageName, extraArgs = "") {
+    const args = extraArgs.trim();
+    if (packageManagerId === "bun") {
+        return args ? `bunx ${packageName} ${args}` : `bunx ${packageName}`;
+    }
+    if (packageManagerId === "npm") {
+        return args ? `npx --yes ${packageName} ${args}` : `npx --yes ${packageName}`;
+    }
+    if (packageManagerId === "pnpm") {
+        return args ? `pnpm dlx ${packageName} ${args}` : `pnpm dlx ${packageName}`;
+    }
+    return args ? `yarn dlx ${packageName} ${args}` : `yarn dlx ${packageName}`;
+}
+function consumeCommandArguments(content, startIndex) {
+    let cursor = startIndex;
+    let args = "";
+    while (cursor < content.length) {
+        const current = content[cursor];
+        if (STOP_CHARS.has(current) ||
+            content.startsWith("&&", cursor) ||
+            content.startsWith("||", cursor) ||
+            current === ";") {
+            break;
+        }
+        args += current;
+        cursor += 1;
+    }
+    return {
+        args: args.trim(),
+        cursor,
+    };
+}
+function replaceBunRunCommands(content, packageManagerId) {
+    const marker = "bun run ";
+    let result = "";
+    let cursor = 0;
+    while (cursor < content.length) {
+        const index = content.indexOf(marker, cursor);
+        if (index === -1) {
+            result += content.slice(cursor);
+            break;
+        }
+        if (index > 0 && /[A-Za-z0-9_-]/.test(content[index - 1])) {
+            result += content.slice(cursor, index + marker.length);
+            cursor = index + marker.length;
+            continue;
+        }
+        result += content.slice(cursor, index);
+        const scriptNameStart = index + marker.length;
+        const scriptNameMatch = /^[A-Za-z0-9:_-]+/.exec(content.slice(scriptNameStart));
+        if (!scriptNameMatch) {
+            result += marker;
+            cursor = scriptNameStart;
+            continue;
+        }
+        const scriptName = scriptNameMatch[0];
+        const argsStart = scriptNameStart + scriptName.length;
+        const { args, cursor: nextCursor } = consumeCommandArguments(content, argsStart);
+        result += formatRunScript(packageManagerId, scriptName, args);
+        cursor = nextCursor;
+    }
+    return result;
+}
+function replaceDevDependencyInstalls(content, packageManagerId) {
+    return content.replace(/\bbun add -d ([^\s&|;`"'()]+)\b/g, (_, packageName) => {
+        if (packageManagerId === "bun") {
+            return `bun add -d ${packageName}`;
+        }
+        return `${packageManagerId} ${DEV_INSTALL_FLAGS[packageManagerId]} ${packageName}`;
+    });
+}
+export function transformPackageManagerText(content, packageManagerId) {
+    const manager = getPackageManager(packageManagerId);
+    return replaceDevDependencyInstalls(replaceBunRunCommands(content
+        .replace(/\bbun install --frozen-lockfile\b/g, manager.frozenInstallCommand)
+        .replace(/\bbun install\b/g, manager.installCommand), packageManagerId), packageManagerId)
+        .replace(/\s*&&\s*/g, " && ")
+        .replace(/\s*\|\|\s*/g, " || ");
+}

package/dist/runtime/shared/package-versions.d.ts

@@ -0,0 +1,63 @@
+export interface PackageVersions {
+    apiClientPackageVersion: string;
+    blockRuntimePackageVersion: string;
+    blockTypesPackageVersion: string;
+    projectToolsPackageVersion: string;
+    restPackageVersion: string;
+    tsxPackageVersion: string;
+    typiaPackageVersion: string;
+    typiaUnpluginPackageVersion: string;
+    typescriptPackageVersion: string;
+    wpTypiaPackageExactVersion: string;
+    wpTypiaPackageVersion: string;
+}
+/**
+ * Explicit fallback ranges for managed WordPress-facing workspace dependencies.
+ *
+ * These remain centralized here even when individual scaffold flows resolve a
+ * fresher local or installed manifest version first, so add-command defaults do
+ * not drift across runtime modules.
+ */
+export declare const DEFAULT_WORDPRESS_ABILITIES_VERSION = "^0.10.0";
+export declare const DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION = "^0.9.0";
+export declare const DEFAULT_WORDPRESS_CORE_DATA_VERSION = "~7.46.0";
+export declare const DEFAULT_WORDPRESS_DATA_VERSION = "~10.46.0";
+export declare const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = "~14.3.0";
+export declare const DEFAULT_WORDPRESS_ENV_VERSION = "^11.2.0";
+export declare const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = "^0.1.1";
+/**
+ * Resolve a managed package version range from linked workspace packages first,
+ * then installed package manifests, while preserving the shared normalization
+ * and manifest fingerprinting rules used by `getPackageVersions()`.
+ *
+ * @param packageName npm package whose manifest version should be consulted.
+ * @param fallback Canonical range to use when no usable manifest version exists.
+ * @param workspacePackageDirName Optional sibling monorepo package directory name.
+ * @returns A normalized semver range suitable for generated dependency entries.
+ */
+export declare function resolveManagedPackageVersionRange(options: {
+    fallback: string;
+    packageName: string;
+    workspacePackageDirName?: string;
+}): string;
+/**
+ * Clears the in-memory cache used by `getPackageVersions()`.
+ *
+ * Long-lived processes can call this after regenerating or updating package
+ * manifests when they want the next lookup to recompute version metadata
+ * synchronously from disk.
+ */
+export declare function clearPackageVersionsCache(): void;
+/**
+ * Backwards-compatible alias for integrations that adopted the original
+ * internal invalidation name before the public cache policy was documented.
+ */
+export declare function invalidatePackageVersionsCache(): void;
+/**
+ * Resolve package versions used in generated manifests and onboarding text.
+ *
+ * The lookup keeps a process-local cached result while recomputing manifest
+ * fingerprints on each call. When the relevant package metadata changes on
+ * disk, the cache key changes and the returned version object is refreshed.
+ */
+export declare function getPackageVersions(): PackageVersions;