wp-typia 0.16.11 → 0.16.13

package/README.md

@@ -12,19 +12,23 @@ Use this package for new installs:
 - `wp-typia add hooked-block counter-card --anchor core/post-content --position after`
 
 `wp-typia <project-dir>` remains available as a backward-compatible alias to
-`wp-typia create <project-dir>`.
+`wp-typia create <project-dir>` when `<project-dir>` is the only positional
+argument.
 
 Compatibility notes:
 
 - `@wp-typia/project-tools` is the canonical programmatic project orchestration package
 - `@wp-typia/create` is the deprecated legacy package shell
 - `create-wp-typia` is archived and should not be used for new installs
+- internal runtime-bridge helper modules are implementation details; integrations
+  should target the CLI or `@wp-typia/project-tools`, not CLI internals
 
-Maintainers: see [`docs/bunli-cli-migration.md`](../../docs/bunli-cli-migration.md)
+Maintainers: see [`docs/bunli-cli-migration.md`](https://imjlk.github.io/wp-typia/maintainers/bunli-cli-migration/)
 for the active CLI ownership contract and the staged Bunli cutover plan.
 
 Project meta docs:
 
 - [Upgrade Guide](https://github.com/imjlk/wp-typia/blob/main/UPGRADE.md)
+- [License](https://github.com/imjlk/wp-typia/blob/main/LICENSE)
 - [Security Policy](https://github.com/imjlk/wp-typia/blob/main/SECURITY.md)
 - [Contributing Guide](https://github.com/imjlk/wp-typia/blob/main/CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wp-typia",
-  "version": "0.16.11",
+  "version": "0.16.13",
   "description": "Canonical CLI package for wp-typia scaffolding and project workflows",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -64,8 +64,8 @@
     "@bunli/runtime": "0.3.1",
     "@bunli/tui": "0.6.0",
     "@bunli/utils": "0.6.0",
-    "@wp-typia/api-client": "^0.4.4",
-    "@wp-typia/project-tools": "0.16.10",
+    "@wp-typia/api-client": "^0.4.5",
+    "@wp-typia/project-tools": "0.16.12",
     "better-result": "^2.7.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",

package/src/command-contract.ts

@@ -1,244 +1,276 @@
-export const WP_TYPIA_CANONICAL_CREATE_USAGE = "wp-typia create <project-dir>";
-export const WP_TYPIA_POSITIONAL_ALIAS_USAGE = "wp-typia <project-dir>";
-export const WP_TYPIA_CANONICAL_MIGRATE_USAGE = "wp-typia migrate <subcommand>";
-export const WP_TYPIA_DEPRECATED_MIGRATIONS_USAGE = "wp-typia migrations <subcommand>";
-export const WP_TYPIA_BUNLI_MIGRATION_DOC = "docs/bunli-cli-migration.md";
+export const WP_TYPIA_CANONICAL_CREATE_USAGE = 'wp-typia create <project-dir>';
+export const WP_TYPIA_POSITIONAL_ALIAS_USAGE = 'wp-typia <project-dir>';
+export const WP_TYPIA_CANONICAL_MIGRATE_USAGE = 'wp-typia migrate <subcommand>';
+export const WP_TYPIA_DEPRECATED_MIGRATIONS_USAGE =
+  'wp-typia migrations <subcommand>';
+export const WP_TYPIA_BUNLI_MIGRATION_DOC =
+  'https://imjlk.github.io/wp-typia/maintainers/bunli-cli-migration/';
 
 export const WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES = [
-	"create",
-	"sync",
-	"add",
-	"migrate",
-	"templates",
-	"doctor",
-	"mcp",
-	"skills",
-	"completions",
-	"complete",
+  'create',
+  'sync',
+  'add',
+  'migrate',
+  'templates',
+  'doctor',
+  'mcp',
+  'skills',
+  'completions',
+  'complete',
 ] as const;
 
 export const WP_TYPIA_TOP_LEVEL_COMMAND_NAMES = [
-	"create",
-	"sync",
-	"add",
-	"migrate",
-	"templates",
-	"doctor",
-	"mcp",
+  'create',
+  'sync',
+  'add',
+  'migrate',
+  'templates',
+  'doctor',
+  'mcp',
 ] as const;
 
 const STRING_OPTION_NAMES_BY_COMMAND = {
-	add: new Set([
-		"anchor",
-		"block",
-		"data-storage",
-		"external-layer-id",
-		"external-layer-source",
-		"persistence-policy",
-		"position",
-		"template",
-	]),
-	create: new Set([
-		"data-storage",
-		"external-layer-id",
-		"external-layer-source",
-		"namespace",
-		"package-manager",
-		"persistence-policy",
-		"php-prefix",
-		"template",
-		"text-domain",
-		"variant",
-	]),
-	migrate: new Set([
-		"current-migration-version",
-		"from-migration-version",
-		"iterations",
-		"migration-version",
-		"seed",
-		"to-migration-version",
-	]),
+  add: new Set([
+    'anchor',
+    'block',
+    'data-storage',
+    'external-layer-id',
+    'external-layer-source',
+    'persistence-policy',
+    'position',
+    'template',
+  ]),
+  create: new Set([
+    'data-storage',
+    'external-layer-id',
+    'external-layer-source',
+    'namespace',
+    'package-manager',
+    'persistence-policy',
+    'php-prefix',
+    'template',
+    'text-domain',
+    'variant',
+  ]),
+  migrate: new Set([
+    'current-migration-version',
+    'from-migration-version',
+    'iterations',
+    'migration-version',
+    'seed',
+    'to-migration-version',
+  ]),
 } as const;
 
 const GLOBAL_STRING_OPTION_NAMES = new Set([
-	"config",
-	"format",
-	"id",
-	"output-dir",
+  'config',
+  'format',
+  'id',
+  'output-dir',
 ]);
 
-const SHORT_OPTION_NAMES_WITH_VALUES = new Set([
-	"c",
-	"p",
-	"t",
-]);
+const SHORT_OPTION_NAMES_WITH_VALUES = new Set(['c', 'p', 't']);
 
 function isLongOptionValueConsumer(optionName: string): boolean {
-	if (GLOBAL_STRING_OPTION_NAMES.has(optionName)) {
-		return true;
-	}
+  if (GLOBAL_STRING_OPTION_NAMES.has(optionName)) {
+    return true;
+  }
 
-	return Object.values(STRING_OPTION_NAMES_BY_COMMAND).some((optionNames) =>
-		optionNames.has(optionName as never),
-	);
+  return Object.values(STRING_OPTION_NAMES_BY_COMMAND).some((optionNames) =>
+    optionNames.has(optionName as never),
+  );
 }
 
 function findFirstPositionalIndex(argv: string[]): number {
-	for (let index = 0; index < argv.length; index += 1) {
-		const arg = argv[index];
-		if (arg === "--") {
-			return index + 1 < argv.length ? index + 1 : -1;
-		}
-		if (!arg.startsWith("-") || arg === "-") {
-			return index;
-		}
-		if (arg.startsWith("--")) {
-			if (arg.includes("=")) {
-				continue;
-			}
-			if (isLongOptionValueConsumer(arg.slice(2))) {
-				index += 1;
-			}
-			continue;
-		}
-		if (arg.length === 2 && SHORT_OPTION_NAMES_WITH_VALUES.has(arg.slice(1))) {
-			index += 1;
-		}
-	}
-
-	return -1;
+  const positionalIndexes = collectPositionalIndexes(argv);
+  return positionalIndexes[0] ?? -1;
+}
+
+function collectPositionalIndexes(argv: string[]): number[] {
+  const positionalIndexes: number[] = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--') {
+      for (let restIndex = index + 1; restIndex < argv.length; restIndex += 1) {
+        positionalIndexes.push(restIndex);
+      }
+      break;
+    }
+    if (!arg.startsWith('-') || arg === '-') {
+      positionalIndexes.push(index);
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      if (arg.includes('=')) {
+        continue;
+      }
+      if (isLongOptionValueConsumer(arg.slice(2))) {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg.length === 2 && SHORT_OPTION_NAMES_WITH_VALUES.has(arg.slice(1))) {
+      index += 1;
+    }
+  }
+
+  return positionalIndexes;
 }
 
 export const WP_TYPIA_FUTURE_COMMAND_TREE = [
-	{
-		description: "Scaffold a new wp-typia project.",
-		name: "create",
-	},
-	{
-		description: "Run the common generated-project sync workflow.",
-		name: "sync",
-	},
-	{
-		description: "Extend an official wp-typia workspace.",
-		name: "add",
-		subcommands: ["block", "variation", "pattern", "binding-source", "hooked-block"],
-	},
-	{
-		description: "Run migration workflows.",
-		name: "migrate",
-		subcommands: [
-			"init",
-			"snapshot",
-			"diff",
-			"scaffold",
-			"plan",
-			"wizard",
-			"verify",
-			"doctor",
-			"fixtures",
-			"fuzz",
-		],
-	},
-	{
-		description: "Inspect scaffold templates.",
-		name: "templates",
-		subcommands: ["list", "inspect"],
-	},
-	{
-		description: "Run repository and project diagnostics.",
-		name: "doctor",
-	},
-	{
-		description: "Inspect or sync schema-driven MCP metadata.",
-		name: "mcp",
-		subcommands: ["list", "sync"],
-	},
+  {
+    description: 'Scaffold a new wp-typia project.',
+    name: 'create',
+  },
+  {
+    description: 'Run the common generated-project sync workflow.',
+    name: 'sync',
+  },
+  {
+    description: 'Extend an official wp-typia workspace.',
+    name: 'add',
+    subcommands: [
+      'block',
+      'variation',
+      'pattern',
+      'binding-source',
+      'hooked-block',
+    ],
+  },
+  {
+    description: 'Run migration workflows.',
+    name: 'migrate',
+    subcommands: [
+      'init',
+      'snapshot',
+      'diff',
+      'scaffold',
+      'plan',
+      'wizard',
+      'verify',
+      'doctor',
+      'fixtures',
+      'fuzz',
+    ],
+  },
+  {
+    description: 'Inspect scaffold templates.',
+    name: 'templates',
+    subcommands: ['list', 'inspect'],
+  },
+  {
+    description: 'Run repository and project diagnostics.',
+    name: 'doctor',
+  },
+  {
+    description: 'Inspect or sync schema-driven MCP metadata.',
+    name: 'mcp',
+    subcommands: ['list', 'sync'],
+  },
 ] as const;
 
 export function isReservedTopLevelCommandName(value: string): boolean {
-	return WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES.includes(
-		value as (typeof WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES)[number],
-	);
+  return WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES.includes(
+    value as (typeof WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES)[number],
+  );
 }
 
 function assertStringOptionValues(argv: string[]): void {
-	const firstPositionalIndex = findFirstPositionalIndex(argv);
-	if (firstPositionalIndex === -1) {
-		return;
-	}
-
-	const commandName = argv[firstPositionalIndex] as keyof typeof STRING_OPTION_NAMES_BY_COMMAND;
-	const stringOptionNames = new Set<string>(GLOBAL_STRING_OPTION_NAMES);
-	for (const optionName of STRING_OPTION_NAMES_BY_COMMAND[commandName] ?? []) {
-		stringOptionNames.add(optionName);
-	}
-
-	for (let index = firstPositionalIndex + 1; index < argv.length; index += 1) {
-		const arg = argv[index];
-		if (arg === "--") {
-			break;
-		}
-		if (arg.length === 2 && arg.startsWith("-")) {
-			if (SHORT_OPTION_NAMES_WITH_VALUES.has(arg.slice(1))) {
-				const next = argv[index + 1];
-				if (!next || next.startsWith("-")) {
-					throw new Error(`\`${arg}\` requires a value.`);
-				}
-				index += 1;
-			}
-			continue;
-		}
-		if (!arg.startsWith("--")) {
-			continue;
-		}
-
-		const [rawName, inlineValue] = arg.slice(2).split("=", 2);
-		if (!stringOptionNames.has(rawName)) {
-			continue;
-		}
-
-		if (arg.includes("=")) {
-			if (!inlineValue) {
-				throw new Error(`\`--${rawName}\` requires a value.`);
-			}
-			continue;
-		}
-
-		const next = argv[index + 1];
-		if (!next || next.startsWith("-")) {
-			throw new Error(`\`--${rawName}\` requires a value.`);
-		}
-		index += 1;
-	}
+  const firstPositionalIndex = findFirstPositionalIndex(argv);
+  if (firstPositionalIndex === -1) {
+    return;
+  }
+
+  const commandName = argv[
+    firstPositionalIndex
+  ] as keyof typeof STRING_OPTION_NAMES_BY_COMMAND;
+  const stringOptionNames = new Set<string>(GLOBAL_STRING_OPTION_NAMES);
+  for (const optionName of STRING_OPTION_NAMES_BY_COMMAND[commandName] ?? []) {
+    stringOptionNames.add(optionName);
+  }
+
+  for (let index = firstPositionalIndex + 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--') {
+      break;
+    }
+    if (arg.length === 2 && arg.startsWith('-')) {
+      if (SHORT_OPTION_NAMES_WITH_VALUES.has(arg.slice(1))) {
+        const next = argv[index + 1];
+        if (!next || next.startsWith('-')) {
+          throw new Error(`\`${arg}\` requires a value.`);
+        }
+        index += 1;
+      }
+      continue;
+    }
+    if (!arg.startsWith('--')) {
+      continue;
+    }
+
+    const [rawName, inlineValue] = arg.slice(2).split('=', 2);
+    if (!stringOptionNames.has(rawName)) {
+      continue;
+    }
+
+    if (arg.includes('=')) {
+      if (!inlineValue) {
+        throw new Error(`\`--${rawName}\` requires a value.`);
+      }
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (!next || next.startsWith('-')) {
+      throw new Error(`\`--${rawName}\` requires a value.`);
+    }
+    index += 1;
+  }
 }
 
 export function normalizeWpTypiaArgv(argv: string[]): string[] {
-	const firstPositionalIndex = findFirstPositionalIndex(argv);
-	if (firstPositionalIndex === -1) {
-		return argv;
-	}
-
-	const firstPositional = argv[firstPositionalIndex];
-	if (!firstPositional) {
-		return argv;
-	}
-
-	if (firstPositional === "migrations") {
-		throw new Error(
-			"`wp-typia migrations` was removed in favor of `wp-typia migrate`. Use `wp-typia migrate <subcommand>` instead.",
-		);
-	}
-
-	if (isReservedTopLevelCommandName(firstPositional)) {
-		assertStringOptionValues(argv);
-		return argv;
-	}
-
-	const normalizedArgv = [
-		...argv.slice(0, firstPositionalIndex),
-		"create",
-		...argv.slice(firstPositionalIndex),
-	];
-	assertStringOptionValues(normalizedArgv);
-	return normalizedArgv;
+  const positionalIndexes = collectPositionalIndexes(argv);
+  const firstPositionalIndex = positionalIndexes[0] ?? -1;
+  if (firstPositionalIndex === -1) {
+    return argv;
+  }
+
+  const firstPositional = argv[firstPositionalIndex];
+  if (!firstPositional) {
+    return argv;
+  }
+
+  if (firstPositional === 'migrations') {
+    throw new Error(
+      '`wp-typia migrations` was removed in favor of `wp-typia migrate`. Use `wp-typia migrate <subcommand>` instead.',
+    );
+  }
+
+  if (isReservedTopLevelCommandName(firstPositional)) {
+    assertStringOptionValues(argv);
+    return argv;
+  }
+
+  if (positionalIndexes.length > 1) {
+    const extraPositionals = positionalIndexes
+      .slice(1)
+      .map((index) => argv[index])
+      .filter(
+        (value): value is string =>
+          typeof value === 'string' && value.length > 0,
+      );
+
+    throw new Error(
+      `The positional alias only accepts a single project directory. Use \`${WP_TYPIA_CANONICAL_CREATE_USAGE}\` for scaffold invocations with additional positional arguments, or check the command spelling if you meant another top-level command. Extra positional arguments: ${extraPositionals.map((value) => `\`${value}\``).join(', ')}.`,
+    );
+  }
+
+  const normalizedArgv = [
+    ...argv.slice(0, firstPositionalIndex),
+    'create',
+    ...argv.slice(firstPositionalIndex),
+  ];
+  assertStringOptionValues(normalizedArgv);
+  return normalizedArgv;
 }

package/src/runtime-bridge-output.ts

@@ -0,0 +1,216 @@
+import type { AlternateBufferCompletionPayload } from "./ui/alternate-buffer-lifecycle";
+
+type PrintLine = (line: string) => void;
+
+type ExternalLayerSelectOption = {
+	description?: string;
+	extends: string[];
+	id: string;
+};
+
+/**
+ * Prints a formatted alternate-buffer completion payload to the provided writers.
+ *
+ * @param payload Structured completion payload to render.
+ * @param options Optional line printers for normal output and warnings.
+ * @returns Nothing.
+ */
+export function printCompletionPayload(
+	payload: AlternateBufferCompletionPayload,
+	options: {
+		printLine?: PrintLine;
+		warnLine?: PrintLine;
+	} = {},
+): void {
+	const printLine = options.printLine ?? (console.log as PrintLine);
+	const warnLine = options.warnLine ?? printLine;
+
+	for (const line of payload.preambleLines ?? []) {
+		printLine(line);
+	}
+	for (const warning of payload.warningLines ?? []) {
+		warnLine(`⚠️ ${warning}`);
+	}
+
+	const hasDetails =
+		(payload.summaryLines?.length ?? 0) > 0 ||
+		(payload.nextSteps?.length ?? 0) > 0 ||
+		(payload.optionalLines?.length ?? 0) > 0 ||
+		Boolean(payload.optionalNote);
+	const hasLeadingContext =
+		(payload.preambleLines?.length ?? 0) > 0 ||
+		(payload.warningLines?.length ?? 0) > 0;
+
+	printLine(hasLeadingContext && hasDetails ? `\n${payload.title}` : payload.title);
+	for (const line of payload.summaryLines ?? []) {
+		printLine(line);
+	}
+	if ((payload.nextSteps?.length ?? 0) > 0) {
+		printLine("Next steps:");
+		for (const step of payload.nextSteps ?? []) {
+			printLine(`  ${step}`);
+		}
+	}
+	if ((payload.optionalLines?.length ?? 0) > 0) {
+		printLine(`\n${payload.optionalTitle ?? "Optional:"}`);
+		for (const step of payload.optionalLines ?? []) {
+			printLine(`  ${step}`);
+		}
+	}
+	if (payload.optionalNote) {
+		printLine(`Note: ${payload.optionalNote}`);
+	}
+}
+
+/**
+ * Builds the completion payload shown after a create flow succeeds.
+ *
+ * @param flow Resolved create-flow data including onboarding steps and warnings.
+ * @returns A structured alternate-buffer completion payload.
+ */
+export function buildCreateCompletionPayload(flow: {
+	nextSteps: string[];
+	optionalOnboarding: {
+		note: string;
+		steps: string[];
+	};
+	projectDir: string;
+	result: {
+		selectedVariant?: string | null;
+		variables: {
+			title: string;
+		};
+		warnings: string[];
+	};
+}): AlternateBufferCompletionPayload {
+	return {
+		nextSteps: flow.nextSteps,
+		optionalLines:
+			flow.optionalOnboarding.steps.length > 0 ? flow.optionalOnboarding.steps : undefined,
+		optionalNote:
+			flow.optionalOnboarding.steps.length > 0 ? flow.optionalOnboarding.note : undefined,
+		optionalTitle:
+			flow.optionalOnboarding.steps.length > 0 ? "Optional before first commit:" : undefined,
+		preambleLines: flow.result.selectedVariant
+			? [`Template variant: ${flow.result.selectedVariant}`]
+			: undefined,
+		summaryLines: [`Project directory: ${flow.projectDir}`],
+		title: `✅ Created ${flow.result.variables.title} in ${flow.projectDir}`,
+		warningLines: flow.result.warnings,
+	};
+}
+
+/**
+ * Builds the completion payload shown after a migrate command succeeds.
+ *
+ * @param options Completed migrate command metadata plus rendered lines.
+ * @returns A structured alternate-buffer completion payload.
+ */
+export function buildMigrationCompletionPayload(options: {
+	command: string;
+	lines: string[];
+}): AlternateBufferCompletionPayload {
+	const summaryLines = options.lines.filter((line) => line.trim().length > 0);
+
+	return {
+		summaryLines,
+		title: `✅ Completed wp-typia migrate ${options.command}`,
+	};
+}
+
+/**
+ * Builds the completion payload shown after an add flow succeeds.
+ *
+ * @param options Add-flow kind plus normalized values to summarize.
+ * @returns A structured alternate-buffer completion payload.
+ */
+export function buildAddCompletionPayload(options: {
+	kind: "binding-source" | "block" | "hooked-block" | "pattern" | "variation";
+	projectDir: string;
+	values: Record<string, string>;
+	warnings?: string[];
+}): AlternateBufferCompletionPayload {
+	switch (options.kind) {
+		case "variation":
+			return {
+				summaryLines: [
+					`Variation: ${options.values.variationSlug}`,
+					`Target block: ${options.values.blockSlug}`,
+					`Project directory: ${options.projectDir}`,
+				],
+				title: "✅ Added workspace variation",
+			};
+		case "pattern":
+			return {
+				summaryLines: [
+					`Pattern: ${options.values.patternSlug}`,
+					`Project directory: ${options.projectDir}`,
+				],
+				title: "✅ Added workspace pattern",
+			};
+		case "binding-source":
+			return {
+				summaryLines: [
+					`Binding source: ${options.values.bindingSourceSlug}`,
+					`Project directory: ${options.projectDir}`,
+				],
+				title: "✅ Added binding source",
+			};
+		case "hooked-block":
+			return {
+				summaryLines: [
+					`Block: ${options.values.blockSlug}`,
+					`Anchor: ${options.values.anchorBlockName}`,
+					`Position: ${options.values.position}`,
+					`Project directory: ${options.projectDir}`,
+				],
+				title: "✅ Added blockHooks metadata",
+			};
+		default:
+			return {
+				summaryLines: [
+					`Blocks: ${options.values.blockSlugs}`,
+					`Template family: ${options.values.templateId}`,
+					`Project directory: ${options.projectDir}`,
+				],
+				title: "✅ Added workspace block",
+				warningLines: options.warnings,
+			};
+	}
+}
+
+/**
+ * Prints a block of text lines using a shared line printer.
+ *
+ * @param lines Lines to print in order.
+ * @param printLine Line printer to use.
+ * @returns Nothing.
+ */
+export function printBlock(lines: string[], printLine: PrintLine): void {
+	for (const line of lines) {
+		printLine(line);
+	}
+}
+
+function formatExternalLayerSelectHint(option: ExternalLayerSelectOption): string | undefined {
+	const details = [
+		option.description,
+		option.extends.length > 0 ? `extends ${option.extends.join(", ")}` : undefined,
+	].filter((value): value is string => typeof value === "string" && value.length > 0);
+
+	return details.length > 0 ? details.join(" · ") : undefined;
+}
+
+/**
+ * Converts external layer options into prompt-compatible select items.
+ *
+ * @param options External layer options returned by the block generator.
+ * @returns Prompt select options with labels and hints.
+ */
+export function toExternalLayerPromptOptions(options: ExternalLayerSelectOption[]) {
+	return options.map((option) => ({
+		hint: formatExternalLayerSelectHint(option),
+		label: option.id,
+		value: option.id,
+	}));
+}

package/src/runtime-bridge-sync.ts

@@ -0,0 +1,169 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { formatRunScript } from "@wp-typia/project-tools/package-managers";
+
+type PackageManagerId = "bun" | "npm" | "pnpm" | "yarn";
+
+type SyncExecutionInput = {
+	check?: boolean;
+	cwd: string;
+};
+
+type SyncProjectContext = {
+	cwd: string;
+	packageJsonPath: string;
+	packageManager: PackageManagerId;
+	scripts: Partial<Record<"sync" | "sync-rest" | "sync-types", string>>;
+};
+
+function getSyncRootError(cwd: string): Error {
+	return new Error(
+		`No generated wp-typia project root was found at ${cwd}. Run \`wp-typia sync\` from a scaffolded project or official workspace root.`,
+	);
+}
+
+function inferSyncPackageManager(cwd: string, packageManagerField?: string): PackageManagerId {
+	const field = String(packageManagerField ?? "");
+	if (field.startsWith("bun@")) return "bun";
+	if (field.startsWith("npm@")) return "npm";
+	if (field.startsWith("pnpm@")) return "pnpm";
+	if (field.startsWith("yarn@")) return "yarn";
+
+	if (
+		fs.existsSync(path.join(cwd, "bun.lock")) ||
+		fs.existsSync(path.join(cwd, "bun.lockb"))
+	) {
+		return "bun";
+	}
+	if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+		return "pnpm";
+	}
+	if (
+		fs.existsSync(path.join(cwd, "yarn.lock")) ||
+		fs.existsSync(path.join(cwd, ".pnp.cjs")) ||
+		fs.existsSync(path.join(cwd, ".pnp.loader.mjs")) ||
+		fs.existsSync(path.join(cwd, ".yarnrc.yml"))
+	) {
+		return "yarn";
+	}
+	if (
+		fs.existsSync(path.join(cwd, "package-lock.json")) ||
+		fs.existsSync(path.join(cwd, "npm-shrinkwrap.json"))
+	) {
+		return "npm";
+	}
+
+	return "npm";
+}
+
+function resolveSyncProjectContext(cwd: string): SyncProjectContext {
+	const packageJsonPath = path.join(cwd, "package.json");
+	if (!fs.existsSync(packageJsonPath)) {
+		throw getSyncRootError(cwd);
+	}
+
+	const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as {
+		packageManager?: string;
+		scripts?: Record<string, unknown>;
+	};
+	const scripts = packageJson.scripts ?? {};
+	const syncScripts = {
+		sync: typeof scripts.sync === "string" ? scripts.sync : undefined,
+		"sync-rest":
+			typeof scripts["sync-rest"] === "string" ? scripts["sync-rest"] : undefined,
+		"sync-types":
+			typeof scripts["sync-types"] === "string" ? scripts["sync-types"] : undefined,
+	} satisfies SyncProjectContext["scripts"];
+
+	if (!syncScripts.sync && !syncScripts["sync-types"]) {
+		throw new Error(
+			`Expected ${packageJsonPath} to define either a \`sync\` or \`sync-types\` script.`,
+		);
+	}
+
+	return {
+		cwd,
+		packageJsonPath,
+		packageManager: inferSyncPackageManager(cwd, packageJson.packageManager),
+		scripts: syncScripts,
+	};
+}
+
+function getPackageManagerRunInvocation(
+	packageManager: PackageManagerId,
+	scriptName: string,
+	extraArgs: string[],
+): { args: string[]; command: string } {
+	switch (packageManager) {
+		case "bun":
+			return { args: ["run", scriptName, ...extraArgs], command: "bun" };
+		case "npm":
+			return {
+				args: ["run", scriptName, ...(extraArgs.length > 0 ? ["--", ...extraArgs] : [])],
+				command: "npm",
+			};
+		case "pnpm":
+			return { args: ["run", scriptName, ...extraArgs], command: "pnpm" };
+		case "yarn":
+			return { args: ["run", scriptName, ...extraArgs], command: "yarn" };
+	}
+}
+
+function runProjectScript(
+	project: SyncProjectContext,
+	scriptName: "sync" | "sync-rest" | "sync-types",
+	extraArgs: string[],
+): void {
+	const script = project.scripts[scriptName];
+	if (!script) {
+		return;
+	}
+
+	const invocation = getPackageManagerRunInvocation(
+		project.packageManager,
+		scriptName,
+		extraArgs,
+	);
+
+	const result = spawnSync(invocation.command, invocation.args, {
+		cwd: project.cwd,
+		shell: process.platform === "win32",
+		stdio: "inherit",
+	});
+
+	if (result.error || result.status !== 0) {
+		throw new Error(
+			`\`${formatRunScript(project.packageManager, scriptName, extraArgs.join(" "))}\` failed.`,
+			{
+				cause: result.error,
+			},
+		);
+	}
+}
+
+/**
+ * Executes the generated-project sync flow through the local project scripts.
+ *
+ * @param options Sync execution options including cwd and optional `--check`.
+ * @returns A promise that resolves after the relevant sync scripts complete.
+ */
+export async function executeSyncCommand({
+	check = false,
+	cwd,
+}: SyncExecutionInput): Promise<void> {
+	const project = resolveSyncProjectContext(cwd);
+	const extraArgs = check ? ["--check"] : [];
+
+	if (project.scripts.sync) {
+		runProjectScript(project, "sync", extraArgs);
+		return;
+	}
+
+	runProjectScript(project, "sync-types", extraArgs);
+
+	if (project.scripts["sync-rest"]) {
+		runProjectScript(project, "sync-rest", extraArgs);
+	}
+}

package/src/runtime-bridge.ts

@@ -1,7 +1,3 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-
 import {
 	formatTemplateDetails,
 	formatTemplateFeatures,
@@ -9,10 +5,23 @@ import {
 	getTemplateById,
 	listTemplates,
 } from "@wp-typia/project-tools/cli-templates";
-import { formatRunScript } from "@wp-typia/project-tools/package-managers";
 import { tryResolveWorkspaceProject } from "@wp-typia/project-tools/workspace-project";
 import type { ReadlinePrompt } from "@wp-typia/project-tools/cli-prompt";
 import type { AlternateBufferCompletionPayload } from "./ui/alternate-buffer-lifecycle";
+import {
+	buildAddCompletionPayload,
+	buildCreateCompletionPayload,
+	buildMigrationCompletionPayload,
+	printBlock,
+	printCompletionPayload,
+	toExternalLayerPromptOptions,
+} from "./runtime-bridge-output";
+export {
+	buildCreateCompletionPayload,
+	buildMigrationCompletionPayload,
+	printCompletionPayload,
+} from "./runtime-bridge-output";
+export { executeSyncCommand } from "./runtime-bridge-sync";
 
 type CreateExecutionInput = {
 	projectDir: string;
@@ -44,11 +53,6 @@ type TemplatesExecutionInput = {
 	};
 };
 
-type SyncExecutionInput = {
-	check?: boolean;
-	cwd: string;
-};
-
 type MigrateExecutionInput = {
 	command?: string;
 	cwd: string;
@@ -58,20 +62,7 @@ type MigrateExecutionInput = {
 };
 
 type PrintLine = (line: string) => void;
-type PackageManagerId = "bun" | "npm" | "pnpm" | "yarn";
 type CliCommandId = "add" | "create" | "doctor" | "migrate";
-type ExternalLayerSelectOption = {
-	description?: string;
-	extends: string[];
-	id: string;
-};
-
-type SyncProjectContext = {
-	cwd: string;
-	packageJsonPath: string;
-	packageManager: PackageManagerId;
-	scripts: Partial<Record<"sync" | "sync-rest" | "sync-types", string>>;
-};
 
 const loadCliAddRuntime = () => import("@wp-typia/project-tools/cli-add");
 const loadCliDiagnosticsRuntime = () => import("@wp-typia/project-tools/cli-diagnostics");
@@ -101,176 +92,6 @@ function shouldWrapCliCommandError(options: {
 	return true;
 }
 
-function printBlock(lines: string[], printLine: PrintLine): void {
-	for (const line of lines) {
-		printLine(line);
-	}
-}
-
-function formatExternalLayerSelectHint(option: ExternalLayerSelectOption): string | undefined {
-	const details = [
-		option.description,
-		option.extends.length > 0 ? `extends ${option.extends.join(", ")}` : undefined,
-	].filter((value): value is string => typeof value === "string" && value.length > 0);
-
-	return details.length > 0 ? details.join(" · ") : undefined;
-}
-
-function toExternalLayerPromptOptions(options: ExternalLayerSelectOption[]) {
-	return options.map((option) => ({
-		hint: formatExternalLayerSelectHint(option),
-		label: option.id,
-		value: option.id,
-	}));
-}
-
-export function printCompletionPayload(
-	payload: AlternateBufferCompletionPayload,
-	options: {
-		printLine?: PrintLine;
-		warnLine?: PrintLine;
-	} = {},
-): void {
-	const printLine = options.printLine ?? (console.log as PrintLine);
-	const warnLine = options.warnLine ?? printLine;
-
-	for (const line of payload.preambleLines ?? []) {
-		printLine(line);
-	}
-	for (const warning of payload.warningLines ?? []) {
-		warnLine(`⚠️ ${warning}`);
-	}
-
-	const hasDetails =
-		(payload.summaryLines?.length ?? 0) > 0 ||
-		(payload.nextSteps?.length ?? 0) > 0 ||
-		(payload.optionalLines?.length ?? 0) > 0 ||
-		Boolean(payload.optionalNote);
-	const hasLeadingContext =
-		(payload.preambleLines?.length ?? 0) > 0 ||
-		(payload.warningLines?.length ?? 0) > 0;
-
-	printLine(hasLeadingContext && hasDetails ? `\n${payload.title}` : payload.title);
-	for (const line of payload.summaryLines ?? []) {
-		printLine(line);
-	}
-	if ((payload.nextSteps?.length ?? 0) > 0) {
-		printLine("Next steps:");
-		for (const step of payload.nextSteps ?? []) {
-			printLine(`  ${step}`);
-		}
-	}
-	if ((payload.optionalLines?.length ?? 0) > 0) {
-		printLine(`\n${payload.optionalTitle ?? "Optional:"}`);
-		for (const step of payload.optionalLines ?? []) {
-			printLine(`  ${step}`);
-		}
-	}
-	if (payload.optionalNote) {
-		printLine(`Note: ${payload.optionalNote}`);
-	}
-}
-
-export function buildCreateCompletionPayload(flow: {
-	nextSteps: string[];
-	optionalOnboarding: {
-		note: string;
-		steps: string[];
-	};
-	projectDir: string;
-	result: {
-		selectedVariant?: string | null;
-		variables: {
-			title: string;
-		};
-		warnings: string[];
-	};
-}): AlternateBufferCompletionPayload {
-	return {
-		nextSteps: flow.nextSteps,
-		optionalLines:
-			flow.optionalOnboarding.steps.length > 0 ? flow.optionalOnboarding.steps : undefined,
-		optionalNote:
-			flow.optionalOnboarding.steps.length > 0 ? flow.optionalOnboarding.note : undefined,
-		optionalTitle:
-			flow.optionalOnboarding.steps.length > 0 ? "Optional before first commit:" : undefined,
-		preambleLines: flow.result.selectedVariant
-			? [`Template variant: ${flow.result.selectedVariant}`]
-			: undefined,
-		summaryLines: [`Project directory: ${flow.projectDir}`],
-		title: `✅ Created ${flow.result.variables.title} in ${flow.projectDir}`,
-		warningLines: flow.result.warnings,
-	};
-}
-
-export function buildMigrationCompletionPayload(options: {
-	command: string;
-	lines: string[];
-}): AlternateBufferCompletionPayload {
-	const summaryLines = options.lines.filter((line) => line.trim().length > 0);
-
-	return {
-		summaryLines,
-		title: `✅ Completed wp-typia migrate ${options.command}`,
-	};
-}
-
-function buildAddCompletionPayload(options: {
-	kind: "binding-source" | "block" | "hooked-block" | "pattern" | "variation";
-	projectDir: string;
-	values: Record<string, string>;
-	warnings?: string[];
-}): AlternateBufferCompletionPayload {
-	switch (options.kind) {
-		case "variation":
-			return {
-				summaryLines: [
-					`Variation: ${options.values.variationSlug}`,
-					`Target block: ${options.values.blockSlug}`,
-					`Project directory: ${options.projectDir}`,
-				],
-				title: "✅ Added workspace variation",
-			};
-		case "pattern":
-			return {
-				summaryLines: [
-					`Pattern: ${options.values.patternSlug}`,
-					`Project directory: ${options.projectDir}`,
-				],
-				title: "✅ Added workspace pattern",
-			};
-		case "binding-source":
-			return {
-				summaryLines: [
-					`Binding source: ${options.values.bindingSourceSlug}`,
-					`Project directory: ${options.projectDir}`,
-				],
-				title: "✅ Added binding source",
-			};
-		case "hooked-block":
-			return {
-				summaryLines: [
-					`Block: ${options.values.blockSlug}`,
-					`Anchor: ${options.values.anchorBlockName}`,
-					`Position: ${options.values.position}`,
-					`Project directory: ${options.projectDir}`,
-				],
-				title: "✅ Added blockHooks metadata",
-			};
-		case "block":
-		default:
-			return {
-				summaryLines: [
-					`Blocks: ${options.values.blockSlugs}`,
-					`Template family: ${options.values.templateId}`,
-					`Project directory: ${options.projectDir}`,
-				],
-				title: "✅ Added workspace block",
-				warningLines: options.warnings,
-			};
-	}
-}
-
 function readOptionalStringFlag(
 	flags: Record<string, unknown>,
 	name: string,
@@ -311,131 +132,6 @@ function pushFlag(argv: string[], name: string, value: unknown): void {
 	argv.push(`--${name}`, String(value));
 }
 
-function getSyncRootError(cwd: string): Error {
-	return new Error(
-		`No generated wp-typia project root was found at ${cwd}. Run \`wp-typia sync\` from a scaffolded project or official workspace root.`,
-	);
-}
-
-function inferSyncPackageManager(cwd: string, packageManagerField?: string): PackageManagerId {
-	const field = String(packageManagerField ?? "");
-	if (field.startsWith("bun@")) return "bun";
-	if (field.startsWith("npm@")) return "npm";
-	if (field.startsWith("pnpm@")) return "pnpm";
-	if (field.startsWith("yarn@")) return "yarn";
-
-	if (
-		fs.existsSync(path.join(cwd, "bun.lock")) ||
-		fs.existsSync(path.join(cwd, "bun.lockb"))
-	) {
-		return "bun";
-	}
-	if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
-		return "pnpm";
-	}
-	if (
-		fs.existsSync(path.join(cwd, "yarn.lock")) ||
-		fs.existsSync(path.join(cwd, ".pnp.cjs")) ||
-		fs.existsSync(path.join(cwd, ".pnp.loader.mjs")) ||
-		fs.existsSync(path.join(cwd, ".yarnrc.yml"))
-	) {
-		return "yarn";
-	}
-	if (
-		fs.existsSync(path.join(cwd, "package-lock.json")) ||
-		fs.existsSync(path.join(cwd, "npm-shrinkwrap.json"))
-	) {
-		return "npm";
-	}
-
-	return "npm";
-}
-
-function resolveSyncProjectContext(cwd: string): SyncProjectContext {
-	const packageJsonPath = path.join(cwd, "package.json");
-	if (!fs.existsSync(packageJsonPath)) {
-		throw getSyncRootError(cwd);
-	}
-
-	const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as {
-		packageManager?: string;
-		scripts?: Record<string, unknown>;
-	};
-	const scripts = packageJson.scripts ?? {};
-	const syncScripts = {
-		sync: typeof scripts.sync === "string" ? scripts.sync : undefined,
-		"sync-rest":
-			typeof scripts["sync-rest"] === "string" ? scripts["sync-rest"] : undefined,
-		"sync-types":
-			typeof scripts["sync-types"] === "string" ? scripts["sync-types"] : undefined,
-	} satisfies SyncProjectContext["scripts"];
-
-	if (!syncScripts.sync && !syncScripts["sync-types"]) {
-		throw new Error(
-			`Expected ${packageJsonPath} to define either a \`sync\` or \`sync-types\` script.`,
-		);
-	}
-
-	return {
-		cwd,
-		packageJsonPath,
-		packageManager: inferSyncPackageManager(cwd, packageJson.packageManager),
-		scripts: syncScripts,
-	};
-}
-
-function getPackageManagerRunInvocation(
-	packageManager: PackageManagerId,
-	scriptName: string,
-	extraArgs: string[],
-): { args: string[]; command: string } {
-	switch (packageManager) {
-		case "bun":
-			return { args: ["run", scriptName, ...extraArgs], command: "bun" };
-		case "npm":
-			return {
-				args: ["run", scriptName, ...(extraArgs.length > 0 ? ["--", ...extraArgs] : [])],
-				command: "npm",
-			};
-		case "pnpm":
-			return { args: ["run", scriptName, ...extraArgs], command: "pnpm" };
-		case "yarn":
-			return { args: ["run", scriptName, ...extraArgs], command: "yarn" };
-	}
-}
-
-function runProjectScript(
-	project: SyncProjectContext,
-	scriptName: "sync" | "sync-rest" | "sync-types",
-	extraArgs: string[],
-): void {
-	const script = project.scripts[scriptName];
-	if (!script) {
-		return;
-	}
-
-	const invocation = getPackageManagerRunInvocation(
-		project.packageManager,
-		scriptName,
-		extraArgs,
-	);
-
-	const result = spawnSync(invocation.command, invocation.args, {
-		cwd: project.cwd,
-		shell: process.platform === "win32",
-		stdio: "inherit",
-	});
-
-	if (result.error || result.status !== 0) {
-		throw new Error(
-			`\`${formatRunScript(project.packageManager, scriptName, extraArgs.join(" "))}\` failed.`,
-			{
-				cause: result.error,
-			},
-		);
-	}
-}
-
 const PACKAGE_MANAGER_PROMPT_OPTIONS = [
 	{ label: "npm", value: "npm", hint: "Use npm" },
 	{ label: "pnpm", value: "pnpm", hint: "Use pnpm" },
@@ -844,25 +540,6 @@ export async function loadAddWorkspaceBlockOptions(cwd: string) {
 	return getWorkspaceBlockSelectOptions(workspace.projectDir);
 }
 
-export async function executeSyncCommand({
-	check = false,
-	cwd,
-}: SyncExecutionInput): Promise<void> {
-	const project = resolveSyncProjectContext(cwd);
-	const extraArgs = check ? ["--check"] : [];
-
-	if (project.scripts.sync) {
-		runProjectScript(project, "sync", extraArgs);
-		return;
-	}
-
-	runProjectScript(project, "sync-types", extraArgs);
-
-	if (project.scripts["sync-rest"]) {
-		runProjectScript(project, "sync-rest", extraArgs);
-	}
-}
-
 export async function executeMigrateCommand({
 	command,
 	cwd,