@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -0,0 +1,42 @@
+import { type RunAddPatternCommandOptions } from "./cli-add-shared.js";
+import type { PatternCatalogScope } from "./pattern-catalog.js";
+/**
+ * Add one PHP block pattern shell to an official workspace project.
+ *
+ * @param options Command options for the pattern scaffold workflow.
+ * @param options.catalogTitle Optional human-readable title. Defaults to the
+ * title-cased form of the normalized pattern slug.
+ * @param options.contentFile Optional safe relative project path directly
+ * under `src/patterns/` or one nested directory under `src/patterns/` for the
+ * generated PHP file. Defaults to `src/patterns/full/<slug>.php` or
+ * `src/patterns/sections/<slug>.php`.
+ * @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.
+ * @param options.patternScope Catalog scope (`full` or `section`). Defaults to `full`.
+ * @param options.sectionRole Section role slug. Required only when
+ * `patternScope` is `section`.
+ * @param options.tags Optional pattern tags as a comma-separated string or
+ * array. Tags are normalized, deduplicated, and sorted.
+ * @param options.thumbnailUrl Optional thumbnail URL or relative asset path
+ * recorded in the inventory entry.
+ * @returns A promise that resolves with the normalized `patternSlug`, owning
+ * `projectDir`, resolved `contentFile`, `patternScope`, `tags`, `title`, and
+ * optional `sectionRole` and `thumbnailUrl` 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, scope, section-role coupling, tag values, or content file
+ * path are invalid, or when a conflicting target file or inventory entry
+ * already exists.
+ */
+export declare function runAddPatternCommand({ catalogTitle, contentFile, cwd, patternName, patternScope, sectionRole, tags, thumbnailUrl, }: RunAddPatternCommandOptions): Promise<{
+    contentFile: string;
+    patternSlug: string;
+    patternScope: PatternCatalogScope;
+    projectDir: string;
+    sectionRole?: string;
+    tags: string[];
+    title: string;
+    thumbnailUrl?: string;
+}>;

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

