@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -0,0 +1,33 @@
+/**
+ * Append only missing lines to an existing text file, preserving any existing
+ * user-managed content.
+ *
+ * @param filePath Absolute file path to append.
+ * @param lines Lines that should be present in the file.
+ * @returns A promise that resolves after the file is created or updated.
+ */
+export declare function appendMissingLines(filePath: string, lines: readonly string[]): Promise<void>;
+/**
+ * Write a generated file only when it is absent, recording a preservation
+ * warning when the target already exists.
+ *
+ * @param options File write options.
+ * @param options.filePath Absolute target file path.
+ * @param options.source Generated source to write when absent.
+ * @param options.warnings Mutable warning collection for preserved files.
+ * @returns A promise that resolves after the file is written or preserved.
+ */
+export declare function writeFileIfAbsent({ filePath, source, warnings, }: {
+    filePath: string;
+    source: string;
+    warnings: string[];
+}): Promise<void>;
+/**
+ * Write a newly generated scaffold file and fail if the target already exists.
+ *
+ * @param filePath Absolute target file path.
+ * @param source Generated source to write.
+ * @returns A promise that resolves after the file is written.
+ * @throws {Error} When the scaffold target already exists.
+ */
+export declare function writeNewScaffoldFile(filePath: string, source: string): Promise<void>;

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

@@ -0,0 +1,65 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { readOptionalUtf8File } from "./fs-async.js";
+/**
+ * Append only missing lines to an existing text file, preserving any existing
+ * user-managed content.
+ *
+ * @param filePath Absolute file path to append.
+ * @param lines Lines that should be present in the file.
+ * @returns A promise that resolves after the file is created or updated.
+ */
+export async function appendMissingLines(filePath, lines) {
+    const current = (await readOptionalUtf8File(filePath)) ?? "";
+    const existingLines = new Set(current.split(/\r?\n/u));
+    const missingLines = lines.filter((line) => !existingLines.has(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");
+}
+/**
+ * Write a generated file only when it is absent, recording a preservation
+ * warning when the target already exists.
+ *
+ * @param options File write options.
+ * @param options.filePath Absolute target file path.
+ * @param options.source Generated source to write when absent.
+ * @param options.warnings Mutable warning collection for preserved files.
+ * @returns A promise that resolves after the file is written or preserved.
+ */
+export async function writeFileIfAbsent({ filePath, source, warnings, }) {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    try {
+        await fsp.writeFile(filePath, source, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            warnings.push(`Preserved existing ${path.basename(filePath)}; review it manually if you need different local integration settings.`);
+            return;
+        }
+        throw error;
+    }
+}
+/**
+ * Write a newly generated scaffold file and fail if the target already exists.
+ *
+ * @param filePath Absolute target file path.
+ * @param source Generated source to write.
+ * @returns A promise that resolves after the file is written.
+ * @throws {Error} When the scaffold target already exists.
+ */
+export async function writeNewScaffoldFile(filePath, source) {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    try {
+        await fsp.writeFile(filePath, source, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`An integration environment scaffold already exists at ${filePath}. Choose a different name.`);
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { IntegrationEnvServiceId } from "./cli-add-shared.js";
+import { type PackageManagerId } from "./package-managers.js";
+interface IntegrationEnvPackageJson {
+    devDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+}
+/**
+ * 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 declare function mutateIntegrationEnvPackageJson(projectDir: string, mutate: (packageJson: IntegrationEnvPackageJson) => void): Promise<void>;
+/**
+ * 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 declare function addIntegrationEnvPackageJsonEntries({ integrationEnvSlug, packageManager, packageJson, withReleaseZip, service, warnings, withWpEnv, }: {
+    integrationEnvSlug: string;
+    packageManager: PackageManagerId;
+    packageJson: IntegrationEnvPackageJson;
+    service: IntegrationEnvServiceId;
+    withReleaseZip: boolean;
+    warnings: string[];
+    withWpEnv: boolean;
+}): void;
+export {};

package/dist/runtime/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 "./json-utils.js";
+import { formatRunScript, } from "./package-managers.js";
+import { DEFAULT_WORDPRESS_ENV_VERSION } from "./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/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/cli-add-workspace-integration-env-source-emitters.js

@@ -0,0 +1,262 @@
+import { toTitleCase } from "./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/cli-add-workspace-integration-env.d.ts

@@ -8,6 +8,7 @@ import { type IntegrationEnvServiceId, type RunAddIntegrationEnvCommandOptions }
  * @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 {
@@ -15,10 +16,11 @@ export interface RunAddIntegrationEnvCommandResult {
     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, withWpEnv, }: RunAddIntegrationEnvCommandOptions): Promise<RunAddIntegrationEnvCommandResult>;
+export declare function runAddIntegrationEnvCommand({ cwd, integrationEnvName, service, withReleaseZip, withWpEnv, }: RunAddIntegrationEnvCommandOptions): Promise<RunAddIntegrationEnvCommandResult>;