@wp-typia/project-tools 0.24.4 → 0.24.6

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

@@ -0,0 +1,122 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { readJsonFile } from "../shared/json-utils.js";
+import { formatRunScript, } from "../shared/package-managers.js";
+import { DEFAULT_WORDPRESS_ENV_VERSION } from "../shared/package-versions.js";
+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.`);
+    }
+}
+/**
+ * Read, mutate, and persist a workspace package manifest for integration-env
+ * scaffolding.
+ *
+ * @param projectDir Absolute official workspace project directory.
+ * @param mutate Callback that mutates the parsed package manifest.
+ * @returns A promise that resolves after `package.json` is written.
+ */
+export async function mutateIntegrationEnvPackageJson(projectDir, mutate) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "integration env package manifest",
+    });
+    mutate(packageJson);
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+}
+/**
+ * Add integration-env dev dependency and package scripts when they are missing,
+ * preserving user-defined script values with warnings.
+ *
+ * @param options Package mutation options.
+ * @param options.integrationEnvSlug Normalized integration environment slug.
+ * @param options.packageManager Package manager used for generated run scripts.
+ * @param options.packageJson Mutable parsed workspace package manifest.
+ * @param options.service Selected optional local service starter.
+ * @param options.withReleaseZip Whether release zip package scripts should be added.
+ * @param options.warnings Mutable warning collection for preserved script values.
+ * @param options.withWpEnv Whether wp-env scripts and dependency should be added.
+ */
+export function addIntegrationEnvPackageJsonEntries({ integrationEnvSlug, packageManager, packageJson, withReleaseZip, service, warnings, withWpEnv, }) {
+    const devDependencies = {
+        ...(packageJson.devDependencies ?? {}),
+    };
+    if (withWpEnv && devDependencies["@wordpress/env"] === undefined) {
+        devDependencies["@wordpress/env"] = DEFAULT_WORDPRESS_ENV_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 (withReleaseZip) {
+        addScriptIfMissing({
+            scriptName: "release:zip",
+            scriptValue: `${formatRunScript(packageManager, "sync-rest:package")} && ${formatRunScript(packageManager, "build")} && wp-scripts plugin-zip`,
+            scripts,
+            warnings,
+        });
+        addScriptIfMissing({
+            scriptName: "release:zip:check",
+            scriptValue: `${formatRunScript(packageManager, "sync-rest:package:check")} && ${formatRunScript(packageManager, "build")}`,
+            scripts,
+            warnings,
+        });
+        addScriptIfMissing({
+            scriptName: "qa:check",
+            scriptValue: `${formatRunScript(packageManager, "wp-typia:doctor:workspace")} && ${formatRunScript(packageManager, "release:zip:check")}`,
+            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;
+}

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

@@ -0,0 +1,44 @@
+import type { IntegrationEnvServiceId } from "./cli-add-shared.js";
+/**
+ * Render the default `@wordpress/env` configuration for an integration
+ * environment starter.
+ *
+ * @returns JSON source for `.wp-env.json`.
+ */
+export declare function buildWpEnvConfigSource(): string;
+/**
+ * Render the placeholder docker-compose service used by the integration starter.
+ *
+ * @returns YAML source for `docker-compose.integration.yml`.
+ */
+export declare function buildDockerComposeSource(): string;
+/**
+ * Render the editable Node smoke-test starter for a workspace.
+ *
+ * @param integrationEnvSlug Normalized integration environment slug.
+ * @returns JavaScript module source for the generated smoke runner.
+ */
+export declare function buildIntegrationSmokeScriptSource(integrationEnvSlug: string): string;
+/**
+ * Render safe default environment variables for integration smoke checks.
+ *
+ * @param service Selected optional local service starter.
+ * @returns Source for entries appended to `.env.example`.
+ */
+export declare function buildEnvExampleSource(service: IntegrationEnvServiceId): string;
+/**
+ * Render integration environment onboarding documentation.
+ *
+ * @param options Integration environment documentation options.
+ * @param options.integrationEnvSlug Normalized integration environment slug.
+ * @param options.service Selected optional local service starter.
+ * @param options.withReleaseZip Whether release zip scripts were scaffolded.
+ * @param options.withWpEnv Whether wp-env setup was scaffolded.
+ * @returns Markdown source for the generated integration environment guide.
+ */
+export declare function buildIntegrationEnvReadmeSource({ integrationEnvSlug, service, withReleaseZip, withWpEnv, }: {
+    integrationEnvSlug: string;
+    service: IntegrationEnvServiceId;
+    withReleaseZip: boolean;
+    withWpEnv: boolean;
+}): string;

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

@@ -0,0 +1,262 @@
+import { toTitleCase } from "../shared/string-case.js";
+/**
+ * Render the default `@wordpress/env` configuration for an integration
+ * environment starter.
+ *
+ * @returns JSON source for `.wp-env.json`.
+ */
+export 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`;
+}
+/**
+ * Render the placeholder docker-compose service used by the integration starter.
+ *
+ * @returns YAML source for `docker-compose.integration.yml`.
+ */
+export 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"
+`;
+}
+/**
+ * Render the editable Node smoke-test starter for a workspace.
+ *
+ * @param integrationEnvSlug Normalized integration environment slug.
+ * @returns JavaScript module source for the generated smoke runner.
+ */
+export 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 getPositiveIntegerEnv(name, fallback) {
+	const value = Number.parseInt(getEnv(name, String(fallback)), 10);
+	return Number.isFinite(value) && value > 0 ? value : 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 requestTimeoutMs = getPositiveIntegerEnv(
+		"WP_TYPIA_SMOKE_TIMEOUT_MS",
+		30_000,
+	);
+	const response = await fetch(url, {
+		headers: {
+			accept: "application/json",
+		},
+		signal: AbortSignal.timeout(requestTimeoutMs),
+	});
+
+	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();
+
+// Extend this starter with project-specific generated REST clients or schema
+// checks as the workspace grows. For example, read JSON schemas under
+// src/rest/<resource>/api-schemas or import TS clients through a tsx-powered
+// smoke runner when you need authenticated route coverage.
+
+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}");
+`;
+}
+/**
+ * Render safe default environment variables for integration smoke checks.
+ *
+ * @param service Selected optional local service starter.
+ * @returns Source for entries appended to `.env.example`.
+ */
+export 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",
+        "WP_TYPIA_SMOKE_TIMEOUT_MS=30000",
+        ...(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");
+}
+/**
+ * Render integration environment onboarding documentation.
+ *
+ * @param options Integration environment documentation options.
+ * @param options.integrationEnvSlug Normalized integration environment slug.
+ * @param options.service Selected optional local service starter.
+ * @param options.withReleaseZip Whether release zip scripts were scaffolded.
+ * @param options.withWpEnv Whether wp-env setup was scaffolded.
+ * @returns Markdown source for the generated integration environment guide.
+ */
+export function buildIntegrationEnvReadmeSource({ integrationEnvSlug, service, withReleaseZip, 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.`,
+        ...(withReleaseZip
+            ? [
+                "Run `npm run release:zip` after smoke checks pass to build a distributable plugin zip.",
+            ]
+            : []),
+    ];
+    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.
+${withReleaseZip ? "- Treat `release:zip:check` as a CI guard before packaging release artifacts.\n" : ""}
+`;
+}

package/dist/runtime/add/cli-add-workspace-integration-env.d.ts

@@ -0,0 +1,26 @@
+import { type IntegrationEnvServiceId, type RunAddIntegrationEnvCommandOptions } from "./cli-add-shared.js";
+/**
+ * Runtime result returned after adding an integration environment starter.
+ *
+ * @property integrationEnvSlug Normalized slug used for generated script and
+ * documentation paths.
+ * @property projectDir Absolute official workspace directory that was updated.
+ * @property service Canonical local service starter id selected for the scaffold.
+ * @property warnings Optional non-fatal preservation notices for existing files
+ * or scripts.
+ * @property withReleaseZip Whether release zip packaging scripts were added.
+ * @property withWpEnv Whether the generated scaffold included the wp-env preset.
+ */
+export interface RunAddIntegrationEnvCommandResult {
+    integrationEnvSlug: string;
+    projectDir: string;
+    service: IntegrationEnvServiceId;
+    warnings?: string[];
+    withReleaseZip: boolean;
+    withWpEnv: boolean;
+}
+/**
+ * Add an opt-in local WordPress integration environment starter to an official
+ * workspace.
+ */
+export declare function runAddIntegrationEnvCommand({ cwd, integrationEnvName, service, withReleaseZip, withWpEnv, }: RunAddIntegrationEnvCommandOptions): Promise<RunAddIntegrationEnvCommandResult>;

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

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { assertValidGeneratedSlug, assertValidIntegrationEnvService, normalizeBlockSlug, } from "./cli-add-shared.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 "../shared/fs-async.js";
+import { resolveWorkspaceProject } from "../workspace/workspace-project.js";
+/**
+ * Add an opt-in local WordPress integration environment starter to an official
+ * workspace.
+ */
+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] [--release-zip]");
+    const serviceId = assertValidIntegrationEnvService(service);
+    const warnings = [];
+    const packageJsonPath = path.join(workspace.projectDir, "package.json");
+    const gitignorePath = path.join(workspace.projectDir, ".gitignore");
+    const envExamplePath = path.join(workspace.projectDir, ".env.example");
+    const wpEnvPath = path.join(workspace.projectDir, ".wp-env.json");
+    const dockerComposePath = path.join(workspace.projectDir, "docker-compose.integration.yml");
+    const smokeDir = path.join(workspace.projectDir, "scripts", "integration-smoke");
+    const docsDir = path.join(workspace.projectDir, "docs", "integration-env");
+    const smokeScriptPath = path.join(smokeDir, `${integrationEnvSlug}.mjs`);
+    const docsPath = path.join(docsDir, `${integrationEnvSlug}.md`);
+    const shouldRemoveSmokeDirOnRollback = !(await pathExists(smokeDir));
+    const shouldRemoveDocsDirOnRollback = !(await pathExists(docsDir));
+    await executeWorkspaceMutationPlan({
+        filePaths: [
+            packageJsonPath,
+            gitignorePath,
+            envExamplePath,
+            ...(withWpEnv ? [wpEnvPath] : []),
+            ...(serviceId === "docker-compose" ? [dockerComposePath] : []),
+        ],
+        targetPaths: [
+            smokeScriptPath,
+            docsPath,
+            ...(shouldRemoveSmokeDirOnRollback ? [smokeDir] : []),
+            ...(shouldRemoveDocsDirOnRollback ? [docsDir] : []),
+        ],
+        run: async () => {
+            await writeNewScaffoldFile(smokeScriptPath, buildIntegrationSmokeScriptSource(integrationEnvSlug));
+            await writeNewScaffoldFile(docsPath, buildIntegrationEnvReadmeSource({
+                integrationEnvSlug,
+                service: serviceId,
+                withReleaseZip,
+                withWpEnv,
+            }));
+            await appendMissingLines(envExamplePath, [
+                ...buildEnvExampleSource(serviceId).trimEnd().split("\n"),
+            ]);
+            await appendMissingLines(gitignorePath, [".env", ".env.local"]);
+            if (withWpEnv) {
+                await writeFileIfAbsent({
+                    filePath: wpEnvPath,
+                    source: buildWpEnvConfigSource(),
+                    warnings,
+                });
+            }
+            if (serviceId === "docker-compose") {
+                await writeFileIfAbsent({
+                    filePath: dockerComposePath,
+                    source: buildDockerComposeSource(),
+                    warnings,
+                });
+            }
+            await mutateIntegrationEnvPackageJson(workspace.projectDir, (packageJson) => addIntegrationEnvPackageJsonEntries({
+                integrationEnvSlug,
+                packageManager: workspace.packageManager,
+                packageJson,
+                service: serviceId,
+                withReleaseZip,
+                warnings,
+                withWpEnv,
+            }));
+        },
+    });
+    return {
+        integrationEnvSlug,
+        projectDir: workspace.projectDir,
+        service: serviceId,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        withReleaseZip,
+        withWpEnv,
+    };
+}

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

