@wp-typia/project-tools 0.11.1 → 0.12.0

package/dist/runtime/workspace-inventory.js

@@ -0,0 +1,270 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import ts from "typescript";
+export const BLOCK_CONFIG_ENTRY_MARKER = "\t// wp-typia add block entries";
+export const VARIATION_CONFIG_ENTRY_MARKER = "\t// wp-typia add variation entries";
+export const PATTERN_CONFIG_ENTRY_MARKER = "\t// wp-typia add pattern entries";
+const VARIATIONS_SECTION = `
+
+export interface WorkspaceVariationConfig {
+\tblock: string;
+\tfile: string;
+\tslug: string;
+}
+
+export const VARIATIONS: WorkspaceVariationConfig[] = [
+\t// wp-typia add variation entries
+];
+`;
+const PATTERNS_SECTION = `
+
+export interface WorkspacePatternConfig {
+\tfile: string;
+\tslug: string;
+}
+
+export const PATTERNS: WorkspacePatternConfig[] = [
+\t// wp-typia add pattern entries
+];
+`;
+function getPropertyNameText(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+        return name.text;
+    }
+    return null;
+}
+function findExportedArrayLiteral(sourceFile, exportName) {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue;
+        }
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+            continue;
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== exportName) {
+                continue;
+            }
+            if (declaration.initializer && ts.isArrayLiteralExpression(declaration.initializer)) {
+                return {
+                    array: declaration.initializer,
+                    found: true,
+                };
+            }
+            return {
+                array: null,
+                found: true,
+            };
+        }
+    }
+    return {
+        array: null,
+        found: false,
+    };
+}
+function getOptionalStringProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (ts.isStringLiteralLike(property.initializer)) {
+            return property.initializer.text;
+        }
+        throw new Error(`${entryName}[${elementIndex}] must use a string literal for "${key}" in scripts/block-config.ts.`);
+    }
+    return undefined;
+}
+function getRequiredStringProperty(entryName, elementIndex, objectLiteral, key) {
+    const value = getOptionalStringProperty(entryName, elementIndex, objectLiteral, key);
+    if (!value) {
+        throw new Error(`${entryName}[${elementIndex}] is missing required "${key}" in scripts/block-config.ts.`);
+    }
+    return value;
+}
+function parseBlockEntries(arrayLiteral) {
+    return arrayLiteral.elements.map((element, elementIndex) => {
+        if (!ts.isObjectLiteralExpression(element)) {
+            throw new Error(`BLOCKS[${elementIndex}] must be an object literal in scripts/block-config.ts.`);
+        }
+        return {
+            apiTypesFile: getOptionalStringProperty("BLOCKS", elementIndex, element, "apiTypesFile"),
+            attributeTypeName: getOptionalStringProperty("BLOCKS", elementIndex, element, "attributeTypeName"),
+            openApiFile: getOptionalStringProperty("BLOCKS", elementIndex, element, "openApiFile"),
+            slug: getRequiredStringProperty("BLOCKS", elementIndex, element, "slug"),
+            typesFile: getRequiredStringProperty("BLOCKS", elementIndex, element, "typesFile"),
+        };
+    });
+}
+function parseVariationEntries(arrayLiteral) {
+    return arrayLiteral.elements.map((element, elementIndex) => {
+        if (!ts.isObjectLiteralExpression(element)) {
+            throw new Error(`VARIATIONS[${elementIndex}] must be an object literal in scripts/block-config.ts.`);
+        }
+        return {
+            block: getRequiredStringProperty("VARIATIONS", elementIndex, element, "block"),
+            file: getRequiredStringProperty("VARIATIONS", elementIndex, element, "file"),
+            slug: getRequiredStringProperty("VARIATIONS", elementIndex, element, "slug"),
+        };
+    });
+}
+function parsePatternEntries(arrayLiteral) {
+    return arrayLiteral.elements.map((element, elementIndex) => {
+        if (!ts.isObjectLiteralExpression(element)) {
+            throw new Error(`PATTERNS[${elementIndex}] must be an object literal in scripts/block-config.ts.`);
+        }
+        return {
+            file: getRequiredStringProperty("PATTERNS", elementIndex, element, "file"),
+            slug: getRequiredStringProperty("PATTERNS", elementIndex, element, "slug"),
+        };
+    });
+}
+/**
+ * Parse workspace inventory entries from the source of `scripts/block-config.ts`.
+ *
+ * @param source Raw TypeScript source from `scripts/block-config.ts`.
+ * @returns Parsed inventory sections without the resolved `blockConfigPath`.
+ * @throws {Error} When `BLOCKS` is missing or any inventory entry is malformed.
+ */
+export function parseWorkspaceInventorySource(source) {
+    const sourceFile = ts.createSourceFile("block-config.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const blockArray = findExportedArrayLiteral(sourceFile, "BLOCKS");
+    if (!blockArray.found || !blockArray.array) {
+        throw new Error("scripts/block-config.ts must export a BLOCKS array.");
+    }
+    const variationArray = findExportedArrayLiteral(sourceFile, "VARIATIONS");
+    const patternArray = findExportedArrayLiteral(sourceFile, "PATTERNS");
+    if (variationArray.found && !variationArray.array) {
+        throw new Error("scripts/block-config.ts must export VARIATIONS as an array literal.");
+    }
+    if (patternArray.found && !patternArray.array) {
+        throw new Error("scripts/block-config.ts must export PATTERNS as an array literal.");
+    }
+    return {
+        blocks: parseBlockEntries(blockArray.array),
+        hasPatternsSection: patternArray.found,
+        hasVariationsSection: variationArray.found,
+        patterns: patternArray.array ? parsePatternEntries(patternArray.array) : [],
+        source,
+        variations: variationArray.array ? parseVariationEntries(variationArray.array) : [],
+    };
+}
+/**
+ * Read and parse the canonical workspace inventory file.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export function readWorkspaceInventory(projectDir) {
+    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
+    let source;
+    try {
+        source = fs.readFileSync(blockConfigPath, "utf8");
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new Error(`Workspace inventory file is missing at ${blockConfigPath}. Expected scripts/block-config.ts to exist.`);
+        }
+        throw error;
+    }
+    return {
+        blockConfigPath,
+        ...parseWorkspaceInventorySource(source),
+    };
+}
+/**
+ * Return select options for the current workspace block inventory.
+ *
+ * The `description` field mirrors `block.typesFile`, while `name` and `value`
+ * both map to the block slug for use in interactive add flows.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Block options for variation-target selection.
+ */
+export function getWorkspaceBlockSelectOptions(projectDir) {
+    return readWorkspaceInventory(projectDir).blocks.map((block) => ({
+        description: block.typesFile,
+        name: block.slug,
+        value: block.slug,
+    }));
+}
+function ensureWorkspaceInventorySections(source) {
+    let nextSource = source.trimEnd();
+    if (!/export\s+interface\s+WorkspaceVariationConfig\b/u.test(nextSource)) {
+        nextSource += VARIATIONS_SECTION;
+    }
+    else if (!/export\s+const\s+VARIATIONS\b/u.test(nextSource)) {
+        nextSource += `
+
+export const VARIATIONS: WorkspaceVariationConfig[] = [
+\t// wp-typia add variation entries
+];
+`;
+    }
+    if (!/export\s+interface\s+WorkspacePatternConfig\b/u.test(nextSource)) {
+        nextSource += PATTERNS_SECTION;
+    }
+    else if (!/export\s+const\s+PATTERNS\b/u.test(nextSource)) {
+        nextSource += `
+
+export const PATTERNS: WorkspacePatternConfig[] = [
+\t// wp-typia add pattern entries
+];
+`;
+    }
+    return `${nextSource}\n`;
+}
+function appendEntriesAtMarker(source, marker, entries) {
+    if (entries.length === 0) {
+        return source;
+    }
+    if (!source.includes(marker)) {
+        throw new Error(`Workspace inventory marker "${marker}" is missing in scripts/block-config.ts.`);
+    }
+    return source.replace(marker, `${entries.join("\n")}\n${marker}`);
+}
+/**
+ * Update `scripts/block-config.ts` source text with additional inventory entries.
+ *
+ * Missing `VARIATIONS` and `PATTERNS` sections are created automatically before
+ * new entries are appended at their marker comments. When provided,
+ * `transformSource` runs before any entries are inserted.
+ *
+ * @param source Existing `scripts/block-config.ts` source.
+ * @param options Entry lists plus an optional source transformer.
+ * @returns Updated source text with all requested inventory entries appended.
+ */
+export function updateWorkspaceInventorySource(source, { blockEntries = [], patternEntries = [], variationEntries = [], transformSource, } = {}) {
+    let nextSource = ensureWorkspaceInventorySections(source);
+    if (transformSource) {
+        nextSource = transformSource(nextSource);
+    }
+    nextSource = appendEntriesAtMarker(nextSource, BLOCK_CONFIG_ENTRY_MARKER, blockEntries);
+    nextSource = appendEntriesAtMarker(nextSource, VARIATION_CONFIG_ENTRY_MARKER, variationEntries);
+    nextSource = appendEntriesAtMarker(nextSource, PATTERN_CONFIG_ENTRY_MARKER, patternEntries);
+    return nextSource;
+}
+/**
+ * Append new entries to the canonical workspace inventory file on disk.
+ *
+ * @param projectDir Workspace root directory.
+ * @param options Entry lists and optional source transform passed through to
+ * `updateWorkspaceInventorySource`.
+ * @returns Resolves once `scripts/block-config.ts` has been updated if needed.
+ */
+export async function appendWorkspaceInventoryEntries(projectDir, options) {
+    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
+    const source = await readFile(blockConfigPath, "utf8");
+    const nextSource = updateWorkspaceInventorySource(source, options);
+    if (nextSource !== source) {
+        await writeFile(blockConfigPath, nextSource, "utf8");
+    }
+}

package/dist/runtime/workspace-project.d.ts

@@ -0,0 +1,66 @@
+import type { PackageManagerId } from "./package-managers.js";
+export declare const WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+export interface WorkspacePackageJson {
+    author?: string;
+    name?: string;
+    packageManager?: string;
+    scripts?: Record<string, string>;
+    wpTypia?: {
+        namespace?: string;
+        phpPrefix?: string;
+        projectType?: string;
+        templatePackage?: string;
+        textDomain?: string;
+    };
+}
+export interface WorkspaceProject {
+    author: string;
+    packageManager: PackageManagerId;
+    packageName: string;
+    projectDir: string;
+    workspace: Required<NonNullable<WorkspacePackageJson["wpTypia"]>>;
+}
+/**
+ * Parse a workspace package manifest from a project directory or `package.json` path.
+ *
+ * @param projectDirOrManifestPath Absolute or relative project directory, or a direct
+ * path to `package.json`.
+ * @returns The parsed workspace package manifest.
+ * @throws {Error} When the manifest cannot be parsed.
+ */
+export declare function parseWorkspacePackageJson(projectDirOrManifestPath: string): WorkspacePackageJson;
+/**
+ * Explain why a nearby wp-typia workspace cannot be resolved from `startDir`.
+ *
+ * @param startDir Directory to begin walking upward from.
+ * @returns A human-readable validation error when a candidate workspace package
+ * manifest is found but its `wpTypia` metadata is invalid, or `null` when no
+ * invalid workspace candidate is discovered.
+ * @throws {Error} When a discovered `package.json` cannot be parsed.
+ */
+export declare function getInvalidWorkspaceProjectReason(startDir: string): string | null;
+/**
+ * Parse a package-manager identifier from a `packageManager` field.
+ *
+ * @param packageManagerField Raw package-manager field such as `bun@1.3.11`.
+ * @returns A normalized `PackageManagerId`, defaulting to `"bun"` when the
+ * field is missing or unsupported.
+ */
+export declare function parseWorkspacePackageManagerId(packageManagerField: string | undefined): PackageManagerId;
+/**
+ * Try to resolve the nearest official wp-typia workspace from `startDir`.
+ *
+ * @param startDir Directory to begin walking upward from.
+ * @returns The resolved `WorkspaceProject`, or `null` when no
+ * `WORKSPACE_TEMPLATE_PACKAGE` workspace is found.
+ * @throws {Error} When a discovered `package.json` cannot be parsed.
+ */
+export declare function tryResolveWorkspaceProject(startDir: string): WorkspaceProject | null;
+/**
+ * Resolve the nearest official wp-typia workspace from `startDir`.
+ *
+ * @param startDir Directory to begin walking upward from.
+ * @returns The resolved `WorkspaceProject`.
+ * @throws {Error} When no `WORKSPACE_TEMPLATE_PACKAGE` workspace can be found.
+ */
+export declare function resolveWorkspaceProject(startDir: string): WorkspaceProject;

package/dist/runtime/workspace-project.js

@@ -0,0 +1,152 @@
+import fs from "node:fs";
+import path from "node:path";
+export const WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+function hasNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Parse a workspace package manifest from a project directory or `package.json` path.
+ *
+ * @param projectDirOrManifestPath Absolute or relative project directory, or a direct
+ * path to `package.json`.
+ * @returns The parsed workspace package manifest.
+ * @throws {Error} When the manifest cannot be parsed.
+ */
+export function parseWorkspacePackageJson(projectDirOrManifestPath) {
+    const packageJsonPath = path.basename(projectDirOrManifestPath) === "package.json"
+        ? projectDirOrManifestPath
+        : path.join(projectDirOrManifestPath, "package.json");
+    try {
+        return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Failed to parse workspace package manifest at ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function getWorkspaceMetadataIssues(packageJson) {
+    if (!packageJson.wpTypia) {
+        return [];
+    }
+    const issues = [];
+    if (packageJson.wpTypia.projectType !== "workspace") {
+        issues.push('wpTypia.projectType must be "workspace"');
+    }
+    if (packageJson.wpTypia.templatePackage !== WORKSPACE_TEMPLATE_PACKAGE) {
+        issues.push(`wpTypia.templatePackage must be "${WORKSPACE_TEMPLATE_PACKAGE}"`);
+    }
+    if (!hasNonEmptyString(packageJson.wpTypia.namespace)) {
+        issues.push("wpTypia.namespace must be a non-empty string");
+    }
+    if (!hasNonEmptyString(packageJson.wpTypia.textDomain)) {
+        issues.push("wpTypia.textDomain must be a non-empty string");
+    }
+    if (!hasNonEmptyString(packageJson.wpTypia.phpPrefix)) {
+        issues.push("wpTypia.phpPrefix must be a non-empty string");
+    }
+    return issues;
+}
+/**
+ * Explain why a nearby wp-typia workspace cannot be resolved from `startDir`.
+ *
+ * @param startDir Directory to begin walking upward from.
+ * @returns A human-readable validation error when a candidate workspace package
+ * manifest is found but its `wpTypia` metadata is invalid, or `null` when no
+ * invalid workspace candidate is discovered.
+ * @throws {Error} When a discovered `package.json` cannot be parsed.
+ */
+export function getInvalidWorkspaceProjectReason(startDir) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            const packageJson = parseWorkspacePackageJson(packageJsonPath);
+            const issues = getWorkspaceMetadataIssues(packageJson);
+            if (issues.length > 0) {
+                return `Invalid wp-typia workspace metadata at ${packageJsonPath}: ${issues.join("; ")}`;
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    return null;
+}
+/**
+ * Parse a package-manager identifier from a `packageManager` field.
+ *
+ * @param packageManagerField Raw package-manager field such as `bun@1.3.11`.
+ * @returns A normalized `PackageManagerId`, defaulting to `"bun"` when the
+ * field is missing or unsupported.
+ */
+export function parseWorkspacePackageManagerId(packageManagerField) {
+    const packageManagerId = packageManagerField?.split("@", 1)[0];
+    switch (packageManagerId) {
+        case "bun":
+        case "npm":
+        case "pnpm":
+        case "yarn":
+            return packageManagerId;
+        default:
+            return "bun";
+    }
+}
+/**
+ * Try to resolve the nearest official wp-typia workspace from `startDir`.
+ *
+ * @param startDir Directory to begin walking upward from.
+ * @returns The resolved `WorkspaceProject`, or `null` when no
+ * `WORKSPACE_TEMPLATE_PACKAGE` workspace is found.
+ * @throws {Error} When a discovered `package.json` cannot be parsed.
+ */
+export function tryResolveWorkspaceProject(startDir) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            const packageJson = parseWorkspacePackageJson(packageJsonPath);
+            if (packageJson.wpTypia?.projectType === "workspace" &&
+                packageJson.wpTypia?.templatePackage === WORKSPACE_TEMPLATE_PACKAGE &&
+                hasNonEmptyString(packageJson.wpTypia.namespace) &&
+                hasNonEmptyString(packageJson.wpTypia.textDomain) &&
+                hasNonEmptyString(packageJson.wpTypia.phpPrefix)) {
+                return {
+                    author: typeof packageJson.author === "string" ? packageJson.author : "Your Name",
+                    packageManager: parseWorkspacePackageManagerId(packageJson.packageManager),
+                    packageName: typeof packageJson.name === "string"
+                        ? packageJson.name
+                        : path.basename(currentDir),
+                    projectDir: currentDir,
+                    workspace: {
+                        namespace: packageJson.wpTypia.namespace,
+                        phpPrefix: packageJson.wpTypia.phpPrefix,
+                        projectType: "workspace",
+                        templatePackage: WORKSPACE_TEMPLATE_PACKAGE,
+                        textDomain: packageJson.wpTypia.textDomain,
+                    },
+                };
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    return null;
+}
+/**
+ * Resolve the nearest official wp-typia workspace from `startDir`.
+ *
+ * @param startDir Directory to begin walking upward from.
+ * @returns The resolved `WorkspaceProject`.
+ * @throws {Error} When no `WORKSPACE_TEMPLATE_PACKAGE` workspace can be found.
+ */
+export function resolveWorkspaceProject(startDir) {
+    const workspace = tryResolveWorkspaceProject(startDir);
+    if (workspace) {
+        return workspace;
+    }
+    throw new Error(`This command must run inside a ${WORKSPACE_TEMPLATE_PACKAGE} project. Create one with \`wp-typia create my-plugin --template ${WORKSPACE_TEMPLATE_PACKAGE}\` first.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@wp-typia/api-client": "^0.4.0",
-    "@wp-typia/block-runtime": "^0.3.0",
+    "@wp-typia/block-runtime": "^0.4.0",
     "@wp-typia/rest": "^0.3.1",
     "@wp-typia/block-types": "^0.2.0",
     "mustache": "^4.2.0",

package/templates/_shared/base/package.json.mustache

@@ -1,7 +1,7 @@
 {
   "name": "{{slug}}",
   "version": "0.1.0",
-  "packageManager": "bun@1.3.10",
+  "packageManager": "bun@1.3.11",
   "description": "{{description}}",
   "author": "{{author}}",
   "license": "GPL-2.0-or-later",

package/templates/_shared/compound/core/package.json.mustache

@@ -1,7 +1,7 @@
 {
   "name": "{{slug}}",
   "version": "0.1.0",
-  "packageManager": "bun@1.3.10",
+  "packageManager": "bun@1.3.11",
   "description": "{{description}}",
   "author": "{{author}}",
   "license": "GPL-2.0-or-later",

package/templates/_shared/compound/persistence/package.json.mustache

@@ -1,7 +1,7 @@
 {
   "name": "{{slug}}",
   "version": "0.1.0",
-  "packageManager": "bun@1.3.10",
+  "packageManager": "bun@1.3.11",
   "description": "{{description}}",
   "author": "{{author}}",
   "license": "GPL-2.0-or-later",

package/templates/_shared/persistence/core/package.json.mustache

@@ -1,7 +1,7 @@
 {
 	"name": "{{slug}}",
 	"version": "0.1.0",
-	"packageManager": "bun@1.3.10",
+	"packageManager": "bun@1.3.11",
 	"description": "{{description}}",
 	"author": "{{author}}",
 	"license": "GPL-2.0-or-later",

package/templates/interactivity/package.json.mustache

@@ -1,7 +1,7 @@
 {
 	"name": "{{slug}}",
 	"version": "0.1.0",
-  "packageManager": "bun@1.3.10",
+  "packageManager": "bun@1.3.11",
 	"description": "{{description}}",
 	"author": "{{author}}",
 	"license": "GPL-2.0-or-later",