@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -1,324 +1,18 @@
-import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { assertValidGeneratedSlug, assertValidIntegrationEnvService, normalizeBlockSlug, } from "./cli-add-shared.js";
-import { formatRunScript, } from "./package-managers.js";
-import { pathExists, readOptionalUtf8File } from "./fs-async.js";
+import { appendMissingLines, writeFileIfAbsent, writeNewScaffoldFile, } from "./cli-add-workspace-integration-env-files.js";
+import { addIntegrationEnvPackageJsonEntries, mutateIntegrationEnvPackageJson, } from "./cli-add-workspace-integration-env-package-json.js";
+import { buildDockerComposeSource, buildEnvExampleSource, buildIntegrationEnvReadmeSource, buildIntegrationSmokeScriptSource, buildWpEnvConfigSource, } from "./cli-add-workspace-integration-env-source-emitters.js";
 import { executeWorkspaceMutationPlan } from "./cli-add-workspace-mutation.js";
+import { pathExists } from "./fs-async.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
-import { toTitleCase } from "./string-case.js";
-const WP_ENV_PACKAGE_VERSION = "^11.2.0";
-function buildWpEnvConfigSource() {
-    return `${JSON.stringify({
-        $schema: "https://schemas.wp.org/trunk/wp-env.json",
-        core: null,
-        port: 8888,
-        testsEnvironment: false,
-        plugins: ["."],
-        config: {
-            WP_DEBUG: true,
-            WP_DEBUG_LOG: true,
-            WP_DEBUG_DISPLAY: false,
-            SCRIPT_DEBUG: true,
-            WP_ENVIRONMENT_TYPE: "local",
-        },
-    }, null, 2)}\n`;
-}
-function buildDockerComposeSource() {
-    return `services:
-  integration-service:
-    image: node:22-alpine
-    working_dir: /workspace
-    volumes:
-      - .:/workspace
-    command: >
-      node -e "require('node:http').createServer((request, response) => {
-        response.writeHead(request.url === '/health' ? 200 : 404, {
-          'content-type': 'application/json'
-        });
-        response.end(JSON.stringify({
-          ok: request.url === '/health',
-          service: 'wp-typia-integration-starter'
-        }));
-      }).listen(3000, '0.0.0.0')"
-    ports:
-      - "3000:3000"
-`;
-}
-function buildIntegrationSmokeScriptSource(integrationEnvSlug) {
-    return `import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const ROOT_DIR = path.resolve(
-	fileURLToPath(new URL("../..", import.meta.url)),
-);
-const ENV_FILE = path.join(ROOT_DIR, ".env");
-
-function parseEnvValue(value) {
-	const trimmed = value.trim();
-	if (
-		(trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-		(trimmed.startsWith("'") && trimmed.endsWith("'"))
-	) {
-		return trimmed.slice(1, -1);
-	}
-
-	return trimmed;
-}
-
-function readEnvFile(filePath) {
-	if (!fs.existsSync(filePath)) {
-		return {};
-	}
-
-	return Object.fromEntries(
-		fs
-			.readFileSync(filePath, "utf8")
-			.split(/\\r?\\n/u)
-			.map((line) => line.trim())
-			.filter((line) => line.length > 0 && !line.startsWith("#"))
-			.map((line) => {
-				const separatorIndex = line.indexOf("=");
-				if (separatorIndex === -1) {
-					return null;
-				}
-
-				return [
-					line.slice(0, separatorIndex).trim(),
-					parseEnvValue(line.slice(separatorIndex + 1)),
-				];
-			})
-			.filter(Boolean),
-	);
-}
-
-const envFile = readEnvFile(ENV_FILE);
-
-function getEnv(name, fallback) {
-	return process.env[name] ?? envFile[name] ?? fallback;
-}
-
-function resolveEndpointUrl(baseUrl, endpointPath) {
-	const normalizedBaseUrl = new URL(baseUrl);
-	if (!normalizedBaseUrl.pathname.endsWith("/")) {
-		normalizedBaseUrl.pathname = \`\${normalizedBaseUrl.pathname}/\`;
-	}
-
-	const relativePath = endpointPath.replace(/^\\/+/u, "");
-	return new URL(relativePath, normalizedBaseUrl);
-}
-
-async function assertJsonEndpoint(label, url) {
-	const response = await fetch(url, {
-		headers: {
-			accept: "application/json",
-		},
-	});
-
-	if (!response.ok) {
-		throw new Error(
-			\`\${label} failed at \${url} with HTTP \${response.status}.\`,
-		);
-	}
-
-	const contentType = response.headers.get("content-type") ?? "";
-	if (!contentType.includes("application/json")) {
-		throw new Error(
-			\`\${label} at \${url} did not return JSON (content-type: \${contentType || "missing"}).\`,
-		);
-	}
-
-	return response.json();
-}
-
-const baseUrl = new URL(
-	getEnv("WP_TYPIA_SMOKE_BASE_URL", "http://localhost:8888"),
-);
-const serviceUrl = getEnv("WP_TYPIA_SERVICE_URL", "").trim();
-
-await assertJsonEndpoint(
-	"WordPress REST index",
-	resolveEndpointUrl(baseUrl, "wp-json/"),
-);
-
-if (serviceUrl.length > 0) {
-	await assertJsonEndpoint(
-		"Local integration service healthcheck",
-		resolveEndpointUrl(serviceUrl, "health"),
-	);
-}
-
-console.log("wp-typia integration smoke passed: ${integrationEnvSlug}");
-`;
-}
-function buildEnvExampleSource(service) {
-    return [
-        "# wp-typia integration smoke settings",
-        "WP_TYPIA_SMOKE_BASE_URL=http://localhost:8888",
-        "WP_TYPIA_SMOKE_USERNAME=admin",
-        "WP_TYPIA_SMOKE_PASSWORD=password",
-        ...(service === "docker-compose"
-            ? [
-                "",
-                "# Optional docker-compose integration service starter.",
-                "WP_TYPIA_SERVICE_URL=http://localhost:3000",
-            ]
-            : [
-                "",
-                "# Set this when your smoke test needs a project-specific service.",
-                "# WP_TYPIA_SERVICE_URL=http://localhost:3000",
-            ]),
-        "",
-    ].join("\n");
-}
-function buildIntegrationEnvReadmeSource({ integrationEnvSlug, service, withWpEnv, }) {
-    const title = toTitleCase(integrationEnvSlug);
-    const setupSteps = [
-        "Copy `.env.example` to `.env` and adjust the URLs or credentials for your local project.",
-        ...(withWpEnv
-            ? [
-                "Run `npm run wp-env:start` to start the generated WordPress environment.",
-            ]
-            : [
-                "Point `WP_TYPIA_SMOKE_BASE_URL` at the WordPress environment you already run locally.",
-            ]),
-        ...(service === "docker-compose"
-            ? [
-                "Run `npm run service:start` if you want the placeholder docker-compose service available at `WP_TYPIA_SERVICE_URL`.",
-            ]
-            : [
-                "Set `WP_TYPIA_SERVICE_URL` only when your integration smoke needs a local service dependency.",
-            ]),
-        `Run \`npm run smoke:${integrationEnvSlug}\` to execute the starter smoke check.`,
-    ];
-    return `# ${title} Integration Environment
-
-This starter keeps local WordPress integration smoke checks opt-in and editable.
-It does not change default block scaffolds or require wp-env unless this add
-workflow was run with \`--wp-env\`.
-
-## Setup
-
-${setupSteps.map((step, index) => `${index + 1}. ${step}`).join("\n")}
-
-## Adapting the Starter
-
-- Extend \`scripts/integration-smoke/${integrationEnvSlug}.mjs\` with the REST,
-  editor, or service assertions that matter for this project.
-- Keep secrets in \`.env\`; \`.env.example\` should document only safe defaults.
-- If your project uses a real service stack, replace the placeholder
-  \`docker-compose.integration.yml\` service with your database, queue, API, or
-  emulator containers.
-- Keep the smoke script focused on high-signal integration checks so CI and
-  local debugging stay fast.
-`;
-}
-async function appendMissingLines(filePath, lines) {
-    const current = (await readOptionalUtf8File(filePath)) ?? "";
-    const missingLines = lines.filter((line) => !current.includes(`${line}\n`) && !current.endsWith(line));
-    if (missingLines.length === 0) {
-        return;
-    }
-    const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
-    await fsp.mkdir(path.dirname(filePath), { recursive: true });
-    await fsp.writeFile(filePath, `${current}${separator}${missingLines.join("\n")}\n`, "utf8");
-}
-async function writeFileIfAbsent({ filePath, source, warnings, }) {
-    if (await pathExists(filePath)) {
-        warnings.push(`Preserved existing ${path.basename(filePath)}; review it manually if you need different local integration settings.`);
-        return;
-    }
-    await fsp.mkdir(path.dirname(filePath), { recursive: true });
-    await fsp.writeFile(filePath, source, "utf8");
-}
-async function writeNewScaffoldFile(filePath, source) {
-    if (await pathExists(filePath)) {
-        throw new Error(`An integration environment scaffold already exists at ${filePath}. Choose a different name.`);
-    }
-    await fsp.mkdir(path.dirname(filePath), { recursive: true });
-    await fsp.writeFile(filePath, source, "utf8");
-}
-function addScriptIfMissing({ scriptName, scripts, scriptValue, warnings, }) {
-    if (scripts[scriptName] === undefined) {
-        scripts[scriptName] = scriptValue;
-        return;
-    }
-    if (scripts[scriptName] !== scriptValue) {
-        warnings.push(`Preserved existing package script "${scriptName}"; add "${scriptValue}" manually if you want the generated integration command.`);
-    }
-}
-async function mutatePackageJson(projectDir, mutate) {
-    const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    mutate(packageJson);
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
-}
-function addIntegrationEnvPackageJsonEntries({ integrationEnvSlug, packageManager, packageJson, service, warnings, withWpEnv, }) {
-    const devDependencies = {
-        ...(packageJson.devDependencies ?? {}),
-    };
-    if (withWpEnv && devDependencies["@wordpress/env"] === undefined) {
-        devDependencies["@wordpress/env"] = WP_ENV_PACKAGE_VERSION;
-    }
-    packageJson.devDependencies = devDependencies;
-    const scripts = {
-        ...(packageJson.scripts ?? {}),
-    };
-    addScriptIfMissing({
-        scriptName: `smoke:${integrationEnvSlug}`,
-        scriptValue: `node scripts/integration-smoke/${integrationEnvSlug}.mjs`,
-        scripts,
-        warnings,
-    });
-    addScriptIfMissing({
-        scriptName: "smoke:integration",
-        scriptValue: formatRunScript(packageManager, `smoke:${integrationEnvSlug}`),
-        scripts,
-        warnings,
-    });
-    if (withWpEnv) {
-        addScriptIfMissing({
-            scriptName: "wp-env:start",
-            scriptValue: "wp-env start",
-            scripts,
-            warnings,
-        });
-        addScriptIfMissing({
-            scriptName: "wp-env:stop",
-            scriptValue: "wp-env stop",
-            scripts,
-            warnings,
-        });
-        addScriptIfMissing({
-            scriptName: "wp-env:reset",
-            scriptValue: "wp-env destroy all && wp-env start",
-            scripts,
-            warnings,
-        });
-    }
-    if (service === "docker-compose") {
-        addScriptIfMissing({
-            scriptName: "service:start",
-            scriptValue: "docker compose -f docker-compose.integration.yml up -d",
-            scripts,
-            warnings,
-        });
-        addScriptIfMissing({
-            scriptName: "service:stop",
-            scriptValue: "docker compose -f docker-compose.integration.yml down",
-            scripts,
-            warnings,
-        });
-    }
-    packageJson.scripts = scripts;
-}
 /**
  * Add an opt-in local WordPress integration environment starter to an official
  * workspace.
  */
