@wp-typia/project-tools 0.16.6 → 0.16.7

package/dist/runtime/cli-add-shared.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_IDS, } from "./hooked-blocks.js";
+import { toKebabCase, toSnakeCase, } from "./string-case.js";
+import { WORKSPACE_TEMPLATE_PACKAGE, } from "./workspace-project.js";
+/**
+ * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
+ */
+export const ADD_KIND_IDS = ["block", "variation", "pattern", "binding-source", "hooked-block"];
+/**
+ * Supported built-in block families accepted by `wp-typia add block --template`.
+ */
+export const ADD_BLOCK_TEMPLATE_IDS = [
+    "basic",
+    "interactivity",
+    "persistence",
+    "compound",
+];
+const WORKSPACE_GENERATED_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+export function normalizeBlockSlug(input) {
+    return toKebabCase(input);
+}
+export function assertValidGeneratedSlug(label, slug, usage) {
+    if (!slug) {
+        throw new Error(`${label} is required. Use \`${usage}\`.`);
+    }
+    if (!WORKSPACE_GENERATED_SLUG_PATTERN.test(slug)) {
+        throw new Error(`${label} must start with a letter and contain only lowercase letters, numbers, and hyphens.`);
+    }
+    return slug;
+}
+export function assertValidHookedBlockPosition(position) {
+    if (HOOKED_BLOCK_POSITION_IDS.includes(position)) {
+        return position;
+    }
+    throw new Error(`Hook position must be one of: ${HOOKED_BLOCK_POSITION_IDS.join(", ")}.`);
+}
+export function getWorkspaceBootstrapPath(workspace) {
+    const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
+    return path.join(workspace.projectDir, `${workspaceBaseName}.php`);
+}
+export function buildWorkspacePhpPrefix(workspacePhpPrefix, slug) {
+    return toSnakeCase(`${workspacePhpPrefix}_${slug}`);
+}
+export function isAddBlockTemplateId(value) {
+    return ADD_BLOCK_TEMPLATE_IDS.includes(value);
+}
+export function quoteTsString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Apply a text transform to an existing file only when the contents change.
+ */
+export async function patchFile(filePath, transform) {
+    const currentSource = await fsp.readFile(filePath, "utf8");
+    const nextSource = transform(currentSource);
+    if (nextSource !== currentSource) {
+        await fsp.writeFile(filePath, nextSource, "utf8");
+    }
+}
+/**
+ * Read a file when it exists and otherwise return `null`.
+ */
+export async function readOptionalFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return fsp.readFile(filePath, "utf8");
+}
+/**
+ * Restore a file to its captured source, deleting it when the snapshot was `null`.
+ */
+export async function restoreOptionalFile(filePath, source) {
+    if (source === null) {
+        await fsp.rm(filePath, { force: true });
+        return;
+    }
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    await fsp.writeFile(filePath, source, "utf8");
+}
+/**
+ * Capture the current contents of a set of workspace files for rollback.
+ */
+export async function snapshotWorkspaceFiles(filePaths) {
+    const uniquePaths = Array.from(new Set(filePaths));
+    return Promise.all(uniquePaths.map(async (filePath) => ({
+        filePath,
+        source: await readOptionalFile(filePath),
+    })));
+}
+/**
+ * Undo a partially applied workspace mutation from a captured snapshot.
+ */
+export async function rollbackWorkspaceMutation(snapshot) {
+    for (const targetPath of snapshot.targetPaths) {
+        await fsp.rm(targetPath, { force: true, recursive: true });
+    }
+    for (const snapshotDir of snapshot.snapshotDirs) {
+        await fsp.rm(snapshotDir, { force: true, recursive: true });
+    }
+    for (const { filePath, source } of snapshot.fileSources) {
+        await restoreOptionalFile(filePath, source);
+    }
+}
+export function resolveWorkspaceBlock(inventory, blockSlug) {
+    const block = inventory.blocks.find((entry) => entry.slug === blockSlug);
+    if (!block) {
+        throw new Error(`Unknown workspace block "${blockSlug}". Choose one of: ${inventory.blocks.map((entry) => entry.slug).join(", ")}`);
+    }
+    return block;
+}
+export function assertValidHookAnchor(anchorBlockName) {
+    const trimmed = anchorBlockName.trim();
+    if (!trimmed) {
+        throw new Error("`wp-typia add hooked-block` requires --anchor <anchor-block-name>.");
+    }
+    if (!HOOKED_BLOCK_ANCHOR_PATTERN.test(trimmed)) {
+        throw new Error("`wp-typia add hooked-block` requires --anchor <anchor-block-name> to use the full `namespace/slug` block name format.");
+    }
+    return trimmed;
+}
+export function readWorkspaceBlockJson(projectDir, blockSlug) {
+    const blockJsonPath = path.join(projectDir, "src", "blocks", blockSlug, "block.json");
+    if (!fs.existsSync(blockJsonPath)) {
+        throw new Error(`Missing ${path.relative(projectDir, blockJsonPath)} for workspace block "${blockSlug}".`);
+    }
+    let blockJson;
+    try {
+        blockJson = JSON.parse(fs.readFileSync(blockJsonPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error
+            ? `Failed to parse ${path.relative(projectDir, blockJsonPath)}: ${error.message}`
+            : `Failed to parse ${path.relative(projectDir, blockJsonPath)}.`);
+    }
+    if (!blockJson || typeof blockJson !== "object" || Array.isArray(blockJson)) {
+        throw new Error(`${path.relative(projectDir, blockJsonPath)} must contain a JSON object.`);
+    }
+    return {
+        blockJson: blockJson,
+        blockJsonPath,
+    };
+}
+export function getMutableBlockHooks(blockJson, blockJsonRelativePath) {
+    const blockHooks = blockJson.blockHooks;
+    if (blockHooks === undefined) {
+        const nextHooks = {};
+        blockJson.blockHooks = nextHooks;
+        return nextHooks;
+    }
+    if (!blockHooks || typeof blockHooks !== "object" || Array.isArray(blockHooks)) {
+        throw new Error(`${blockJsonRelativePath} must define blockHooks as an object when present.`);
+    }
+    return blockHooks;
+}
+export function assertVariationDoesNotExist(projectDir, blockSlug, variationSlug, inventory) {
+    const variationPath = path.join(projectDir, "src", "blocks", blockSlug, "variations", `${variationSlug}.ts`);
+    if (fs.existsSync(variationPath)) {
+        throw new Error(`A variation already exists at ${path.relative(projectDir, variationPath)}. Choose a different name.`);
+    }
+    if (inventory.variations.some((entry) => entry.block === blockSlug && entry.slug === variationSlug)) {
+        throw new Error(`A variation inventory entry already exists for ${blockSlug}/${variationSlug}. Choose a different name.`);
+    }
+}
+export function assertPatternDoesNotExist(projectDir, patternSlug, inventory) {
+    const patternPath = path.join(projectDir, "src", "patterns", `${patternSlug}.php`);
+    if (fs.existsSync(patternPath)) {
+        throw new Error(`A pattern already exists at ${path.relative(projectDir, patternPath)}. Choose a different name.`);
+    }
+    if (inventory.patterns.some((entry) => entry.slug === patternSlug)) {
+        throw new Error(`A pattern inventory entry already exists for ${patternSlug}. Choose a different name.`);
+    }
+}
+export function assertBindingSourceDoesNotExist(projectDir, bindingSourceSlug, inventory) {
+    const bindingSourceDir = path.join(projectDir, "src", "bindings", bindingSourceSlug);
+    if (fs.existsSync(bindingSourceDir)) {
+        throw new Error(`A binding source already exists at ${path.relative(projectDir, bindingSourceDir)}. Choose a different name.`);
+    }
+    if (inventory.bindingSources.some((entry) => entry.slug === bindingSourceSlug)) {
+        throw new Error(`A binding source inventory entry already exists for ${bindingSourceSlug}. Choose a different name.`);
+    }
+}
+/**
+ * Returns help text for the canonical `wp-typia add` subcommands.
+ */
+export function formatAddHelpText() {
+    return `Usage:
+  wp-typia add block <name> --template <${ADD_BLOCK_TEMPLATE_IDS.join("|")}> [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
+  wp-typia add variation <name> --block <block-slug>
+  wp-typia add pattern <name>
+  wp-typia add binding-source <name>
+  wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <${HOOKED_BLOCK_POSITION_IDS.join("|")}>
+
+Notes:
+  \`wp-typia add\` runs only inside official ${WORKSPACE_TEMPLATE_PACKAGE} workspaces.
+  \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
+  \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.
+  \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.`;
+}

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

@@ -0,0 +1,81 @@
+import type { HookedBlockPositionId } from "./hooked-blocks.js";
+import { type RunAddBindingSourceCommandOptions, type RunAddHookedBlockCommandOptions, type RunAddPatternCommandOptions, type RunAddVariationCommandOptions } from "./cli-add-shared.js";
+/**
+ * Add one variation entry to an existing workspace block.
+ *
+ * @param options Command options for the variation scaffold workflow.
+ * @param options.blockName Target workspace block slug that will own the variation.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.variationName Human-entered variation name that will be normalized
+ * and validated before files are written.
+ * @returns A promise that resolves with the normalized `blockSlug`,
+ * `variationSlug`, and owning `projectDir` after the variation files and
+ * inventory entry have been written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the target block is unknown, when the variation slug is invalid, or when a
+ * conflicting file or inventory entry already exists.
+ */
+export declare function runAddVariationCommand({ blockName, cwd, variationName, }: RunAddVariationCommandOptions): Promise<{
+    blockSlug: string;
+    projectDir: string;
+    variationSlug: string;
+}>;
+/**
+ * Add one PHP block pattern shell to an official workspace project.
+ *
+ * @param options Command options for the pattern scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.patternName Human-entered pattern name that will be normalized
+ * and validated before files are written.
+ * @returns A promise that resolves with the normalized `patternSlug` and
+ * owning `projectDir` after the pattern file and inventory entry have been
+ * written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the pattern slug is invalid, or when a conflicting file or inventory entry
+ * already exists.
+ */
+export declare function runAddPatternCommand({ cwd, patternName, }: RunAddPatternCommandOptions): Promise<{
+    patternSlug: string;
+    projectDir: string;
+}>;
+/**
+ * Add one block binding source scaffold to an official workspace project.
+ *
+ * @param options Command options for the binding-source scaffold workflow.
+ * @param options.bindingSourceName Human-entered binding source name that will
+ * be normalized and validated before files are written.
+ * @param options.cwd Working directory used to resolve the nearest official
+ * workspace. Defaults to `process.cwd()`.
+ * @returns A promise that resolves with the normalized `bindingSourceSlug` and
+ * owning `projectDir` after the server/editor files and inventory entry have
+ * been written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the slug is invalid, or when a conflicting file or inventory entry exists.
+ */
+export declare function runAddBindingSourceCommand({ bindingSourceName, cwd, }: RunAddBindingSourceCommandOptions): Promise<{
+    bindingSourceSlug: string;
+    projectDir: string;
+}>;
+/**
+ * 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;
+}>;