@wp-typia/project-tools 0.22.10 → 0.23.0

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

@@ -0,0 +1,42 @@
+import { quoteTsString, } from "./cli-add-shared.js";
+import { toTitleCase } from "./string-case.js";
+/**
+ * Render one `CONTRACTS` inventory entry for `scripts/block-config.ts`.
+ *
+ * @param contractSlug Stable kebab-case contract id.
+ * @param sourceTypeName Exported TypeScript type/interface used for schema generation.
+ */
+export function buildContractConfigEntry(contractSlug, sourceTypeName) {
+    return [
+        "\t{",
+        `\t\tschemaFile: ${quoteTsString(`src/contracts/${contractSlug}.schema.json`)},`,
+        `\t\tslug: ${quoteTsString(contractSlug)},`,
+        `\t\tsourceTypeName: ${quoteTsString(sourceTypeName)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/contracts/${contractSlug}.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+/**
+ * Render a small starter TypeScript contract that users can replace with their
+ * real external route, smoke-test, or PHP integration payload shape.
+ *
+ * @param contractSlug Stable kebab-case contract id.
+ * @param sourceTypeName Exported TypeScript type/interface used for schema generation.
+ */
+export function buildContractTypesSource(contractSlug, sourceTypeName) {
+    const title = toTitleCase(contractSlug);
+    return `/**
+ * ${title} is a standalone wire contract.
+ *
+ * It does not register a WordPress REST route. Edit this type, then run
+ * \`wp-typia sync-rest\` or \`wp-typia sync\` to refresh the JSON Schema
+ * artifact referenced from scripts/block-config.ts.
+ */
+export interface ${sourceTypeName} {
+\tid: string;
+\tstatus: 'pending' | 'ready';
+\tupdatedAt: string;
+\tmessage?: string;
+}
+`;
+}

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

@@ -0,0 +1,15 @@
+import { type RunAddContractCommandOptions } from "./cli-add-shared.js";
+/**
+ * Scaffold a standalone TypeScript wire contract and synchronize its JSON
+ * Schema artifact without generating PHP route glue.
+ *
+ * @param options Command options for the standalone contract workflow.
+ * @returns Resolved scaffold metadata for the created contract.
+ */
+export declare function runAddContractCommand({ contractName, cwd, typeName, }: RunAddContractCommandOptions): Promise<{
+    contractSlug: string;
+    projectDir: string;
+    schemaFile: string;
+    sourceTypeName: string;
+    typesFile: string;
+}>;

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

@@ -0,0 +1,65 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { pathExists } from "./fs-async.js";
+import { assertContractDoesNotExist, assertValidGeneratedSlug, assertValidTypeScriptIdentifier, normalizeBlockSlug, } from "./cli-add-shared.js";
+import { executeWorkspaceMutationPlan } from "./cli-add-workspace-mutation.js";
+import { ensureContractSyncScriptAnchors } from "./cli-add-workspace-rest-anchors.js";
+import { buildContractConfigEntry, buildContractTypesSource, } from "./cli-add-workspace-contract-source-emitters.js";
+import { syncStandaloneContractArtifacts } from "./contract-artifacts.js";
+import { toPascalCase } from "./string-case.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
+import { resolveWorkspaceProject } from "./workspace-project.js";
+const ADD_CONTRACT_USAGE = "wp-typia add contract <name> [--type <ExportedTypeName>]";
+/**
+ * Scaffold a standalone TypeScript wire contract and synchronize its JSON
+ * Schema artifact without generating PHP route glue.
+ *
+ * @param options Command options for the standalone contract workflow.
+ * @returns Resolved scaffold metadata for the created contract.
+ */
+export async function runAddContractCommand({ contractName, cwd = process.cwd(), typeName, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const contractSlug = assertValidGeneratedSlug("Contract name", normalizeBlockSlug(contractName), ADD_CONTRACT_USAGE);
+    const sourceTypeName = assertValidTypeScriptIdentifier("Contract type", typeName ?? toPascalCase(contractSlug), ADD_CONTRACT_USAGE);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
+    assertContractDoesNotExist(workspace.projectDir, contractSlug, inventory);
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
+    const contractDir = path.join(workspace.projectDir, "src", "contracts");
+    const typesFile = `src/contracts/${contractSlug}.ts`;
+    const schemaFile = `src/contracts/${contractSlug}.schema.json`;
+    const typesFilePath = path.join(workspace.projectDir, typesFile);
+    const schemaFilePath = path.join(workspace.projectDir, schemaFile);
+    const contractDirExisted = await pathExists(contractDir);
+    return executeWorkspaceMutationPlan({
+        filePaths: [blockConfigPath, syncRestScriptPath],
+        targetPaths: [
+            typesFilePath,
+            schemaFilePath,
+            ...(contractDirExisted ? [] : [contractDir]),
+        ],
+        run: async () => {
+            await fsp.mkdir(contractDir, { recursive: true });
+            await ensureContractSyncScriptAnchors(workspace);
+            await fsp.writeFile(typesFilePath, buildContractTypesSource(contractSlug, sourceTypeName), "utf8");
+            await syncStandaloneContractArtifacts({
+                projectDir: workspace.projectDir,
+                schemaFile,
+                sourceTypeName,
+                typesFile,
+            });
+            await appendWorkspaceInventoryEntries(workspace.projectDir, {
+                contractEntries: [
+                    buildContractConfigEntry(contractSlug, sourceTypeName),
+                ],
+            });
+            return {
+                contractSlug,
+                projectDir: workspace.projectDir,
+                schemaFile,
+                sourceTypeName,
+                typesFile,
+            };
+        },
+    });
+}

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

@@ -0,0 +1,24 @@
+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 withWpEnv Whether the generated scaffold included the wp-env preset.
+ */
+export interface RunAddIntegrationEnvCommandResult {
+    integrationEnvSlug: string;
+    projectDir: string;
+    service: IntegrationEnvServiceId;
+    warnings?: string[];
+    withWpEnv: boolean;
+}
+/**
+ * Add an opt-in local WordPress integration environment starter to an official
+ * workspace.
+ */
+export declare function runAddIntegrationEnvCommand({ cwd, integrationEnvName, service, withWpEnv, }: RunAddIntegrationEnvCommandOptions): Promise<RunAddIntegrationEnvCommandResult>;

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

@@ -0,0 +1,391 @@
+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 { executeWorkspaceMutationPlan } from "./cli-add-workspace-mutation.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, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const integrationEnvSlug = assertValidGeneratedSlug("Integration environment name", normalizeBlockSlug(integrationEnvName), "wp-typia add integration-env <name> [--wp-env]");
+    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,
+                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 mutatePackageJson(workspace.projectDir, (packageJson) => addIntegrationEnvPackageJsonEntries({
+                integrationEnvSlug,
+                packageManager: workspace.packageManager,
+                packageJson,
+                service: serviceId,
+                warnings,
+                withWpEnv,
+            }));
+        },
+    });
+    return {
+        integrationEnvSlug,
+        projectDir: workspace.projectDir,
+        service: serviceId,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        withWpEnv,
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Ensure the workspace bootstrap loads generated post-meta PHP modules.
+ *
+ * Inserts the generated loader function, appends its `init` hook, and rejects
+ * incompatible existing loader functions that omit the generated post-meta glob.
+ *
+ * @param workspace Resolved official workspace metadata and paths.
+ * @returns A promise that resolves after the bootstrap has been patched.
+ * @throws {Error} When the bootstrap cannot be read, written, or safely patched.
+ */
+export declare function ensurePostMetaBootstrapAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensure `scripts/sync-rest-contracts.ts` handles post-meta schema contracts.
+ *
+ * Patches inventory imports, type guards, no-resource checks, sync loops, and
+ * success copy so generated post-meta schemas participate in REST contract sync.
+ *
+ * @param workspace Resolved official workspace metadata and paths.
+ * @returns A promise that resolves after the sync script has been patched.
+ * @throws {Error} When expected anchors are missing or file IO fails.
+ */
+export declare function ensurePostMetaSyncScriptAnchors(workspace: WorkspaceProject): Promise<void>;