-export async function runAddIntegrationEnvCommand({ cwd = process.cwd(), integrationEnvName, service, withWpEnv = false, }) {
+export async function runAddIntegrationEnvCommand({ cwd = process.cwd(), integrationEnvName, service, withReleaseZip = false, withWpEnv = false, }) {
     const workspace = resolveWorkspaceProject(cwd);
-    const integrationEnvSlug = assertValidGeneratedSlug("Integration environment name", normalizeBlockSlug(integrationEnvName), "wp-typia add integration-env <name> [--wp-env]");
+    const integrationEnvSlug = assertValidGeneratedSlug("Integration environment name", normalizeBlockSlug(integrationEnvName), "wp-typia add integration-env <name> [--wp-env] [--release-zip]");
     const serviceId = assertValidIntegrationEnvService(service);
     const warnings = [];
     const packageJsonPath = path.join(workspace.projectDir, "package.json");
@@ -351,6 +45,7 @@ export async function runAddIntegrationEnvCommand({ cwd = process.cwd(), integra
             await writeNewScaffoldFile(docsPath, buildIntegrationEnvReadmeSource({
                 integrationEnvSlug,
                 service: serviceId,
+                withReleaseZip,
                 withWpEnv,
             }));
             await appendMissingLines(envExamplePath, [
@@ -371,11 +66,12 @@ export async function runAddIntegrationEnvCommand({ cwd = process.cwd(), integra
                     warnings,
                 });
             }
-            await mutatePackageJson(workspace.projectDir, (packageJson) => addIntegrationEnvPackageJsonEntries({
+            await mutateIntegrationEnvPackageJson(workspace.projectDir, (packageJson) => addIntegrationEnvPackageJsonEntries({
                 integrationEnvSlug,
                 packageManager: workspace.packageManager,
                 packageJson,
                 service: serviceId,
+                withReleaseZip,
                 warnings,
                 withWpEnv,
             }));
@@ -386,6 +82,7 @@ export async function runAddIntegrationEnvCommand({ cwd = process.cwd(), integra
         projectDir: workspace.projectDir,
         service: serviceId,
         warnings: warnings.length > 0 ? warnings : undefined,
+        withReleaseZip,
         withWpEnv,
     };
 }

package/dist/runtime/cli-add-workspace-pattern-anchors.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Ensure workspace bootstrap PHP registers pattern categories and loads
+ * generated pattern modules from both flat and nested pattern directories.
+ *
+ * @param workspace Resolved official workspace project metadata.
+ * @returns A promise that resolves after the workspace bootstrap is patched.
+ * @throws {Error} When existing bootstrap source cannot be safely patched.
+ */
+export declare function ensurePatternBootstrapAnchors(workspace: WorkspaceProject): Promise<void>;

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

@@ -0,0 +1,95 @@
+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";
+import { toTitleCase } from "./string-case.js";
+const FLAT_PATTERN_GLOB = "glob( __DIR__ . '/src/patterns/*.php' ) ?: array()";
+const NESTED_PATTERN_GLOB = "glob( __DIR__ . '/src/patterns/*/*.php' ) ?: array()";
+const LEGACY_FLAT_PATTERN_MODULES_ASSIGNMENT_PATTERN = /^[ \t]*\$pattern_modules\s*=\s*glob\( __DIR__ \. '\/src\/patterns\/\*\.php' \) \?: array\(\);\s*$/mu;
+const LEGACY_FLAT_PATTERN_FOREACH_PATTERN = /^[ \t]*foreach\s*\(\s*glob\( __DIR__ \. '\/src\/patterns\/\*\.php' \) \?: array\(\)\s+as\s+\$pattern_module\s*\)\s*\{\r?\n[ \t]*require\s+\$pattern_module;\r?\n[ \t]*\}/mu;
+function buildNestedPatternModulesAssignment() {
+    return [
+        "\t$pattern_modules = array_merge(",
+        `\t\t${FLAT_PATTERN_GLOB},`,
+        `\t\t${NESTED_PATTERN_GLOB}`,
+        "\t);",
+    ].join("\n");
+}
+function ensureNestedPatternLoaderSource(source, bootstrapPath) {
+    if (source.includes(NESTED_PATTERN_GLOB)) {
+        return source;
+    }
+    if (LEGACY_FLAT_PATTERN_FOREACH_PATTERN.test(source)) {
+        return source.replace(LEGACY_FLAT_PATTERN_FOREACH_PATTERN, [
+            buildNestedPatternModulesAssignment(),
+            "\tforeach ( $pattern_modules as $pattern_module ) {",
+            "\t\trequire $pattern_module;",
+            "\t}",
+        ].join("\n"));
+    }
+    if (LEGACY_FLAT_PATTERN_MODULES_ASSIGNMENT_PATTERN.test(source)) {
+        return source.replace(LEGACY_FLAT_PATTERN_MODULES_ASSIGNMENT_PATTERN, buildNestedPatternModulesAssignment());
+    }
+    if (source.includes("array_merge(") && source.includes(FLAT_PATTERN_GLOB)) {
+        return source.replace(FLAT_PATTERN_GLOB, `${FLAT_PATTERN_GLOB},\n\t\t${NESTED_PATTERN_GLOB}`);
+    }
+    throw new Error(`Unable to repair ${path.basename(bootstrapPath)} pattern loader for nested src/patterns directories.`);
+}
+/**
+ * Ensure workspace bootstrap PHP registers pattern categories and loads
+ * generated pattern modules from both flat and nested pattern directories.
+ *
+ * @param workspace Resolved official workspace project metadata.
+ * @returns A promise that resolves after the workspace bootstrap is patched.
+ * @throws {Error} When existing bootstrap source cannot be safely patched.
+ */
+export async function ensurePatternBootstrapAnchors(workspace) {
+    const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    await patchFile(bootstrapPath, (source) => {
+        let nextSource = source;
+        const patternCategoryFunctionName = `${workspace.workspace.phpPrefix}_register_pattern_category`;
+        const patternRegistrationFunctionName = `${workspace.workspace.phpPrefix}_register_patterns`;
+        const patternCategoryHook = `add_action( 'init', '${patternCategoryFunctionName}' );`;
+        const patternRegistrationHook = `add_action( 'init', '${patternRegistrationFunctionName}', 20 );`;
+        const patternFunctions = `
+
+function ${patternCategoryFunctionName}() {
+	if ( function_exists( 'register_block_pattern_category' ) ) {
+		register_block_pattern_category(
+			'${workspace.workspace.namespace}',
+			array(
+				'label' => __( ${JSON.stringify(`${toTitleCase(workspaceBaseName)} Patterns`)}, '${workspace.workspace.textDomain}' ),
+			)
+		);
+	}
+}
+
+function ${patternRegistrationFunctionName}() {
+	$pattern_modules = array_merge(
+		${FLAT_PATTERN_GLOB},
+		${NESTED_PATTERN_GLOB}
+	);
+	foreach ( $pattern_modules as $pattern_module ) {
+		require $pattern_module;
+	}
+}
+`;
+        if (!hasPhpFunctionDefinition(nextSource, patternCategoryFunctionName) &&
+            !hasPhpFunctionDefinition(nextSource, patternRegistrationFunctionName)) {
+            nextSource = insertPhpSnippetBeforeWorkspaceAnchors(nextSource, patternFunctions);
+        }
+        if (!hasPhpFunctionDefinition(nextSource, patternCategoryFunctionName) ||
+            !hasPhpFunctionDefinition(nextSource, patternRegistrationFunctionName)) {
+            throw new Error(`Unable to inject pattern bootstrap functions into ${path.basename(bootstrapPath)}.`);
+        }
+        nextSource = ensureNestedPatternLoaderSource(nextSource, bootstrapPath);
+        if (!nextSource.includes(patternCategoryHook)) {
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, patternCategoryHook);
+        }
+        if (!nextSource.includes(patternRegistrationHook)) {
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, patternRegistrationHook);
+        }
+        return nextSource;
+    });
+}

package/dist/runtime/cli-add-workspace-pattern-options.d.ts

@@ -0,0 +1,20 @@
+import { type RunAddPatternCommandOptions } from "./cli-add-shared.js";
+import { type PatternCatalogScope } from "./pattern-catalog.js";
+export type ResolvedPatternCatalogOptions = {
+    contentFile: string;
+    patternScope: PatternCatalogScope;
+    sectionRole?: string;
+    tags: string[];
+    thumbnailUrl?: string;
+    title: string;
+};
+/**
+ * Resolve and validate catalog metadata for a generated workspace pattern.
+ *
+ * @param patternSlug Normalized and validated pattern slug.
+ * @param options Raw add-pattern command options from the CLI layer.
+ * @returns Resolved catalog metadata and safe relative content path.
+ * @throws {Error} When scope, section-role coupling, tags, thumbnail URL, or
+ * content file paths are invalid.
+ */
+export declare function resolvePatternCatalogOptions(patternSlug: string, options: RunAddPatternCommandOptions): ResolvedPatternCatalogOptions;

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

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { assertValidGeneratedSlug, normalizeBlockSlug, } from "./cli-add-shared.js";
+import { isValidPatternThumbnailUrl, PATTERN_CATALOG_SCOPE_IDS, } from "./pattern-catalog.js";
+import { toTitleCase } from "./string-case.js";
+const PATTERN_CONTENT_FILE_ROOT = "src/patterns/";
+const PATTERN_TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
+function assertValidPatternRelativePath(label, value, usage) {
+    const normalizedPath = value.trim().replace(/\\/gu, "/");
+    if (normalizedPath.length === 0 ||
+        path.isAbsolute(normalizedPath) ||
+        normalizedPath.split("/").includes("..") ||
+        /[<>:"|?*\u0000-\u001F]/u.test(normalizedPath)) {
+        throw new Error(`${label} must be a safe relative project path. Use \`${usage}\`.`);
+    }
+    return normalizedPath;
+}
+function assertValidPatternContentFile(value, usage) {
+    const normalizedPath = assertValidPatternRelativePath("Pattern content file", value, usage);
+    if (!isLoadablePatternContentFilePath(normalizedPath)) {
+        throw new Error("Pattern content file must live directly under `src/patterns/` or one nested directory under `src/patterns/` and end in `.php` so the generated PHP loader can require it.");
+    }
+    return normalizedPath;
+}
+function isLoadablePatternContentFilePath(normalizedPath) {
+    if (!normalizedPath.startsWith(PATTERN_CONTENT_FILE_ROOT) ||
+        !normalizedPath.endsWith(".php")) {
+        return false;
+    }
+    const patternRelativePath = normalizedPath.slice(PATTERN_CONTENT_FILE_ROOT.length);
+    const segments = patternRelativePath.split("/");
+    return ((segments.length === 1 || segments.length === 2) &&
+        segments.every((segment) => segment.length > 0));
+}
+function resolvePatternScope(scope) {
+    if (scope === undefined || scope.trim() === "") {
+        return "full";
+    }
+    const normalizedScope = scope.trim();
+    if (PATTERN_CATALOG_SCOPE_IDS.includes(normalizedScope)) {
+        return normalizedScope;
+    }
+    throw new Error(`Pattern scope must be one of: ${PATTERN_CATALOG_SCOPE_IDS.join(", ")}.`);
+}
+function normalizeOptionalSlug(label, value, usage) {
+    if (value === undefined || value.trim() === "") {
+        return undefined;
+    }
+    return assertValidGeneratedSlug(label, normalizeBlockSlug(value), usage);
+}
+function normalizePatternTags(tags) {
+    const rawTags = typeof tags === "string"
+        ? tags.split(",")
+        : Array.isArray(tags)
+            ? [...tags]
+            : [];
+    const normalizedTags = rawTags
+        .map((tag) => normalizeBlockSlug(tag))
+        .filter((tag) => tag.length > 0);
+    for (const tag of normalizedTags) {
+        if (!PATTERN_TAG_PATTERN.test(tag)) {
+            throw new Error(`Pattern tag "${tag}" must contain only lowercase letters, numbers, and hyphens.`);
+        }
+    }
+    return [...new Set(normalizedTags)].sort();
+}
+function normalizePatternThumbnailUrl(value) {
+    if (value === undefined || value.trim() === "") {
+        return undefined;
+    }
+    const thumbnailUrl = value.trim();
+    if (!isValidPatternThumbnailUrl(thumbnailUrl)) {
+        throw new Error("Pattern thumbnail URL must be an http(s) URL or safe relative project path.");
+    }
+    return thumbnailUrl;
+}
+function resolvePatternContentFile(patternSlug, patternScope, contentFile) {
+    if (contentFile && contentFile.trim() !== "") {
+        return assertValidPatternContentFile(contentFile, "wp-typia add pattern <name> [--scope <full|section>]");
+    }
+    const scopeDirectory = patternScope === "section" ? "sections" : "full";
+    return path.posix.join("src", "patterns", scopeDirectory, `${patternSlug}.php`);
+}
+/**
+ * Resolve and validate catalog metadata for a generated workspace pattern.
+ *
+ * @param patternSlug Normalized and validated pattern slug.
+ * @param options Raw add-pattern command options from the CLI layer.
+ * @returns Resolved catalog metadata and safe relative content path.
+ * @throws {Error} When scope, section-role coupling, tags, thumbnail URL, or
+ * content file paths are invalid.
+ */
+export function resolvePatternCatalogOptions(patternSlug, options) {
+    const patternScope = resolvePatternScope(options.patternScope);
+    const sectionRole = normalizeOptionalSlug("Pattern section role", options.sectionRole, "wp-typia add pattern <name> --scope section --section-role <role>");
+    if (patternScope === "section" && !sectionRole) {
+        throw new Error("`wp-typia add pattern --scope section` requires --section-role <role>.");
+    }
+    if (patternScope !== "section" && sectionRole) {
+        throw new Error("`--section-role` requires `--scope section`.");
+    }
+    const title = options.catalogTitle && options.catalogTitle.trim() !== ""
+        ? options.catalogTitle.trim()
+        : toTitleCase(patternSlug);
+    const thumbnailUrl = normalizePatternThumbnailUrl(options.thumbnailUrl);
+    return {
+        contentFile: resolvePatternContentFile(patternSlug, patternScope, options.contentFile),
+        patternScope,
+        ...(sectionRole ? { sectionRole } : {}),
+        tags: normalizePatternTags(options.tags),
+        ...(thumbnailUrl ? { thumbnailUrl } : {}),
+        title,
+    };
+}

package/dist/runtime/cli-add-workspace-pattern-source-emitters.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedPatternCatalogOptions } from "./cli-add-workspace-pattern-options.js";
+/**
+ * Render the block-config inventory entry for a generated pattern.
+ *
+ * @param patternSlug Normalized and validated pattern slug.
+ * @param options Resolved pattern catalog metadata.
+ * @returns A TypeScript object literal snippet for the workspace inventory.
+ */
+export declare function buildPatternConfigEntry(patternSlug: string, options: ResolvedPatternCatalogOptions): string;
+/**
+ * Render the PHP pattern module registered by the workspace add command.
+ *
+ * @param patternSlug Normalized and validated pattern slug.
+ * @param namespace WordPress block namespace for the workspace.
+ * @param sectionRole Optional section role for section-scoped patterns.
+ * @param textDomain Translation text domain for generated labels.
+ * @param title Human-readable pattern title.
+ * @returns PHP source for a single generated block pattern module.
+ */
+export declare function buildPatternSource(patternSlug: string, namespace: string, sectionRole: string | undefined, textDomain: string, title: string): string;

package/dist/runtime/cli-add-workspace-pattern-source-emitters.js

@@ -0,0 +1,57 @@
+import { quoteTsString } from "./cli-add-shared.js";
+/**
+ * Render the block-config inventory entry for a generated pattern.
+ *
+ * @param patternSlug Normalized and validated pattern slug.
+ * @param options Resolved pattern catalog metadata.
+ * @returns A TypeScript object literal snippet for the workspace inventory.
+ */
+export function buildPatternConfigEntry(patternSlug, options) {
+    const lines = [
+        "\t{",
+        `\t\tcontentFile: ${quoteTsString(options.contentFile)},`,
+        `\t\tfile: ${quoteTsString(options.contentFile)},`,
+        `\t\tscope: ${quoteTsString(options.patternScope)},`,
+        ...(options.sectionRole
+            ? [`\t\tsectionRole: ${quoteTsString(options.sectionRole)},`]
+            : []),
+        `\t\tslug: ${quoteTsString(patternSlug)},`,
+        `\t\ttags: [${options.tags.map((tag) => quoteTsString(tag)).join(", ")}],`,
+        ...(options.thumbnailUrl
+            ? [`\t\tthumbnailUrl: ${quoteTsString(options.thumbnailUrl)},`]
+            : []),
+        `\t\ttitle: ${quoteTsString(options.title)},`,
+        "\t},",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Render the PHP pattern module registered by the workspace add command.
+ *
+ * @param patternSlug Normalized and validated pattern slug.
+ * @param namespace WordPress block namespace for the workspace.
+ * @param sectionRole Optional section role for section-scoped patterns.
+ * @param textDomain Translation text domain for generated labels.
+ * @param title Human-readable pattern title.
+ * @returns PHP source for a single generated block pattern module.
+ */
+export function buildPatternSource(patternSlug, namespace, sectionRole, textDomain, title) {
+    const content = sectionRole
+        ? `'<!-- wp:group {"className":"section section--${sectionRole}"} --><div class="wp-block-group section section--${sectionRole}"><!-- wp:paragraph --><p>' . esc_html__( 'Describe this section pattern here.', '${textDomain}' ) . '</p><!-- /wp:paragraph --></div><!-- /wp:group -->'`
+        : `'<!-- wp:paragraph --><p>' . esc_html__( 'Describe this pattern here.', '${textDomain}' ) . '</p><!-- /wp:paragraph -->'`;
+    return `<?php
+if ( ! defined( 'ABSPATH' ) ) {
+	return;
+}
+
+register_block_pattern(
+	'${namespace}/${patternSlug}',
+	array(
+		'title'       => __( ${JSON.stringify(title)}, '${textDomain}' ),
+		'description' => __( ${JSON.stringify(`A starter pattern for ${title}.`)}, '${textDomain}' ),
+		'categories'  => array( '${namespace}' ),
+		'content'     => ${content},
+	)
+);
+`;
+}