@wp-typia/project-tools 0.16.11 → 0.16.12

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

@@ -0,0 +1,12 @@
+import type { RemoteTemplateLocator, SeedSource } from './template-source-contracts.js';
+export declare function isOfficialWorkspaceTemplateSeed(seed: SeedSource): boolean;
+export declare function assertNoSymlinks(sourceDir: string): Promise<void>;
+/**
+ * Resolves a template locator into a local seed source directory.
+ *
+ * @param locator Remote template locator describing a local path, GitHub source, or npm package.
+ * @param cwd Current working directory used to resolve local template paths.
+ * @returns A local seed source containing the resolved root and block directory, plus optional cleanup.
+ * @throws When the locator is invalid, the source cannot be fetched, or filesystem validation fails.
+ */
+export declare function resolveTemplateSeed(locator: RemoteTemplateLocator, cwd: string): Promise<SeedSource>;

package/dist/runtime/template-source-seeds.js

@@ -0,0 +1,243 @@
+import fs from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import semver from 'semver';
+import { x as extractTarball } from 'tar';
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from './template-registry.js';
+import { isPlainObject } from './object-utils.js';
+function selectRegistryVersion(metadata, locator) {
+    const distTags = isPlainObject(metadata['dist-tags'])
+        ? metadata['dist-tags']
+        : {};
+    const versions = isPlainObject(metadata.versions) ? metadata.versions : {};
+    const versionKeys = Object.keys(versions);
+    if (locator.type === 'version') {
+        if (!versions[locator.fetchSpec]) {
+            throw new Error(`npm template package version not found: ${locator.raw}`);
+        }
+        return locator.fetchSpec;
+    }
+    if (locator.type === 'tag') {
+        const taggedVersion = distTags[locator.fetchSpec];
+        if (typeof taggedVersion !== 'string') {
+            throw new Error(`npm template package tag not found: ${locator.raw}`);
+        }
+        return taggedVersion;
+    }
+    const range = locator.fetchSpec.trim().length > 0 ? locator.fetchSpec : '*';
+    const matchedVersion = semver.maxSatisfying(versionKeys, range);
+    if (matchedVersion) {
+        return matchedVersion;
+    }
+    if (locator.fetchSpec.trim().length > 0) {
+        throw new Error(`Unable to resolve npm template version for ${locator.raw}. Requested "${locator.fetchSpec}" but available versions are: ${versionKeys.join(', ') || '(none)'}.`);
+    }
+    const latestVersion = distTags.latest;
+    if (typeof latestVersion === 'string' && versions[latestVersion]) {
+        return latestVersion;
+    }
+    throw new Error(`Unable to resolve a published npm template version for ${locator.raw}.`);
+}
+async function fetchNpmTemplateSource(locator) {
+    const registryBase = (process.env.NPM_CONFIG_REGISTRY ?? 'https://registry.npmjs.org').replace(/\/$/, '');
+    const metadataResponse = await fetch(`${registryBase}/${encodeURIComponent(locator.name)}`);
+    if (!metadataResponse.ok) {
+        throw new Error(`Failed to fetch npm template metadata for ${locator.raw}: ${metadataResponse.status}`);
+    }
+    const metadata = (await metadataResponse.json());
+    const resolvedVersion = selectRegistryVersion(metadata, locator);
+    const versions = isPlainObject(metadata.versions) ? metadata.versions : {};
+    const versionMetadata = versions[resolvedVersion];
+    if (!isPlainObject(versionMetadata) || !isPlainObject(versionMetadata.dist)) {
+        throw new Error(`npm template metadata is missing dist information for ${locator.raw}@${resolvedVersion}.`);
+    }
+    const tarballUrl = versionMetadata.dist.tarball;
+    if (typeof tarballUrl !== 'string' || tarballUrl.length === 0) {
+        throw new Error(`npm template metadata is missing tarball URL for ${locator.raw}@${resolvedVersion}.`);
+    }
+    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
+    const cleanup = async () => {
+        await fsp.rm(tempRoot, { force: true, recursive: true });
+    };
+    try {
+        const tarballResponse = await fetch(tarballUrl);
+        if (!tarballResponse.ok) {
+            throw new Error(`Failed to download npm template tarball for ${locator.raw}: ${tarballResponse.status}`);
+        }
+        const tarballPath = path.join(tempRoot, 'template.tgz');
+        const unpackDir = path.join(tempRoot, 'source');
+        await fsp.mkdir(unpackDir, { recursive: true });
+        await fsp.writeFile(tarballPath, Buffer.from(await tarballResponse.arrayBuffer()));
+        await extractTarball({
+            cwd: unpackDir,
+            file: tarballPath,
+            strip: 1,
+        });
+        await assertNoSymlinks(unpackDir);
+        return {
+            blockDir: unpackDir,
+            cleanup,
+            rootDir: unpackDir,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+/**
+ * Resolve a locally installed npm template package from the caller workspace.
+ *
+ * Bare package ids are preferred here so monorepo and offline workflows can
+ * use an already-installed template without forcing a registry fetch.
+ */
+function resolveInstalledNpmTemplateSource(locator, cwd) {
+    if (locator.rawSpec !== '' && locator.rawSpec !== '*') {
+        return null;
+    }
+    const workspacePackagesRoot = path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, '..');
+    if (fs.existsSync(workspacePackagesRoot)) {
+        for (const entry of fs.readdirSync(workspacePackagesRoot, {
+            withFileTypes: true,
+        })) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const packageDir = path.join(workspacePackagesRoot, entry.name);
+            const packageJsonPath = path.join(packageDir, 'package.json');
+            if (!fs.existsSync(packageJsonPath)) {
+                continue;
+            }
+            const manifest = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+            if (manifest.name === locator.name) {
+                return {
+                    blockDir: packageDir,
+                    rootDir: packageDir,
+                };
+            }
+        }
+    }
+    const workspaceRequire = createRequire(path.join(path.resolve(cwd), '__wp_typia_template_resolver__.cjs'));
+    try {
+        const packageJsonPath = fs.realpathSync(workspaceRequire.resolve(`${locator.name}/package.json`));
+        const sourceDir = path.dirname(packageJsonPath);
+        return {
+            blockDir: sourceDir,
+            rootDir: sourceDir,
+        };
+    }
+    catch (error) {
+        const errorCode = typeof error === 'object' && error !== null && 'code' in error
+            ? String(error.code)
+            : '';
+        if (errorCode === 'MODULE_NOT_FOUND' ||
+            errorCode === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+            for (const basePath of workspaceRequire.resolve.paths(locator.name) ??
+                []) {
+                const packageJsonPath = path.join(basePath, locator.name, 'package.json');
+                if (!fs.existsSync(packageJsonPath)) {
+                    continue;
+                }
+                const sourceDir = path.dirname(fs.realpathSync(packageJsonPath));
+                return {
+                    blockDir: sourceDir,
+                    rootDir: sourceDir,
+                };
+            }
+            return null;
+        }
+        throw error;
+    }
+}
+export function isOfficialWorkspaceTemplateSeed(seed) {
+    const packageJsonPath = path.join(seed.rootDir, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return false;
+    }
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
+    }
+    catch {
+        return false;
+    }
+}
+export async function assertNoSymlinks(sourceDir) {
+    const stats = await fsp.lstat(sourceDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error(`Template sources may not include symbolic links: ${sourceDir}`);
+    }
+    if (!stats.isDirectory()) {
+        return;
+    }
+    for (const entry of await fsp.readdir(sourceDir)) {
+        await assertNoSymlinks(path.join(sourceDir, entry));
+    }
+}
+async function resolveGitHubTemplateSource(locator) {
+    const remoteRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
+    const cleanup = async () => {
+        await fsp.rm(remoteRoot, { force: true, recursive: true });
+    };
+    const checkoutDir = path.join(remoteRoot, 'source');
+    try {
+        const args = ['clone', '--depth', '1'];
+        if (locator.ref) {
+            args.push('--branch', locator.ref);
+        }
+        args.push(`https://github.com/${locator.owner}/${locator.repo}.git`, checkoutDir);
+        execFileSync('git', args, { stdio: 'ignore' });
+        const sourceDir = path.resolve(checkoutDir, locator.sourcePath);
+        const relativeSourceDir = path.relative(checkoutDir, sourceDir);
+        if (relativeSourceDir.startsWith('..') ||
+            path.isAbsolute(relativeSourceDir)) {
+            throw new Error('GitHub template path must stay within the cloned repository.');
+        }
+        if (!fs.existsSync(sourceDir)) {
+            throw new Error(`GitHub template path does not exist: ${locator.sourcePath}`);
+        }
+        await assertNoSymlinks(sourceDir);
+        return {
+            blockDir: sourceDir,
+            cleanup,
+            rootDir: sourceDir,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+/**
+ * Resolves a template locator into a local seed source directory.
+ *
+ * @param locator Remote template locator describing a local path, GitHub source, or npm package.
+ * @param cwd Current working directory used to resolve local template paths.
+ * @returns A local seed source containing the resolved root and block directory, plus optional cleanup.
+ * @throws When the locator is invalid, the source cannot be fetched, or filesystem validation fails.
+ */
+export async function resolveTemplateSeed(locator, cwd) {
+    if (locator.kind === 'path') {
+        const sourceDir = path.resolve(cwd, locator.templatePath);
+        if (!fs.existsSync(sourceDir)) {
+            throw new Error(`Template path does not exist: ${sourceDir}`);
+        }
+        await assertNoSymlinks(sourceDir);
+        return {
+            blockDir: sourceDir,
+            rootDir: sourceDir,
+        };
+    }
+    if (locator.kind === 'github') {
+        return resolveGitHubTemplateSource(locator.locator);
+    }
+    const installedSource = resolveInstalledNpmTemplateSource(locator.locator, cwd);
+    if (installedSource) {
+        await assertNoSymlinks(installedSource.blockDir);
+        return installedSource;
+    }
+    return fetchNpmTemplateSource(locator.locator);
+}

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

@@ -1,89 +1,7 @@
-import { type UnknownRecord } from './object-utils.js';
-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;
-    /** 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;
-    templateDir: string;
-    cleanup?: () => Promise<void>;
-    selectedVariant?: string | null;
-    warnings?: string[];
-}
-interface GitHubTemplateLocator {
-    owner: string;
-    repo: string;
-    ref: string | null;
-    sourcePath: string;
-}
-interface NpmTemplateLocator {
-    fetchSpec: string;
-    name: string;
-    raw: string;
-    rawSpec: string;
-    type: string;
-}
-interface SeedSource {
-    assetsDir?: string;
-    blockDir: string;
-    cleanup?: () => Promise<void>;
-    rootDir: string;
-    selectedVariant?: string | null;
-    warnings?: string[];
-}
-type RemoteTemplateLocator = {
-    kind: 'github';
-    locator: GitHubTemplateLocator;
-} | {
-    kind: 'npm';
-    locator: NpmTemplateLocator;
-} | {
-    kind: 'path';
-    templatePath: string;
-};
-export declare function parseGitHubTemplateLocator(templateId: string): GitHubTemplateLocator | null;
-export declare function parseNpmTemplateLocator(templateId: string): NpmTemplateLocator | null;
-export declare function parseTemplateLocator(templateId: string): RemoteTemplateLocator;
-/**
- * Resolves a template locator into a local seed source directory.
- *
- * @param locator Remote template locator describing a local path, GitHub source, or npm package.
- * @param cwd Current working directory used to resolve local template paths.
- * @returns A local seed source containing the resolved root and block directory, plus optional cleanup.
- * @throws When the locator is invalid, the source cannot be fetched, or filesystem validation fails.
- */
-export declare function resolveTemplateSeed(locator: RemoteTemplateLocator, cwd: string): Promise<SeedSource>;
+import type { ResolvedTemplateSource } from './template-source-contracts.js';
+export type { GitHubTemplateLocator, NpmTemplateLocator, RemoteTemplateLocator, ResolvedTemplateSource, TemplateSourceFormat, TemplateVariableContext, } from './template-source-contracts.js';
+export { parseGitHubTemplateLocator, parseNpmTemplateLocator, parseTemplateLocator, } from './template-source-locators.js';
+export { resolveTemplateSeed } from './template-source-seeds.js';
 export declare function resolveTemplateSource(templateId: string, cwd: string, variables: {
     [key: string]: string;
 }, variant?: string): Promise<ResolvedTemplateSource>;
-export {};