@wp-typia/project-tools 0.24.4 → 0.24.5

package/dist/runtime/templates/template-source-cache.js

@@ -0,0 +1,481 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { getNodeErrorCode, pathExists } from '../shared/fs-async.js';
+import { CACHE_MARKER_FILE, CACHE_PRUNE_MARKER_FILE, externalTemplateCacheMetadataMatches, formatExternalTemplateCacheEntryMarker, formatExternalTemplateCachePruneMarker, isExternalTemplateCacheEntryFreshForTtl, parseExternalTemplateCacheEntryMarker, parseExternalTemplateCachePruneMarker, } from './template-source-cache-markers.js';
+import { getExternalTemplateCacheNowMs, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, resolveExternalTemplateCachePruneIntervalMs, resolveExternalTemplateCacheTtlMs, } from './template-source-cache-policy.js';
+export { EXTERNAL_TEMPLATE_CACHE_DIR_ENV, EXTERNAL_TEMPLATE_CACHE_ENV, EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV, EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, } from './template-source-cache-policy.js';
+/**
+ * Private directory mode used for cache roots and entries on POSIX platforms.
+ */
+const PRIVATE_CACHE_DIRECTORY_MODE = 0o700;
+/**
+ * Filesystem errors that mean another writer published the same cache entry.
+ */
+const CACHE_PUBLISH_RACE_ERROR_CODES = new Set(['EEXIST', 'ENOTEMPTY']);
+/**
+ * Filesystem errors that make the optional cache unavailable.
+ */
+const CACHE_UNAVAILABLE_ERROR_CODES = new Set([
+    'EACCES',
+    'ENOSPC',
+    'ENOTDIR',
+    'EPERM',
+    'EROFS',
+]);
+/**
+ * Cache namespaces must stay within one path segment under the cache root.
+ */
+const SAFE_CACHE_NAMESPACE_SEGMENT = /^[A-Za-z0-9_.-]+$/u;
+/**
+ * Cache entries are deterministic SHA-256 digest directory names.
+ */
+const SAFE_CACHE_ENTRY_SEGMENT = /^[a-f0-9]{64}$/u;
+function createTemporaryCacheEntryDirName(cacheKey) {
+    // Crypto randomness keeps concurrent cache populators from colliding on the
+    // staging directory before the final atomic rename publishes the cache entry.
+    return `.tmp-${cacheKey}-${process.pid}-${Date.now()}-${randomUUID()}`;
+}
+/**
+ * Creates a deterministic cache key from source identity and integrity parts.
+ *
+ * @param keyParts Ordered values that identify one cached template source.
+ * @returns SHA-256 hex digest of the JSON-serialized key parts.
+ */
+export function createExternalTemplateCacheKey(keyParts) {
+    return createHash('sha256')
+        .update(JSON.stringify(keyParts))
+        .digest('hex');
+}
+async function isDirectoryPath(directory) {
+    try {
+        const stats = await fsp.lstat(directory);
+        return stats.isDirectory() && !stats.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function removeTemporaryCacheEntry(entryDir) {
+    try {
+        await fsp.rm(entryDir, { force: true, recursive: true });
+    }
+    catch {
+        // Cache cleanup is best-effort; the caller can still continue uncached.
+    }
+}
+function getCurrentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+async function isPrivateCacheDirectory(directory) {
+    try {
+        const stats = await fsp.lstat(directory);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            return false;
+        }
+        const currentUid = getCurrentUid();
+        if (currentUid !== null && stats.uid !== currentUid) {
+            return false;
+        }
+        if (process.platform !== 'win32' && (stats.mode & 0o077) !== 0) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensurePrivateCacheDirectory(directory) {
+    try {
+        await fsp.mkdir(directory, {
+            mode: PRIVATE_CACHE_DIRECTORY_MODE,
+            recursive: true,
+        });
+        const stats = await fsp.lstat(directory);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            return false;
+        }
+        const currentUid = getCurrentUid();
+        if (currentUid !== null && stats.uid !== currentUid) {
+            return false;
+        }
+        if (process.platform !== 'win32') {
+            if ((stats.mode & 0o077) !== 0) {
+                await fsp.chmod(directory, PRIVATE_CACHE_DIRECTORY_MODE);
+            }
+        }
+        return isPrivateCacheDirectory(directory);
+    }
+    catch {
+        return false;
+    }
+}
+function resolveCacheNamespaceDir(cacheRoot, namespace) {
+    if (namespace === '.' ||
+        namespace === '..' ||
+        !SAFE_CACHE_NAMESPACE_SEGMENT.test(namespace)) {
+        return null;
+    }
+    const namespaceDir = path.join(cacheRoot, namespace);
+    const relativeNamespaceDir = path.relative(cacheRoot, namespaceDir);
+    if (relativeNamespaceDir.length === 0 ||
+        relativeNamespaceDir.startsWith('..') ||
+        path.isAbsolute(relativeNamespaceDir)) {
+        return null;
+    }
+    return namespaceDir;
+}
+function getCacheEntryPaths(descriptor) {
+    const cacheKey = createExternalTemplateCacheKey(descriptor.keyParts);
+    const cacheRoot = getExternalTemplateCacheRoot();
+    const namespaceDir = resolveCacheNamespaceDir(cacheRoot, descriptor.namespace);
+    if (!namespaceDir) {
+        return null;
+    }
+    const entryDir = path.join(namespaceDir, cacheKey);
+    return {
+        cacheKey,
+        cacheRoot,
+        entryDir,
+        markerPath: path.join(entryDir, CACHE_MARKER_FILE),
+        namespaceDir,
+        sourceDir: path.join(entryDir, 'source'),
+    };
+}
+async function isReusableCacheEntry(entryDir, markerPath, sourceDir) {
+    return ((await isPrivateCacheDirectory(entryDir)) &&
+        (await pathExists(markerPath)) &&
+        (await isDirectoryPath(sourceDir)));
+}
+async function readCacheEntryMarker(markerPath) {
+    try {
+        return parseExternalTemplateCacheEntryMarker(await fsp.readFile(markerPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function getReusableCacheEntryMarker(entryDir, markerPath, sourceDir) {
+    if (!(await isReusableCacheEntry(entryDir, markerPath, sourceDir))) {
+        return null;
+    }
+    return readCacheEntryMarker(markerPath);
+}
+async function isReusableFreshCacheEntry(entryDir, markerPath, sourceDir, nowMs, ttlMs) {
+    const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+    return (marker !== null &&
+        isExternalTemplateCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs));
+}
+function isPathInsideDirectory(directory, candidatePath) {
+    const relativePath = path.relative(directory, candidatePath);
+    return (relativePath.length > 0 &&
+        !relativePath.startsWith('..') &&
+        !path.isAbsolute(relativePath));
+}
+async function removeCacheEntryWithinRoot(cacheRoot, entryDir) {
+    if (!isPathInsideDirectory(cacheRoot, entryDir)) {
+        return false;
+    }
+    try {
+        await fsp.rm(entryDir, { force: true, recursive: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getCachePruneMarkerPath(cacheRoot) {
+    return path.join(cacheRoot, CACHE_PRUNE_MARKER_FILE);
+}
+async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, pruneIntervalMs, ttlMs, }) {
+    if (force || pruneIntervalMs === null) {
+        return false;
+    }
+    let markerText;
+    try {
+        markerText = await fsp.readFile(getCachePruneMarkerPath(cacheRoot), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const marker = parseExternalTemplateCachePruneMarker(markerText);
+    if (!marker ||
+        marker.ttlMs !== ttlMs ||
+        marker.pruneIntervalMs !== pruneIntervalMs) {
+        return false;
+    }
+    const elapsedMs = nowMs - marker.prunedAtMs;
+    return elapsedMs >= 0 && elapsedMs < pruneIntervalMs;
+}
+async function writeExternalTemplateCachePruneMarker({ cacheRoot, nowMs, pruneIntervalMs, ttlMs, }) {
+    try {
+        await fsp.writeFile(getCachePruneMarkerPath(cacheRoot), formatExternalTemplateCachePruneMarker({
+            nowMs,
+            pruneIntervalMs,
+            ttlMs,
+        }), 'utf8');
+    }
+    catch {
+        // Prune markers are an optimization; failing to write one keeps TTL safe.
+    }
+}
+/**
+ * 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 async function pruneExternalTemplateCache(options = {}) {
+    const env = options.env ?? process.env;
+    const cacheRoot = getExternalTemplateCacheRoot(env);
+    const ttlMs = resolveExternalTemplateCacheTtlMs({
+        env,
+        ttlDays: options.ttlDays,
+    });
+    const pruneIntervalMs = resolveExternalTemplateCachePruneIntervalMs({
+        env,
+        pruneIntervalMs: options.pruneIntervalMs,
+    });
+    const result = {
+        cacheRoot,
+        prunedEntries: 0,
+        scannedEntries: 0,
+        skippedEntries: 0,
+        skippedByThrottle: false,
+        ttlMs,
+    };
+    if (ttlMs === null || !(await isPrivateCacheDirectory(cacheRoot))) {
+        return result;
+    }
+    const nowMs = getExternalTemplateCacheNowMs(options.now);
+    if (await shouldSkipExternalTemplateCachePrune({
+        cacheRoot,
+        force: options.force,
+        nowMs,
+        pruneIntervalMs,
+        ttlMs,
+    })) {
+        result.skippedByThrottle = true;
+        return result;
+    }
+    let namespaceEntries;
+    try {
+        namespaceEntries = await fsp.readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    const expiresBeforeMs = nowMs - ttlMs;
+    for (const namespaceEntry of namespaceEntries) {
+        if (!namespaceEntry.isDirectory()) {
+            continue;
+        }
+        const namespaceDir = resolveCacheNamespaceDir(cacheRoot, namespaceEntry.name);
+        if (!namespaceDir || !(await isPrivateCacheDirectory(namespaceDir))) {
+            result.skippedEntries += 1;
+            continue;
+        }
+        let cacheEntries;
+        try {
+            cacheEntries = await fsp.readdir(namespaceDir, { withFileTypes: true });
+        }
+        catch {
+            result.skippedEntries += 1;
+            continue;
+        }
+        for (const cacheEntry of cacheEntries) {
+            if (!cacheEntry.isDirectory()) {
+                continue;
+            }
+            if (!SAFE_CACHE_ENTRY_SEGMENT.test(cacheEntry.name)) {
+                result.skippedEntries += 1;
+                continue;
+            }
+            const entryDir = path.join(namespaceDir, cacheEntry.name);
+            result.scannedEntries += 1;
+            if (!isPathInsideDirectory(cacheRoot, entryDir)) {
+                result.skippedEntries += 1;
+                continue;
+            }
+            const markerPath = path.join(entryDir, CACHE_MARKER_FILE);
+            const sourceDir = path.join(entryDir, 'source');
+            const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+            if (!marker) {
+                result.skippedEntries += 1;
+                continue;
+            }
+            if (marker.createdAtMs < expiresBeforeMs) {
+                if (await removeCacheEntryWithinRoot(cacheRoot, entryDir)) {
+                    result.prunedEntries += 1;
+                }
+                else {
+                    result.skippedEntries += 1;
+                }
+            }
+        }
+    }
+    await writeExternalTemplateCachePruneMarker({
+        cacheRoot,
+        nowMs,
+        pruneIntervalMs,
+        ttlMs,
+    });
+    return result;
+}
+/**
+ * Finds a reusable cache entry whose marker metadata includes the expected fields.
+ *
+ * This lookup is intended for resilient fallbacks where a caller cannot compute
+ * the exact deterministic key but can safely reuse a previously validated local
+ * cache entry for the same source identity.
+ *
+ * @param descriptor Cache namespace and marker metadata fields to match.
+ * @returns Existing cache resolution details, or `null` when no safe entry exists.
+ */
+export async function findReusableExternalTemplateSourceCache(descriptor) {
+    if (!isExternalTemplateCacheEnabled()) {
+        return null;
+    }
+    const cacheRoot = getExternalTemplateCacheRoot();
+    const namespaceDir = resolveCacheNamespaceDir(cacheRoot, descriptor.namespace);
+    if (!namespaceDir) {
+        return null;
+    }
+    if (!(await isPrivateCacheDirectory(cacheRoot)) ||
+        !(await isPrivateCacheDirectory(namespaceDir))) {
+        return null;
+    }
+    const ttlMs = resolveExternalTemplateCacheTtlMs();
+    const nowMs = getExternalTemplateCacheNowMs(undefined);
+    await pruneExternalTemplateCache();
+    let entries;
+    try {
+        entries = await fsp.readdir(namespaceDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    let bestEntry = null;
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const entryDir = path.join(namespaceDir, entry.name);
+        const markerPath = path.join(entryDir, CACHE_MARKER_FILE);
+        const sourceDir = path.join(entryDir, 'source');
+        const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+        if (!marker ||
+            !isExternalTemplateCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs) ||
+            !externalTemplateCacheMetadataMatches(marker.metadata, descriptor.metadata)) {
+            continue;
+        }
+        if (!bestEntry || marker.createdAtMs > bestEntry.createdAtMs) {
+            bestEntry = {
+                createdAtMs: marker.createdAtMs,
+                sourceDir,
+            };
+        }
+    }
+    return bestEntry
+        ? {
+            cacheHit: true,
+            sourceDir: bestEntry.sourceDir,
+        }
+        : null;
+}
+/**
+ * Resolves or populates a cached external template source directory.
+ *
+ * Returns `null` when caching is disabled. Cache misses populate a temporary
+ * directory first and then atomically move it into place; concurrent writers
+ * that lose the race reuse the completed marker/source pair.
+ *
+ * @param descriptor Namespace, key parts, and metadata for the cache entry.
+ * @param populateSourceDir Callback that writes the guarded source on a miss.
+ * @returns Cache resolution details, or `null` when caching is disabled.
+ */
+export async function resolveExternalTemplateSourceCache(descriptor, populateSourceDir) {
+    if (!isExternalTemplateCacheEnabled()) {
+        return null;
+    }
+    const cacheEntryPaths = getCacheEntryPaths(descriptor);
+    if (!cacheEntryPaths) {
+        return null;
+    }
+    const { cacheKey, cacheRoot, entryDir, markerPath, namespaceDir, sourceDir } = cacheEntryPaths;
+    if (!(await ensurePrivateCacheDirectory(cacheRoot)) ||
+        !(await ensurePrivateCacheDirectory(namespaceDir))) {
+        return null;
+    }
+    const ttlMs = resolveExternalTemplateCacheTtlMs();
+    const nowMs = getExternalTemplateCacheNowMs(undefined);
+    await pruneExternalTemplateCache();
+    const existingMarker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+    if (existingMarker &&
+        isExternalTemplateCacheEntryFreshForTtl(existingMarker.createdAtMs, nowMs, ttlMs)) {
+        return {
+            cacheHit: true,
+            sourceDir,
+        };
+    }
+    if (existingMarker) {
+        await removeCacheEntryWithinRoot(cacheRoot, entryDir);
+    }
+    const temporaryEntryDir = path.join(namespaceDir, createTemporaryCacheEntryDirName(cacheKey));
+    const temporarySourceDir = path.join(temporaryEntryDir, 'source');
+    let populateFailed = false;
+    try {
+        await fsp.mkdir(temporarySourceDir, {
+            mode: PRIVATE_CACHE_DIRECTORY_MODE,
+            recursive: true,
+        });
+        if (process.platform !== 'win32') {
+            await fsp.chmod(temporaryEntryDir, PRIVATE_CACHE_DIRECTORY_MODE);
+        }
+        try {
+            await populateSourceDir(temporarySourceDir);
+        }
+        catch (error) {
+            populateFailed = true;
+            throw error;
+        }
+        await fsp.writeFile(path.join(temporaryEntryDir, CACHE_MARKER_FILE), formatExternalTemplateCacheEntryMarker({
+            cacheKey,
+            createdAt: new Date(),
+            metadata: descriptor.metadata,
+            namespace: descriptor.namespace,
+        }), 'utf8');
+        await fsp.rename(temporaryEntryDir, entryDir);
+        return {
+            cacheHit: false,
+            sourceDir,
+        };
+    }
+    catch (error) {
+        await removeTemporaryCacheEntry(temporaryEntryDir);
+        if (populateFailed) {
+            if (CACHE_UNAVAILABLE_ERROR_CODES.has(getNodeErrorCode(error))) {
+                return null;
+            }
+            throw error;
+        }
+        const errorCode = getNodeErrorCode(error);
+        if (CACHE_PUBLISH_RACE_ERROR_CODES.has(errorCode) &&
+            (await isReusableFreshCacheEntry(entryDir, markerPath, sourceDir, nowMs, ttlMs))) {
+            return {
+                cacheHit: true,
+                sourceDir,
+            };
+        }
+        if (CACHE_PUBLISH_RACE_ERROR_CODES.has(errorCode) ||
+            CACHE_UNAVAILABLE_ERROR_CODES.has(errorCode)) {
+            return null;
+        }
+        throw error;
+    }
+}

package/dist/runtime/templates/template-source-contracts.d.ts

@@ -0,0 +1,94 @@
+import type { UnknownRecord } from '../shared/object-utils.js';
+export type TemplateSourceFormat = 'wp-typia' | 'create-block-external' | 'create-block-subset';
+/**
+ * Public template variables exposed to external template seeds before wp-typia
+ * normalizes them into a scaffold project.
+ */
+export interface TemplateVariableContext extends UnknownRecord {
+    /** Version string for `@wp-typia/api-client` used in generated dependencies. */
+    apiClientPackageVersion: string;
+    /** Version string for `@wp-typia/block-runtime` used in generated dependencies. */
+    blockRuntimePackageVersion: string;
+    /** Version string for `@wp-typia/block-types` used in generated dependencies. */
+    blockTypesPackageVersion: string;
+    /** Version string for `wp-typia` used when templates include the CLI binary locally. */
+    wpTypiaPackageVersion: string;
+    /** PascalCase block type name derived from the scaffold slug. */
+    pascalCase: string;
+    /** Snake_case PHP symbol prefix used for generated functions, constants, and keys. */
+    phpPrefix: string;
+    /** Human-readable block title. */
+    title: string;
+    /** Human-readable project or block description. */
+    description: string;
+    /** Keyword string derived from the slug for generated block metadata. */
+    keyword: string;
+    /** Block namespace used in generated block names such as `namespace/slug`. */
+    namespace: string;
+    /** Kebab-case scaffold slug used for package names, paths, and block slugs. */
+    slug: string;
+    /** Kebab-case text domain used for generated i18n strings and plugin headers. */
+    textDomain: string;
+}
+export interface ResolvedTemplateSource {
+    id: string;
+    defaultCategory: string;
+    description: string;
+    features: string[];
+    format: TemplateSourceFormat;
+    isOfficialWorkspaceTemplate?: boolean;
+    /**
+     * True when the resolved template can participate in scaffold migration UI
+     * seeding, such as rendered wp-typia workspace templates.
+     */
+    supportsMigrationUi?: boolean;
+    templateDir: string;
+    cleanup?: () => Promise<void>;
+    selectedVariant?: string | null;
+    warnings?: string[];
+}
+export interface GitHubTemplateLocator {
+    owner: string;
+    repo: string;
+    ref: string | null;
+    sourcePath: string;
+}
+export interface NpmTemplateLocator {
+    fetchSpec: string;
+    name: string;
+    raw: string;
+    rawSpec: string;
+    type: string;
+}
+export interface ExternalTemplateConfig<TView extends UnknownRecord = TemplateVariableContext> {
+    assetsPath?: string;
+    blockTemplatesPath?: string;
+    defaultValues?: Partial<TView>;
+    folderName?: string;
+    /**
+     * Relative template root that renders a fuller wp-typia plugin/workspace
+     * scaffold instead of a create-block subset.
+     */
+    pluginTemplatesPath?: string;
+    transformer?: (view: TView) => UnknownRecord | Promise<UnknownRecord>;
+    variants?: Record<string, Partial<TView>>;
+}
+export interface SeedSource {
+    assetsDir?: string;
+    blockDir: string;
+    cleanup?: () => Promise<void>;
+    formatHint?: 'create-block-subset' | 'wp-typia';
+    rootDir: string;
+    selectedVariant?: string | null;
+    warnings?: string[];
+}
+export type RemoteTemplateLocator = {
+    kind: 'github';
+    locator: GitHubTemplateLocator;
+} | {
+    kind: 'npm';
+    locator: NpmTemplateLocator;
+} | {
+    kind: 'path';
+    templatePath: string;
+};

package/dist/runtime/templates/template-source-contracts.js

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

package/dist/runtime/templates/template-source-external.d.ts

@@ -0,0 +1,34 @@
+import type { SeedSource, TemplateVariableContext } from './template-source-contracts.js';
+/**
+ * Candidate filenames for official external template config entrypoints.
+ */
+export declare const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES: readonly ["index.js", "index.cjs", "index.mjs"];
+export declare const EXTERNAL_TEMPLATE_TRUST_WARNING = "External template configs execute trusted JavaScript during scaffolding. Review the template source before using local paths, GitHub repos, or npm packages you do not already trust.";
+/**
+ * Search a source directory for the first supported external template entry.
+ *
+ * @deprecated Since 0.22.10. Use `findExternalTemplateEntry()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export declare function getExternalTemplateEntry(sourceDir: string): string | null;
+/**
+ * Search a source directory for a supported external template entry asynchronously.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export declare function findExternalTemplateEntry(sourceDir: string): Promise<string | null>;
+/**
+ * Load an official external template config and render its seed.
+ *
+ * @param sourceDir Source directory that contains the external template config.
+ * @param context Template render context used for the selected variant.
+ * @param requestedVariant Optional explicit variant override.
+ * @returns A rendered temporary seed directory with optional assets and cleanup.
+ */
+export declare function renderCreateBlockExternalTemplate(sourceDir: string, context: TemplateVariableContext, requestedVariant?: string): Promise<SeedSource>;