@wp-typia/project-tools 0.22.3 → 0.22.5

package/dist/runtime/cli-add-workspace-mutation.js

@@ -0,0 +1,60 @@
+import { rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+const DEFAULT_PHP_SNIPPET_INSERTION_ANCHORS = [
+    /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
+    /\?>\s*$/u,
+];
+/**
+ * Error thrown when the mutation and its rollback both fail.
+ */
+export class WorkspaceMutationRollbackError extends Error {
+    constructor(mutationError, rollbackError) {
+        super("Workspace mutation failed and rollback also failed.");
+        this.name = "WorkspaceMutationRollbackError";
+        this.mutationError = mutationError;
+        this.rollbackError = rollbackError;
+    }
+}
+/**
+ * Execute a workspace add mutation with rollback on any failure.
+ */
+export async function executeWorkspaceMutationPlan({ filePaths, run, snapshotDirs = [], targetPaths = [], }) {
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles(filePaths),
+        snapshotDirs: [...snapshotDirs],
+        targetPaths: [...targetPaths],
+    };
+    try {
+        return await run();
+    }
+    catch (error) {
+        try {
+            await rollbackWorkspaceMutation(mutationSnapshot);
+        }
+        catch (rollbackError) {
+            throw new WorkspaceMutationRollbackError(error, rollbackError);
+        }
+        throw error;
+    }
+}
+/**
+ * Insert a PHP snippet before the workspace textdomain hook or closing tag.
+ */
+export function insertPhpSnippetBeforeWorkspaceAnchors(source, snippet) {
+    for (const anchor of DEFAULT_PHP_SNIPPET_INSERTION_ANCHORS) {
+        const candidate = source.replace(anchor, (match) => `${snippet}\n${match}`);
+        if (candidate !== source) {
+            return candidate;
+        }
+    }
+    return `${source.trimEnd()}\n${snippet}\n`;
+}
+/**
+ * Append a PHP snippet before the closing tag when one is present.
+ */
+export function appendPhpSnippetBeforeClosingTag(source, snippet) {
+    const closingTagPattern = /\?>\s*$/u;
+    if (closingTagPattern.test(source)) {
+        return source.replace(closingTagPattern, `${snippet}\n?>`);
+    }
+    return `${source.trimEnd()}\n${snippet}\n`;
+}

