@wp-typia/project-tools 0.24.4 → 0.24.5

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

@@ -0,0 +1,47 @@
+/**
+ * Render one `scripts/block-config.ts` editor-plugin inventory entry.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param slot Canonical editor-plugin slot id.
+ * @returns TypeScript source for the inventory entry.
+ */
+export declare function buildEditorPluginConfigEntry(editorPluginSlug: string, slot: string): string;
+/**
+ * Render the generated editor-plugin model type module.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @returns TypeScript source for the plugin model type.
+ */
+export declare function buildEditorPluginTypesSource(editorPluginSlug: string): string;
+/**
+ * Render the generated editor-plugin data module.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param slot Canonical editor-plugin slot id.
+ * @returns TypeScript source for default plugin data helpers.
+ */
+export declare function buildEditorPluginDataSource(editorPluginSlug: string, slot: string): string;
+/**
+ * Render the React surface for a generated editor plugin.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param slot Canonical editor-plugin slot id.
+ * @param textDomain Workspace text domain used for translatable UI strings.
+ * @returns TSX source for the generated plugin surface.
+ */
+export declare function buildEditorPluginSurfaceSource(editorPluginSlug: string, slot: string, textDomain: string): string;
+/**
+ * Render the generated editor-plugin entry module.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param namespace Workspace block namespace.
+ * @param textDomain Workspace text domain used for translatable UI strings.
+ * @returns TSX source for registering the editor plugin.
+ */
+export declare function buildEditorPluginEntrySource(editorPluginSlug: string, namespace: string, textDomain: string): string;
+/**
+ * Render the generated editor-plugin stylesheet.
+ *
+ * @returns SCSS source for the generated editor plugin shell.
+ */
+export declare function buildEditorPluginStyleSource(): string;

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