@@ -0,0 +1,99 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { assertPatternDoesNotExist, assertValidGeneratedSlug, getWorkspaceBootstrapPath, normalizeBlockSlug, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensurePatternBootstrapAnchors } from "./cli-add-workspace-pattern-anchors.js";
+import { resolvePatternCatalogOptions } from "./cli-add-workspace-pattern-options.js";
+import { buildPatternConfigEntry, buildPatternSource, } from "./cli-add-workspace-pattern-source-emitters.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
+import { resolveWorkspaceProject } from "./workspace-project.js";
+/**
+ * Add one PHP block pattern shell to an official workspace project.
+ *
+ * @param options Command options for the pattern scaffold workflow.
+ * @param options.catalogTitle Optional human-readable title. Defaults to the
+ * title-cased form of the normalized pattern slug.
+ * @param options.contentFile Optional safe relative project path directly
+ * under `src/patterns/` or one nested directory under `src/patterns/` for the
+ * generated PHP file. Defaults to `src/patterns/full/<slug>.php` or
+ * `src/patterns/sections/<slug>.php`.
+ * @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.
+ * @param options.patternScope Catalog scope (`full` or `section`). Defaults to `full`.
+ * @param options.sectionRole Section role slug. Required only when
+ * `patternScope` is `section`.
+ * @param options.tags Optional pattern tags as a comma-separated string or
+ * array. Tags are normalized, deduplicated, and sorted.
+ * @param options.thumbnailUrl Optional thumbnail URL or relative asset path
+ * recorded in the inventory entry.
+ * @returns A promise that resolves with the normalized `patternSlug`, owning
+ * `projectDir`, resolved `contentFile`, `patternScope`, `tags`, `title`, and
+ * optional `sectionRole` and `thumbnailUrl` 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, scope, section-role coupling, tag values, or content file
+ * path are invalid, or when a conflicting target file or inventory entry
+ * already exists.
+ */
+export async function runAddPatternCommand({ catalogTitle, contentFile, cwd = process.cwd(), patternName, patternScope, sectionRole, tags, thumbnailUrl, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const patternSlug = assertValidGeneratedSlug("Pattern name", normalizeBlockSlug(patternName), "wp-typia add pattern <name>");
+    const patternCatalogOptions = resolvePatternCatalogOptions(patternSlug, {
+        catalogTitle,
+        contentFile,
+        cwd,
+        patternName,
+        patternScope,
+        sectionRole,
+        tags,
+        thumbnailUrl,
+    });
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
+    assertPatternDoesNotExist(workspace.projectDir, patternSlug, inventory);
+    const contentFilePath = path.join(workspace.projectDir, patternCatalogOptions.contentFile);
+    if (await fsp.stat(contentFilePath).then(() => true, (error) => {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    })) {
+        throw new Error(`A pattern already exists at ${patternCatalogOptions.contentFile}. Choose a different name.`);
+    }
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    const patternFilePath = contentFilePath;
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([blockConfigPath, bootstrapPath]),
+        snapshotDirs: [],
+        targetPaths: [patternFilePath],
+    };
+    try {
+        await fsp.mkdir(path.dirname(patternFilePath), { recursive: true });
+        await ensurePatternBootstrapAnchors(workspace);
+        await fsp.writeFile(patternFilePath, buildPatternSource(patternSlug, workspace.workspace.namespace, patternCatalogOptions.sectionRole, workspace.workspace.textDomain, patternCatalogOptions.title), "utf8");
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            patternEntries: [
+                buildPatternConfigEntry(patternSlug, patternCatalogOptions),
+            ],
+        });
+        return {
+            contentFile: patternCatalogOptions.contentFile,
+            patternSlug,
+            patternScope: patternCatalogOptions.patternScope,
+            projectDir: workspace.projectDir,
+            ...(patternCatalogOptions.sectionRole
+                ? { sectionRole: patternCatalogOptions.sectionRole }
+                : {}),
+            tags: patternCatalogOptions.tags,
+            title: patternCatalogOptions.title,
+            ...(patternCatalogOptions.thumbnailUrl
+                ? { thumbnailUrl: patternCatalogOptions.thumbnailUrl }
+                : {}),
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

package/dist/runtime/cli-add-workspace-post-meta.js

@@ -2,7 +2,7 @@ import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { pathExists } from "./fs-async.js";
 import { assertPostMetaDoesNotExist, assertValidGeneratedSlug, assertValidPostMetaPostType, assertValidTypeScriptIdentifier, getWorkspaceBootstrapPath, normalizeBlockSlug, resolvePostMetaKey, } from "./cli-add-shared.js";
-import { ensureContractSyncScriptAnchors } from "./cli-add-workspace-rest-anchors.js";
+import { ensureContractSyncScriptAnchors, } from "./cli-add-workspace-rest-contract-sync-anchors.js";
 import { ensurePostMetaBootstrapAnchors, ensurePostMetaSyncScriptAnchors, } from "./cli-add-workspace-post-meta-anchors.js";
 import { buildPostMetaConfigEntry, buildPostMetaPhpSource, buildPostMetaReadmeSource, buildPostMetaTypesSource, } from "./cli-add-workspace-post-meta-source-emitters.js";
 import { executeWorkspaceMutationPlan } from "./cli-add-workspace-mutation.js";

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

@@ -0,0 +1,50 @@
+import { type SourceRange } from "./ts-source-masking.js";
+/**
+ * Find the first executable call expression for a named function in source code.
+ *
+ * @param source TypeScript or JavaScript source text to scan.
+ * @param callName Function identifier to locate.
+ * @returns The source range for the first matching executable call, or
+ * `undefined` when the identifier is absent, commented, string-literal-only, or
+ * not followed by a call expression.
+ */
+export declare function findExecutableCallRange(source: string, callName: string): SourceRange | undefined;
+/**
+ * Ensure a block entrypoint imports and calls a workspace registration helper.
+ *
+ * @param options Entrypoint patch options.
+ * @param options.blockIndexPath Absolute path to the block entrypoint file.
+ * @param options.callLine Call expression line to insert when missing.
+ * @param options.callPattern Executable pattern used to detect an existing call.
+ * @param options.importLine Import line to prepend when missing.
+ * @param options.importPattern Uncommented import pattern used to avoid duplicates.
+ * @returns A promise that resolves after the entrypoint has been patched.
+ * @throws {Error} When the call cannot be injected or verified.
+ */
+export declare function ensureWorkspaceEntrypointCall({ blockIndexPath, callLine, callPattern, importLine, importPattern, }: {
+    blockIndexPath: string;
+    callLine: string;
+    callPattern: RegExp;
+    importLine: string;
+    importPattern: RegExp;
+}): Promise<void>;
+/**
+ * Ensure a scaffold block registration settings hook is imported and called.
+ *
+ * @param options Registration settings patch options.
+ * @param options.blockIndexPath Absolute path to the block entrypoint file.
+ * @param options.callLine Settings mutation call to insert before registration.
+ * @param options.callPattern Executable pattern used to detect an existing call.
+ * @param options.importLine Import line to prepend when missing.
+ * @param options.importPattern Uncommented import pattern used to avoid duplicates.
+ * @returns A promise that resolves after the entrypoint has been patched.
+ * @throws {Error} When the entrypoint does not expose the expected
+ * `registerScaffoldBlockType(registration.name, registration.settings)` call.
+ */
+export declare function ensureWorkspaceRegistrationSettingsCall({ blockIndexPath, callLine, callPattern, importLine, importPattern, }: {
+    blockIndexPath: string;
+    callLine: string;
+    callPattern: RegExp;
+    importLine: string;
+    importPattern: RegExp;
+}): Promise<void>;

package/dist/runtime/cli-add-workspace-registration-hooks.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { patchFile } from "./cli-add-shared.js";
+import { findExecutablePatternMatch, hasExecutablePattern, hasUncommentedPattern, maskTypeScriptCommentsAndLiterals, } from "./ts-source-masking.js";
+const SCAFFOLD_REGISTRATION_SETTINGS_CALL_PATTERN = /registerScaffoldBlockType\s*\(\s*registration\s*\.\s*name\s*,\s*registration\s*\.\s*settings\s*\)\s*;?/u;
+function isIdentifierBoundary(source, index) {
+    if (index < 0 || index >= source.length) {
+        return true;
+    }
+    return !/[A-Za-z0-9_$]/u.test(source[index] ?? "");
+}
+function skipWhitespace(source, index) {
+    let cursor = index;
+    while (cursor < source.length && /\s/u.test(source[cursor] ?? "")) {
+        cursor += 1;
+    }
+    return cursor;
+}
+function findMatchingDelimiterEnd(source, openIndex, openDelimiter, closeDelimiter) {
+    let depth = 0;
+    for (let index = openIndex; index < source.length; index += 1) {
+        const char = source[index];
+        if (char === openDelimiter) {
+            depth += 1;
+            continue;
+        }
+        if (char === closeDelimiter) {
+            depth -= 1;
+            if (depth === 0) {
+                return index + 1;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Find the first executable call expression for a named function in source code.
+ *
+ * @param source TypeScript or JavaScript source text to scan.
+ * @param callName Function identifier to locate.
+ * @returns The source range for the first matching executable call, or
+ * `undefined` when the identifier is absent, commented, string-literal-only, or
+ * not followed by a call expression.
+ */
+export function findExecutableCallRange(source, callName) {
+    const maskedSource = maskTypeScriptCommentsAndLiterals(source);
+    let searchIndex = 0;
+    while (searchIndex < maskedSource.length) {
+        const callNameIndex = maskedSource.indexOf(callName, searchIndex);
+        if (callNameIndex === -1) {
+            return undefined;
+        }
+        const callNameEnd = callNameIndex + callName.length;
+        if (!isIdentifierBoundary(maskedSource, callNameIndex - 1) ||
+            !isIdentifierBoundary(maskedSource, callNameEnd)) {
+            searchIndex = callNameEnd;
+            continue;
+        }
+        let cursor = skipWhitespace(maskedSource, callNameEnd);
+        if (maskedSource[cursor] === "<") {
+            const genericEnd = findMatchingDelimiterEnd(maskedSource, cursor, "<", ">");
+            if (genericEnd === undefined) {
+                searchIndex = callNameEnd;
+                continue;
+            }
+            cursor = skipWhitespace(maskedSource, genericEnd);
+        }
+        if (maskedSource[cursor] !== "(") {
+            searchIndex = callNameEnd;
+            continue;
+        }
+        const callEnd = findMatchingDelimiterEnd(maskedSource, cursor, "(", ")");
+        if (callEnd === undefined) {
+            searchIndex = callNameEnd;
+            continue;
+        }
+        let end = skipWhitespace(maskedSource, callEnd);
+        if (maskedSource[end] === ";") {
+            end += 1;
+        }
+        return {
+            end,
+            start: callNameIndex,
+        };
+    }
+    return undefined;
+}
+function findBlockRegistrationCallRange(source) {
+    return (findExecutableCallRange(source, "registerScaffoldBlockType") ??
+        findExecutableCallRange(source, "registerBlockType"));
+}
+/**
+ * Ensure a block entrypoint imports and calls a workspace registration helper.
+ *
+ * @param options Entrypoint patch options.
+ * @param options.blockIndexPath Absolute path to the block entrypoint file.
+ * @param options.callLine Call expression line to insert when missing.
+ * @param options.callPattern Executable pattern used to detect an existing call.
+ * @param options.importLine Import line to prepend when missing.
+ * @param options.importPattern Uncommented import pattern used to avoid duplicates.
+ * @returns A promise that resolves after the entrypoint has been patched.
+ * @throws {Error} When the call cannot be injected or verified.
+ */
+export async function ensureWorkspaceEntrypointCall({ blockIndexPath, callLine, callPattern, importLine, importPattern, }) {
+    await patchFile(blockIndexPath, (source) => {
+        let nextSource = source;
+        if (!hasUncommentedPattern(nextSource, importPattern)) {
+            nextSource = `${importLine}\n${nextSource}`;
+        }
+        if (!hasExecutablePattern(nextSource, callPattern)) {
+            const callRange = findBlockRegistrationCallRange(nextSource);
+            if (callRange) {
+                nextSource = [
+                    nextSource.slice(0, callRange.end),
+                    `\n${callLine}\n`,
+                    nextSource.slice(callRange.end),
+                ].join("");
+            }
+            else {
+                nextSource = `${nextSource.trimEnd()}\n\n${callLine}\n`;
+            }
+        }
+        if (!hasExecutablePattern(nextSource, callPattern)) {
+            throw new Error(`Unable to inject ${callLine} into ${path.basename(blockIndexPath)}.`);
+        }
+        return nextSource;
+    });
+}
+/**
+ * Ensure a scaffold block registration settings hook is imported and called.
+ *
+ * @param options Registration settings patch options.
+ * @param options.blockIndexPath Absolute path to the block entrypoint file.
+ * @param options.callLine Settings mutation call to insert before registration.
+ * @param options.callPattern Executable pattern used to detect an existing call.
+ * @param options.importLine Import line to prepend when missing.
+ * @param options.importPattern Uncommented import pattern used to avoid duplicates.
+ * @returns A promise that resolves after the entrypoint has been patched.
+ * @throws {Error} When the entrypoint does not expose the expected
+ * `registerScaffoldBlockType(registration.name, registration.settings)` call.
+ */
+export async function ensureWorkspaceRegistrationSettingsCall({ blockIndexPath, callLine, callPattern, importLine, importPattern, }) {
+    await patchFile(blockIndexPath, (source) => {
+        let nextSource = source;
+        if (!hasUncommentedPattern(nextSource, importPattern)) {
+            nextSource = `${importLine}\n${nextSource}`;
+        }
+        if (!hasExecutablePattern(nextSource, callPattern)) {
+            const callRange = findExecutablePatternMatch(nextSource, [
+                SCAFFOLD_REGISTRATION_SETTINGS_CALL_PATTERN,
+            ]);
+            if (!callRange) {
+                throw new Error(`Unable to inject ${callLine} into ${path.basename(blockIndexPath)} because it does not expose a scaffold registration settings object.`);
+            }
+            nextSource = [
+                nextSource.slice(0, callRange.start),
+                `${callLine}\n`,
+                nextSource.slice(callRange.start),
+            ].join("");
+        }
+        return nextSource;
+    });
+}

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

@@ -1,4 +1,9 @@
-import type { WorkspaceProject } from "./workspace-project.js";
-export declare function ensureRestResourceBootstrapAnchors(workspace: WorkspaceProject): Promise<void>;
-export declare function ensureContractSyncScriptAnchors(workspace: WorkspaceProject): Promise<void>;
-export declare function ensureRestResourceSyncScriptAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Compatibility facade for REST workspace anchor patchers.
+ *
+ * Keep the public runtime import path stable while bootstrap, contract sync,
+ * and REST resource sync patchers live in focused implementation modules.
+ */
+export { ensureRestResourceBootstrapAnchors, ensureRestSchemaHelperBootstrapAnchors, } from "./cli-add-workspace-rest-bootstrap-anchors.js";
+export { ensureContractSyncScriptAnchors, } from "./cli-add-workspace-rest-contract-sync-anchors.js";
+export { ensureRestResourceSyncScriptAnchors, } from "./cli-add-workspace-rest-resource-sync-anchors.js";