package/dist/runtime/cli-add-workspace-rest-anchors.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { getWorkspaceBootstrapPath, patchFile, } from "./cli-add-shared.js";
+import { appendPhpSnippetBeforeClosingTag, insertPhpSnippetBeforeWorkspaceAnchors, } from "./cli-add-workspace-mutation.js";
 import { hasPhpFunctionDefinition } from "./php-utils.js";
 const REST_RESOURCE_SERVER_GLOB = "/inc/rest/*.php";
 export async function ensureRestResourceBootstrapAnchors(workspace) {
@@ -16,30 +17,8 @@ function ${registerFunctionName}() {
 \t}
 }
 `;
-        const insertionAnchors = [
-            /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
-            /\?>\s*$/u,
-        ];
-        const insertPhpSnippet = (snippet) => {
-            for (const anchor of insertionAnchors) {
-                const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
-                if (candidate !== nextSource) {
-                    nextSource = candidate;
-                    return;
-                }
-            }
-            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
-        };
-        const appendPhpSnippet = (snippet) => {
-            const closingTagPattern = /\?>\s*$/u;
-            if (closingTagPattern.test(nextSource)) {
-                nextSource = nextSource.replace(closingTagPattern, `${snippet}\n?>`);
-                return;
-            }
-            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
-        };
         if (!hasPhpFunctionDefinition(nextSource, registerFunctionName)) {
-            insertPhpSnippet(registerFunction);
+            nextSource = insertPhpSnippetBeforeWorkspaceAnchors(nextSource, registerFunction);
         }
         else if (!nextSource.includes(REST_RESOURCE_SERVER_GLOB)) {
             throw new Error([
@@ -49,7 +28,7 @@ function ${registerFunctionName}() {
             ].join(" "));
         }
         if (!nextSource.includes(registerHook)) {
-            appendPhpSnippet(registerHook);
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, registerHook);
         }
         return nextSource;
     });

package/dist/runtime/cli-add-workspace.js

@@ -5,6 +5,7 @@ import { resolveWorkspaceProject } from "./workspace-project.js";
 import { appendWorkspaceInventoryEntries, readWorkspaceInventory } from "./workspace-inventory.js";
 import { toKebabCase, toSnakeCase, toTitleCase } from "./string-case.js";
 import { assertBlockStyleDoesNotExist, assertBlockTransformDoesNotExist, assertValidGeneratedSlug, assertValidHookAnchor, assertValidHookedBlockPosition, assertVariationDoesNotExist, getMutableBlockHooks, normalizeBlockSlug, patchFile, quoteTsString, readWorkspaceBlockJson, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { findExecutablePatternMatch, hasExecutablePattern, hasUncommentedPattern, maskTypeScriptCommentsAndLiterals, } from "./ts-source-masking.js";
 const VARIATIONS_IMPORT_LINE = "import { registerWorkspaceVariations } from './variations';";
 const VARIATIONS_IMPORT_PATTERN = /^\s*import\s*\{\s*registerWorkspaceVariations\s*\}\s*from\s*["']\.\/variations["']\s*;?\s*$/mu;
 const VARIATIONS_CALL_LINE = "registerWorkspaceVariations();";
@@ -19,85 +20,6 @@ const BLOCK_TRANSFORMS_CALL_LINE = "applyWorkspaceBlockTransforms(registration.s
 const BLOCK_TRANSFORMS_CALL_PATTERN = /applyWorkspaceBlockTransforms\s*\(\s*registration\s*\.\s*settings\s*\)\s*;?/u;
 const SCAFFOLD_REGISTRATION_SETTINGS_CALL_PATTERN = /registerScaffoldBlockType\s*\(\s*registration\s*\.\s*name\s*,\s*registration\s*\.\s*settings\s*\)\s*;?/u;
 const FULL_BLOCK_NAME_PATTERN = /^[a-z0-9-]+\/[a-z0-9-]+$/u;
-function maskSourceSegment(segment) {
-    return segment.replace(/[^\n\r]/gu, " ");
-}
-function maskTypeScriptComments(source) {
-    return source
-        .replace(/\/\*[\s\S]*?\*\//gu, maskSourceSegment)
-        .replace(/\/\/[^\n\r]*/gu, maskSourceSegment);
-}
-// Preserve source offsets so executable-code match indexes still map to the original file.
-function maskTypeScriptCommentsAndLiterals(source) {
-    let maskedSource = "";
-    let index = 0;
-    while (index < source.length) {
-        const current = source[index];
-        const next = source[index + 1];
-        if (current === "/" && next === "/") {
-            const start = index;
-            index += 2;
-            while (index < source.length &&
-                source[index] !== "\n" &&
-                source[index] !== "\r") {
-                index += 1;
-            }
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        if (current === "/" && next === "*") {
-            const start = index;
-            index += 2;
-            while (index < source.length &&
-                !(source[index] === "*" && source[index + 1] === "/")) {
-                index += 1;
-            }
-            index = Math.min(index + 2, source.length);
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        if (current === "'" || current === '"' || current === "`") {
-            const start = index;
-            const quote = current;
-            index += 1;
-            while (index < source.length) {
-                const char = source[index];
-                if (char === "\\") {
-                    index += 2;
-                    continue;
-                }
-                index += 1;
-                if (char === quote) {
-                    break;
-                }
-            }
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        maskedSource += current;
-        index += 1;
-    }
-    return maskedSource;
-}
-function hasExecutablePattern(source, pattern) {
-    return pattern.test(maskTypeScriptCommentsAndLiterals(source));
-}
-function hasUncommentedPattern(source, pattern) {
-    return pattern.test(maskTypeScriptComments(source));
-}
-function findExecutablePatternMatch(source, patterns) {
-    const maskedSource = maskTypeScriptCommentsAndLiterals(source);
-    for (const pattern of patterns) {
-        const match = pattern.exec(maskedSource);
-        if (match && match.index !== undefined) {
-            return {
-                end: match.index + match[0].length,
-                start: match.index,
-            };
-        }
-    }
-    return undefined;
-}
 function isIdentifierBoundary(source, index) {
     if (index < 0 || index >= source.length) {
         return true;

package/dist/runtime/cli-add.d.ts

@@ -3,11 +3,11 @@
  *
  * The canonical CLI surface stays stable here while the implementation lives
  * in focused internal modules:
- * - `cli-add-shared` for shared validation/help/rollback helpers
+ * - `cli-add-shared` as a compatibility barrel around focused add helpers
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, } from "./cli-add-shared.js";
 export type { AddBlockTemplateId, AddKindId, EditorPluginSlotId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";

package/dist/runtime/cli-add.js

@@ -3,11 +3,11 @@
  *
  * The canonical CLI surface stays stable here while the implementation lives
  * in focused internal modules:
- * - `cli-add-shared` for shared validation/help/rollback helpers
+ * - `cli-add-shared` as a compatibility barrel around focused add helpers
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
 export { getWorkspaceBlockSelectOptions } from "./workspace-inventory.js";

package/dist/runtime/cli-doctor-workspace-blocks.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { checkExistingFiles, createDoctorCheck, WORKSPACE_FULL_BLOCK_NAME_PATTERN, WORKSPACE_GENERATED_BLOCK_ARTIFACTS, } from "./cli-doctor-workspace-shared.js";
 import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
+import { hasExecutablePattern, hasUncommentedPattern, maskTypeScriptCommentsAndLiterals, } from "./ts-source-masking.js";
 const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
 const WORKSPACE_COLLECTION_IMPORT_PATTERN = /^\s*import\s+["']\.\.\/\.\.\/collection["']\s*;?\s*$/m;
 const WORKSPACE_VARIATIONS_IMPORT_PATTERN = /^\s*import\s*\{\s*registerWorkspaceVariations\s*\}\s*from\s*["']\.\/variations["']\s*;?\s*$/mu;
@@ -40,72 +41,6 @@ const WORKSPACE_BLOCK_LOCAL_STYLE_FILES = [
 ];
 const WORKSPACE_BLOCK_IFRAME_GLOBAL_DOM_PATTERN = /\b(?:document|window)\b|\b(?:parent|top)\b(?!\s*:)/gu;
 const WORKSPACE_BLOCK_PROPS_PATTERN = /\buse(?:Block|InnerBlocks)Props(?:\.save)?\s*\(/u;
-function maskSourceSegment(segment) {
-    return segment.replace(/[^\n\r]/gu, " ");
-}
-function maskTypeScriptComments(source) {
-    return source
-        .replace(/\/\*[\s\S]*?\*\//gu, maskSourceSegment)
-        .replace(/\/\/[^\n\r]*/gu, maskSourceSegment);
-}
-// Preserve offsets while hiding non-executable text from hook checks.
-function maskTypeScriptCommentsAndLiterals(source) {
-    let maskedSource = "";
-    let index = 0;
-    while (index < source.length) {
-        const current = source[index];
-        const next = source[index + 1];
-        if (current === "/" && next === "/") {
-            const start = index;
-            index += 2;
-            while (index < source.length &&
-                source[index] !== "\n" &&
-                source[index] !== "\r") {
-                index += 1;
-            }
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        if (current === "/" && next === "*") {
-            const start = index;
-            index += 2;
-            while (index < source.length &&
-                !(source[index] === "*" && source[index + 1] === "/")) {
-                index += 1;
-            }
-            index = Math.min(index + 2, source.length);
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        if (current === "'" || current === '"' || current === "`") {
-            const start = index;
-            const quote = current;
-            index += 1;
-            while (index < source.length) {
-                const char = source[index];
-                if (char === "\\") {
-                    index += 2;
-                    continue;
-                }
-                index += 1;
-                if (char === quote) {
-                    break;
-                }
-            }
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        maskedSource += current;
-        index += 1;
-    }
-    return maskedSource;
-}
-function hasUncommentedPattern(source, pattern) {
-    return pattern.test(maskTypeScriptComments(source));
-}
-function hasExecutablePattern(source, pattern) {
-    return pattern.test(maskTypeScriptCommentsAndLiterals(source));
-}
 function normalizePathSeparators(relativePath) {
     return relativePath.split(path.sep).join("/");
 }

package/dist/runtime/index.d.ts

@@ -32,6 +32,8 @@ export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, format
 export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export type { PackageVersions } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
+export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
+export type { ExternalTemplateCachePruneOptions, ExternalTemplateCachePruneResult, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
 export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
 export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, DoctorCheck, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, } from "./cli-core.js";

package/dist/runtime/index.js

@@ -25,5 +25,6 @@ export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, str
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
 export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
+export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
 export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";

package/dist/runtime/migration-utils.d.ts

@@ -1,3 +1,4 @@
+import { type PackageManagerId } from './package-managers.js';
 import type { JsonValue, ManifestAttribute, JsonObject } from './migration-types.js';
 import { type UnknownRecord } from './object-utils.js';
 export { cloneJsonValue } from './json-utils.js';
@@ -12,7 +13,7 @@ export declare function copyFile(sourcePath: string, targetPath: string): void;
 export declare function sanitizeSaveSnapshotSource(source: string): string;
 export declare function sanitizeSnapshotBlockJson(blockJson: JsonObject): JsonObject;
 export declare function runProjectScriptIfPresent(projectDir: string, scriptName: string): void;
-export declare function detectPackageManagerId(projectDir: string): 'bun' | 'npm' | 'pnpm' | 'yarn';
+export declare function detectPackageManagerId(projectDir: string): PackageManagerId;
 export declare function getLocalTsxBinary(projectDir: string): string;
 /**
  * Returns whether isInteractiveTerminal() is running with both stdin and stdout

package/dist/runtime/migration-utils.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { formatRunScript } from './package-managers.js';
+import { formatRunScript, inferPackageManagerId, parsePackageManagerField, } from './package-managers.js';
 import { isPlainObject } from './object-utils.js';
 export { cloneJsonValue } from './json-utils.js';
 const MIGRATION_VERSION_LABEL_PATTERN = /^v([1-9]\d*)$/;
@@ -141,16 +141,8 @@ export function runProjectScriptIfPresent(projectDir, scriptName) {
 }
 export function detectPackageManagerId(projectDir) {
     const packageJson = readJson(path.join(projectDir, 'package.json'));
-    const field = String(packageJson.packageManager ?? '');
-    if (field.startsWith('bun@'))
-        return 'bun';
-    if (field.startsWith('npm@'))
-        return 'npm';
-    if (field.startsWith('pnpm@'))
-        return 'pnpm';
-    if (field.startsWith('yarn@'))
-        return 'yarn';
-    return 'bun';
+    return (parsePackageManagerField(packageJson.packageManager) ??
+        inferPackageManagerId(projectDir));
 }
 export function getLocalTsxBinary(projectDir) {
     const filename = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';

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

@@ -9,6 +9,25 @@ export interface PackageManagerDefinition {
 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;

package/dist/runtime/package-managers.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 const PACKAGE_MANAGER_DATA = [
     {
         id: "bun",
@@ -28,6 +30,15 @@ const PACKAGE_MANAGER_DATA = [
         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 = {
@@ -44,6 +55,57 @@ export function getPackageManager(id) {
     }
     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 = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return typeof manifest.packageManager === "string"
+            ? manifest.packageManager
+            : undefined;
+    }
+    catch {
+        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,

package/dist/runtime/template-source-cache.d.ts

@@ -8,6 +8,12 @@ export declare const EXTERNAL_TEMPLATE_CACHE_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_C
  * Environment variable that overrides the external template cache root.
  */
 export declare const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR";
+/**
+ * Environment variable that enables TTL-based external template cache pruning.
+ *
+ * Unset, empty, zero, negative, and non-numeric values keep pruning disabled.
+ */
+export declare const EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_TTL_DAYS";
 /**
  * Serializable metadata recorded in the cache marker for diagnostics.
  */
@@ -58,6 +64,48 @@ export interface ExternalTemplateCacheLookupDescriptor {
      */
     namespace: string;
 }
+/**
+ * Options for best-effort external template cache pruning.
+ */
+export interface ExternalTemplateCachePruneOptions {
+    /**
+     * Environment object to inspect, defaulting to `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Clock override for deterministic tests.
+     */
+    now?: Date | number;
+    /**
+     * TTL override in days. When omitted, the TTL environment variable is used.
+     */
+    ttlDays?: number;
+}
+/**
+ * Summary returned after external template cache pruning.
+ */
+export interface ExternalTemplateCachePruneResult {
+    /**
+     * Absolute cache root inspected by the pruning helper.
+     */
+    cacheRoot: string;
+    /**
+     * Entries removed because their marker timestamp exceeded the TTL.
+     */
+    prunedEntries: number;
+    /**
+     * Candidate cache entry directories inspected.
+     */
+    scannedEntries: number;
+    /**
+     * Candidate directories skipped because they were malformed or unsafe.
+     */
+    skippedEntries: number;
+    /**
+     * Resolved TTL in milliseconds, or `null` when pruning was disabled.
+     */
+    ttlMs: number | null;
+}
 /**
  * Checks whether remote external template source caching is enabled.
  *
@@ -86,6 +134,17 @@ export declare function getExternalTemplateCacheRoot(env?: NodeJS.ProcessEnv): s
  * @returns SHA-256 hex digest of the JSON-serialized key parts.
  */
 export declare function createExternalTemplateCacheKey(keyParts: readonly string[]): string;
+/**
+ * Removes stale external template cache entries when a positive TTL is configured.
+ *
+ * The helper is best-effort: malformed cache directories are skipped, cache
+ * roots must remain private and non-symlinked, and deletes are constrained to
+ * deterministic entry directories under the configured cache root.
+ *
+ * @param options Optional TTL, clock, and environment overrides.
+ * @returns Pruning summary with counts for inspected, skipped, and removed entries.
+ */
+export declare function pruneExternalTemplateCache(options?: ExternalTemplateCachePruneOptions): Promise<ExternalTemplateCachePruneResult>;
 /**
  * Finds a reusable cache entry whose marker metadata includes the expected fields.
  *