@@ -0,0 +1,219 @@
+import { quoteTsString } from "./cli-add-shared.js";
+import { toPascalCase, toTitleCase } from "../shared/string-case.js";
+/**
+ * Render one `scripts/block-config.ts` editor-plugin inventory entry.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param slot Canonical editor-plugin slot id.
+ * @returns TypeScript source for the inventory entry.
+ */
+export function buildEditorPluginConfigEntry(editorPluginSlug, slot) {
+    return [
+        "\t{",
+        `\t\tfile: ${quoteTsString(`src/editor-plugins/${editorPluginSlug}/index.tsx`)},`,
+        `\t\tslug: ${quoteTsString(editorPluginSlug)},`,
+        `\t\tslot: ${quoteTsString(slot)},`,
+        "\t},",
+    ].join("\n");
+}
+/**
+ * Render the generated editor-plugin model type module.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @returns TypeScript source for the plugin model type.
+ */
+export function buildEditorPluginTypesSource(editorPluginSlug) {
+    const typeName = `${toPascalCase(editorPluginSlug)}EditorPluginModel`;
+    return `export interface ${typeName} {
+\tprimaryActionLabel: string;
+\tsummary: string;
+}
+`;
+}
+/**
+ * Render the generated editor-plugin data module.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param slot Canonical editor-plugin slot id.
+ * @returns TypeScript source for default plugin data helpers.
+ */
+export function buildEditorPluginDataSource(editorPluginSlug, slot) {
+    const typeName = `${toPascalCase(editorPluginSlug)}EditorPluginModel`;
+    const pluginTitle = toTitleCase(editorPluginSlug);
+    const modelFactoryName = `get${toPascalCase(editorPluginSlug)}EditorPluginModel`;
+    const enabledFactoryName = `is${toPascalCase(editorPluginSlug)}Enabled`;
+    return `import type { ${typeName} } from './types';
+
+export const EDITOR_PLUGIN_SLOT = ${quoteTsString(slot)} as const;
+export const REQUIRED_CAPABILITY = 'edit_posts' as const;
+
+const DEFAULT_EDITOR_PLUGIN_MODEL: ${typeName} = {
+\tprimaryActionLabel: ${quoteTsString(`Review ${pluginTitle}`)},
+\tsummary: ${quoteTsString(`Replace this summary with your ${pluginTitle} workflow state.`)},
+};
+
+export function ${modelFactoryName}(): ${typeName} {
+\treturn DEFAULT_EDITOR_PLUGIN_MODEL;
+}
+
+export function ${enabledFactoryName}(): boolean {
+\treturn true;
+}
+`;
+}
+/**
+ * Render the React surface for a generated editor plugin.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param slot Canonical editor-plugin slot id.
+ * @param textDomain Workspace text domain used for translatable UI strings.
+ * @returns TSX source for the generated plugin surface.
+ */
+export function buildEditorPluginSurfaceSource(editorPluginSlug, slot, textDomain) {
+    const pascalName = toPascalCase(editorPluginSlug);
+    const modelFactoryName = `get${pascalName}EditorPluginModel`;
+    const enabledFactoryName = `is${pascalName}Enabled`;
+    const componentName = `${pascalName}Surface`;
+    if (slot === "document-setting-panel") {
+        return `import { Button } from '@wordpress/components';
+import { PluginDocumentSettingPanel } from '@wordpress/editor';
+import { __ } from '@wordpress/i18n';
+
+import { ${modelFactoryName}, ${enabledFactoryName} } from './data';
+import './style.scss';
+
+export interface ${componentName}Props {
+\tsurfaceName: string;
+\ttitle: string;
+}
+
+export function ${componentName}( {
+\tsurfaceName,
+\ttitle,
+}: ${componentName}Props ) {
+\tif ( ! ${enabledFactoryName}() ) {
+\t\treturn null;
+\t}
+
+\tconst editorPluginModel = ${modelFactoryName}();
+
+\treturn (
+\t\t<PluginDocumentSettingPanel
+\t\t\tclassName="wp-typia-editor-plugin-shell"
+\t\t\tname={ surfaceName }
+\t\t\ttitle={ title }
+\t\t>
+\t\t\t<p>{ editorPluginModel.summary }</p>
+\t\t\t<Button variant="secondary">
+\t\t\t\t{ editorPluginModel.primaryActionLabel }
+\t\t\t</Button>
+\t\t\t<p className="wp-typia-editor-plugin-shell__hint">
+\t\t\t\t{ __( 'Use data.ts to add post type, capability, or editor context guards before showing this panel.', ${quoteTsString(textDomain)} ) }
+\t\t\t</p>
+\t\t</PluginDocumentSettingPanel>
+\t);
+}
+`;
+    }
+    return `import { Button, PanelBody } from '@wordpress/components';
+import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/editor';
+import { __ } from '@wordpress/i18n';
+
+import { ${modelFactoryName}, ${enabledFactoryName} } from './data';
+import './style.scss';
+
+export interface ${componentName}Props {
+\tsurfaceName: string;
+\ttitle: string;
+}
+
+export function ${componentName}( {
+\tsurfaceName,
+\ttitle,
+}: ${componentName}Props ) {
+\tif ( ! ${enabledFactoryName}() ) {
+\t\treturn null;
+\t}
+
+\tconst editorPluginModel = ${modelFactoryName}();
+
+\treturn (
+\t\t<>
+\t\t\t<PluginSidebarMoreMenuItem target={ surfaceName }>
+\t\t\t\t{ title }
+\t\t\t</PluginSidebarMoreMenuItem>
+\t\t\t<PluginSidebar name={ surfaceName } title={ title }>
+\t\t\t\t<div className="wp-typia-editor-plugin-shell">
+\t\t\t\t\t<PanelBody
+\t\t\t\t\t\tinitialOpen
+\t\t\t\t\t\ttitle={ __( 'Document workflow', ${quoteTsString(textDomain)} ) }
+\t\t\t\t\t>
+\t\t\t\t\t\t<p>{ editorPluginModel.summary }</p>
+\t\t\t\t\t\t<Button variant="secondary">
+\t\t\t\t\t\t\t{ editorPluginModel.primaryActionLabel }
+\t\t\t\t\t\t</Button>
+\t\t\t\t\t</PanelBody>
+\t\t\t\t</div>
+\t\t\t</PluginSidebar>
+\t\t</>
+\t);
+}
+`;
+}
+/**
+ * Render the generated editor-plugin entry module.
+ *
+ * @param editorPluginSlug Normalized editor-plugin slug.
+ * @param namespace Workspace block namespace.
+ * @param textDomain Workspace text domain used for translatable UI strings.
+ * @returns TSX source for registering the editor plugin.
+ */
+export function buildEditorPluginEntrySource(editorPluginSlug, namespace, textDomain) {
+    const pascalName = toPascalCase(editorPluginSlug);
+    const componentName = `${pascalName}Surface`;
+    const pluginName = `${namespace}-${editorPluginSlug}`;
+    const surfaceName = `${pluginName}-surface`;
+    const pluginTitle = toTitleCase(editorPluginSlug);
+    return `import { registerPlugin } from '@wordpress/plugins';
+import { __ } from '@wordpress/i18n';
+
+import { REQUIRED_CAPABILITY } from './data';
+import { ${componentName} } from './Surface';
+
+const EDITOR_PLUGIN_NAME = ${quoteTsString(pluginName)};
+const EDITOR_PLUGIN_SURFACE_NAME = ${quoteTsString(surfaceName)};
+const EDITOR_PLUGIN_TITLE = __( ${quoteTsString(pluginTitle)}, ${quoteTsString(textDomain)} );
+
+registerPlugin( EDITOR_PLUGIN_NAME, {
+\ticon: 'admin-generic',
+\trender: () => (
+\t\t<${componentName}
+\t\t\tsurfaceName={ EDITOR_PLUGIN_SURFACE_NAME }
+\t\t\ttitle={ EDITOR_PLUGIN_TITLE }
+\t\t/>
+\t),
+} );
+
+export { REQUIRED_CAPABILITY };
+`;
+}
+/**
+ * Render the generated editor-plugin stylesheet.
+ *
+ * @returns SCSS source for the generated editor plugin shell.
+ */
+export function buildEditorPluginStyleSource() {
+    return `.wp-typia-editor-plugin-shell {
+\tpadding: 16px;
+}
+
+.wp-typia-editor-plugin-shell p {
+\tmargin: 0 0 12px;
+}
+
+.wp-typia-editor-plugin-shell__hint {
+\tcolor: #757575;
+\tfont-size: 12px;
+}
+`;
+}