@@ -0,0 +1,30 @@
+export interface WorkspaceMutationPlan<TResult> {
+    /** Files to capture before the mutation starts. Missing files are restored as absent. */
+    filePaths: string[];
+    /** Snapshot directories created by the mutation, usually migration fixtures. */
+    snapshotDirs?: string[];
+    /** Created files or directories to remove if the mutation fails. */
+    targetPaths?: string[];
+    /** Mutating work to execute after the snapshot is captured. */
+    run: () => Promise<TResult>;
+}
+/**
+ * Error thrown when the mutation and its rollback both fail.
+ */
+export declare class WorkspaceMutationRollbackError extends Error {
+    readonly mutationError: unknown;
+    readonly rollbackError: unknown;
+    constructor(mutationError: unknown, rollbackError: unknown);
+}
+/**
+ * Execute a workspace add mutation with rollback on any failure.
+ */
+export declare function executeWorkspaceMutationPlan<TResult>({ filePaths, run, snapshotDirs, targetPaths, }: WorkspaceMutationPlan<TResult>): Promise<TResult>;
+/**
+ * Insert a PHP snippet before the workspace textdomain hook or closing tag.
+ */
+export declare function insertPhpSnippetBeforeWorkspaceAnchors(source: string, snippet: string): string;
+/**
+ * Append a PHP snippet before the closing tag when one is present.
+ */
+export declare function appendPhpSnippetBeforeClosingTag(source: string, snippet: string): string;

package/dist/runtime/add/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/add/cli-add-workspace-pattern-anchors.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceProject } from "../workspace/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>;