package/dist/runtime/add/cli-add-workspace-editor-plugin.d.ts

@@ -0,0 +1,22 @@
+import { type RunAddEditorPluginCommandOptions } from "./cli-add-shared.js";
+export { ensureEditorPluginBootstrapAnchors, ensureEditorPluginBuildScriptAnchors, ensureEditorPluginWebpackAnchors, resolveEditorPluginRegistryPath, writeEditorPluginRegistry, } from "./cli-add-workspace-editor-plugin-anchors.js";
+/**
+ * Add one document-level editor plugin scaffold to an official workspace project.
+ *
+ * @param options Command options for the editor-plugin scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.editorPluginName Human-entered editor-plugin name that will be
+ * normalized and validated before files are written.
+ * @param options.slot Optional editor plugin shell slot. Defaults to `sidebar`.
+ * @returns A promise that resolves with the normalized `editorPluginSlug`, chosen
+ * `slot`, and owning `projectDir` after the scaffold files and inventory entry
+ * are written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when the
+ * slug or slot is invalid, or when a conflicting file or inventory entry exists.
+ */
+export declare function runAddEditorPluginCommand({ cwd, editorPluginName, slot, }: RunAddEditorPluginCommandOptions): Promise<{
+    editorPluginSlug: string;
+    projectDir: string;
+    slot: string;
+}>;

package/dist/runtime/add/cli-add-workspace-editor-plugin.js

@@ -0,0 +1,78 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { assertEditorPluginDoesNotExist, assertValidEditorPluginSlot, assertValidGeneratedSlug, getWorkspaceBootstrapPath, normalizeBlockSlug, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureEditorPluginBootstrapAnchors, ensureEditorPluginBuildScriptAnchors, ensureEditorPluginWebpackAnchors, resolveEditorPluginRegistryPath, writeEditorPluginRegistry, } from "./cli-add-workspace-editor-plugin-anchors.js";
+import { buildEditorPluginConfigEntry, buildEditorPluginDataSource, buildEditorPluginEntrySource, buildEditorPluginStyleSource, buildEditorPluginSurfaceSource, buildEditorPluginTypesSource, } from "./cli-add-workspace-editor-plugin-source-emitters.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "../workspace/workspace-inventory.js";
+import { resolveWorkspaceProject } from "../workspace/workspace-project.js";
+export { ensureEditorPluginBootstrapAnchors, ensureEditorPluginBuildScriptAnchors, ensureEditorPluginWebpackAnchors, resolveEditorPluginRegistryPath, writeEditorPluginRegistry, } from "./cli-add-workspace-editor-plugin-anchors.js";
+/**
+ * Add one document-level editor plugin scaffold to an official workspace project.
+ *
+ * @param options Command options for the editor-plugin scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.editorPluginName Human-entered editor-plugin name that will be
+ * normalized and validated before files are written.
+ * @param options.slot Optional editor plugin shell slot. Defaults to `sidebar`.
+ * @returns A promise that resolves with the normalized `editorPluginSlug`, chosen
+ * `slot`, and owning `projectDir` after the scaffold files and inventory entry
+ * are written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when the
+ * slug or slot is invalid, or when a conflicting file or inventory entry exists.
+ */
+export async function runAddEditorPluginCommand({ cwd = process.cwd(), editorPluginName, slot, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const editorPluginSlug = assertValidGeneratedSlug("Editor plugin name", normalizeBlockSlug(editorPluginName), "wp-typia add editor-plugin <name> [--slot <sidebar|document-setting-panel>]");
+    const resolvedSlot = assertValidEditorPluginSlot(slot);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
+    assertEditorPluginDoesNotExist(workspace.projectDir, editorPluginSlug, inventory);
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    const buildScriptPath = path.join(workspace.projectDir, "scripts", "build-workspace.mjs");
+    const editorPluginsIndexPath = await resolveEditorPluginRegistryPath(workspace.projectDir);
+    const webpackConfigPath = path.join(workspace.projectDir, "webpack.config.js");
+    const editorPluginDir = path.join(workspace.projectDir, "src", "editor-plugins", editorPluginSlug);
+    const entryFilePath = path.join(editorPluginDir, "index.tsx");
+    const surfaceFilePath = path.join(editorPluginDir, "Surface.tsx");
+    const dataFilePath = path.join(editorPluginDir, "data.ts");
+    const typesFilePath = path.join(editorPluginDir, "types.ts");
+    const styleFilePath = path.join(editorPluginDir, "style.scss");
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            bootstrapPath,
+            buildScriptPath,
+            editorPluginsIndexPath,
+            webpackConfigPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [editorPluginDir],
+    };
+    try {
+        await fsp.mkdir(editorPluginDir, { recursive: true });
+        await ensureEditorPluginBootstrapAnchors(workspace);
+        await ensureEditorPluginBuildScriptAnchors(workspace);
+        await ensureEditorPluginWebpackAnchors(workspace);
+        await fsp.writeFile(entryFilePath, buildEditorPluginEntrySource(editorPluginSlug, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
+        await fsp.writeFile(surfaceFilePath, buildEditorPluginSurfaceSource(editorPluginSlug, resolvedSlot, workspace.workspace.textDomain), "utf8");
+        await fsp.writeFile(dataFilePath, buildEditorPluginDataSource(editorPluginSlug, resolvedSlot), "utf8");
+        await fsp.writeFile(typesFilePath, buildEditorPluginTypesSource(editorPluginSlug), "utf8");
+        await fsp.writeFile(styleFilePath, buildEditorPluginStyleSource(), "utf8");
+        await writeEditorPluginRegistry(workspace.projectDir, editorPluginSlug);
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            editorPluginEntries: [
+                buildEditorPluginConfigEntry(editorPluginSlug, resolvedSlot),
+            ],
+        });
+        return {
+            editorPluginSlug,
+            projectDir: workspace.projectDir,
+            slot: resolvedSlot,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

package/dist/runtime/add/cli-add-workspace-hooked-block.d.ts

@@ -0,0 +1,23 @@
+import type { HookedBlockPositionId } from "./hooked-blocks.js";
+import { type RunAddHookedBlockCommandOptions } from "./cli-add-shared.js";
+/**
+ * Add one `blockHooks` entry to an existing official workspace block.
+ *
+ * @param options Command options for the hooked-block workflow.
+ * @param options.anchorBlockName Full block name that will anchor the insertion.
+ * @param options.blockName Existing workspace block slug to patch.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.position Hook position to store in `block.json`.
+ * @returns A promise that resolves with the normalized target block slug, anchor
+ * block name, position, and owning project directory after `block.json` is written.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the target block is unknown, when required flags are missing, or when the
+ * block already defines a hook for the requested anchor.
+ */
+export declare function runAddHookedBlockCommand({ anchorBlockName, blockName, cwd, position, }: RunAddHookedBlockCommandOptions): Promise<{
+    anchorBlockName: string;
+    blockSlug: string;
+    position: HookedBlockPositionId;
+    projectDir: string;
+}>;

package/dist/runtime/add/cli-add-workspace-hooked-block.js

@@ -0,0 +1,57 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { assertValidHookAnchor, assertValidHookedBlockPosition, getMutableBlockHooks, normalizeBlockSlug, readWorkspaceBlockJson, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { readWorkspaceInventoryAsync } from "../workspace/workspace-inventory.js";
+import { resolveWorkspaceProject } from "../workspace/workspace-project.js";
+/**
+ * Add one `blockHooks` entry to an existing official workspace block.
+ *
+ * @param options Command options for the hooked-block workflow.
+ * @param options.anchorBlockName Full block name that will anchor the insertion.
+ * @param options.blockName Existing workspace block slug to patch.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.position Hook position to store in `block.json`.
+ * @returns A promise that resolves with the normalized target block slug, anchor
+ * block name, position, and owning project directory after `block.json` is written.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the target block is unknown, when required flags are missing, or when the
+ * block already defines a hook for the requested anchor.
+ */
+export async function runAddHookedBlockCommand({ anchorBlockName, blockName, cwd = process.cwd(), position, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const blockSlug = normalizeBlockSlug(blockName);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
+    resolveWorkspaceBlock(inventory, blockSlug);
+    const resolvedAnchorBlockName = assertValidHookAnchor(anchorBlockName);
+    const resolvedPosition = assertValidHookedBlockPosition(position);
+    const selfHookAnchor = `${workspace.workspace.namespace}/${blockSlug}`;
+    if (resolvedAnchorBlockName === selfHookAnchor) {
+        throw new Error("`wp-typia add hooked-block` cannot hook a block relative to its own block name.");
+    }
+    const { blockJson, blockJsonPath } = await readWorkspaceBlockJson(workspace.projectDir, blockSlug);
+    const blockJsonRelativePath = path.relative(workspace.projectDir, blockJsonPath);
+    const blockHooks = getMutableBlockHooks(blockJson, blockJsonRelativePath);
+    if (Object.prototype.hasOwnProperty.call(blockHooks, resolvedAnchorBlockName)) {
+        throw new Error(`${blockJsonRelativePath} already defines a blockHooks entry for "${resolvedAnchorBlockName}".`);
+    }
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([blockJsonPath]),
+        snapshotDirs: [],
+        targetPaths: [],
+    };
+    try {
+        blockHooks[resolvedAnchorBlockName] = resolvedPosition;
+        await fsp.writeFile(blockJsonPath, JSON.stringify(blockJson, null, "\t"), "utf8");
+        return {
+            anchorBlockName: resolvedAnchorBlockName,
+            blockSlug,
+            position: resolvedPosition,
+            projectDir: workspace.projectDir,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

package/dist/runtime/add/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/add/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 "../shared/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/add/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 "../shared/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 {};