@wp-typia/project-tools 0.24.1 → 0.24.3

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

@@ -14,7 +14,7 @@ export function formatAddHelpText() {
 	wp-typia add variation <name> --block <block-slug> [--dry-run]
 	wp-typia add style <name> --block <block-slug> [--dry-run]
 	wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug> [--dry-run]
-  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>|--tag <tag>...] [--thumbnail-url <url>] [--dry-run]
+  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--tag <tag>...] [--thumbnail-url <url>] [--dry-run]
   wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--from-post-meta|--post-meta <post-meta> [--meta-path <field>]] [--dry-run]
   wp-typia add contract <name> [--type <ExportedTypeName>] [--dry-run]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <${REST_RESOURCE_METHOD_IDS.join(",")}>] [--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--dry-run]
@@ -42,7 +42,7 @@ Notes:
   \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
   \`add style\` registers a Block Styles option for an existing generated block.
   \`add transform\` adds a block-to-block transform into an existing generated block.
-  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\` and records typed catalog metadata in \`PATTERNS\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, and pass \`--tags hero,landing\` or repeat \`--tag hero --tag landing\` to set catalog tags.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\` and records typed catalog metadata in \`PATTERNS\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, pass \`--tags hero,landing\` for a comma-separated tag list, and repeat \`--tag hero --tag landing\` for single tag values.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare an end-to-end bindable attribute on an existing generated block. Pass \`--from-post-meta\` or \`--post-meta\` to generate a source backed by a typed post-meta contract; \`--meta-path\` selects one top-level field as the default binding arg.
   \`add contract\` registers a standalone TypeScript wire contract under \`src/contracts/\` and generates a stable JSON Schema artifact without creating PHP route glue.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`. Use \`--route-pattern\`, \`--permission-callback\`, \`--controller-class\`, and \`--controller-extends\` when an existing WordPress controller or permission model needs to own part of the generated route surface.

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

@@ -1,7 +1,7 @@
-import { PATTERN_CATALOG_SCOPE_IDS, type PatternCatalogScope } from "./pattern-catalog.js";
+import { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, type PatternCatalogScope } from "./pattern-catalog.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
 export type { AddKindId } from "./cli-add-kind-ids.js";
-export { PATTERN_CATALOG_SCOPE_IDS };
+export { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, };
 export type { PatternCatalogScope };
 /**
  * Supported plugin-level REST resource methods accepted by

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

@@ -1,7 +1,7 @@
 import { suggestCloseId } from "./id-suggestions.js";
-import { PATTERN_CATALOG_SCOPE_IDS, } from "./pattern-catalog.js";
+import { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, } from "./pattern-catalog.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
-export { PATTERN_CATALOG_SCOPE_IDS };
+export { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, };
 /**
  * Supported plugin-level REST resource methods accepted by
  * `wp-typia add rest-resource --methods`.

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

@@ -1,9 +1,8 @@
 import path from "node:path";
-import { assertValidGeneratedSlug, normalizeBlockSlug, } from "./cli-add-shared.js";
-import { isValidPatternThumbnailUrl, PATTERN_CATALOG_SCOPE_IDS, } from "./pattern-catalog.js";
+import { normalizeBlockSlug, } from "./cli-add-shared.js";
+import { isValidPatternThumbnailUrl, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, } from "./pattern-catalog.js";
 import { toTitleCase } from "./string-case.js";
 const PATTERN_CONTENT_FILE_ROOT = "src/patterns/";
-const PATTERN_TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
 function assertValidPatternRelativePath(label, value, usage) {
     const normalizedPath = value.trim().replace(/\\/gu, "/");
     if (normalizedPath.length === 0 ||
@@ -41,11 +40,24 @@ function resolvePatternScope(scope) {
     }
     throw new Error(`Pattern scope must be one of: ${PATTERN_CATALOG_SCOPE_IDS.join(", ")}.`);
 }
-function normalizeOptionalSlug(label, value, usage) {
+/**
+ * Normalize and validate a raw pattern section role before catalog generation.
+ * Non-empty values are normalized with normalizeBlockSlug; valid roles start
+ * with a lowercase letter and then use lowercase letters, numbers, or hyphens.
+ *
+ * @param value Raw section-role input from CLI or programmatic callers.
+ * @returns Normalized role slug, or undefined when the input is empty.
+ * @throws When the normalized role does not match the shared section-role pattern.
+ */
+function normalizePatternSectionRole(value) {
     if (value === undefined || value.trim() === "") {
         return undefined;
     }
-    return assertValidGeneratedSlug(label, normalizeBlockSlug(value), usage);
+    const sectionRole = normalizeBlockSlug(value);
+    if (!PATTERN_SECTION_ROLE_PATTERN.test(sectionRole)) {
+        throw new Error("Pattern section role must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens. Section roles apply only with `--scope section`.");
+    }
+    return sectionRole;
 }
 function normalizePatternTags(tags) {
     const rawTags = typeof tags === "string"
@@ -91,12 +103,12 @@ function resolvePatternContentFile(patternSlug, patternScope, contentFile) {
  */
 export function resolvePatternCatalogOptions(patternSlug, options) {
     const patternScope = resolvePatternScope(options.patternScope);
-    const sectionRole = normalizeOptionalSlug("Pattern section role", options.sectionRole, "wp-typia add pattern <name> --scope section --section-role <role>");
+    const sectionRole = normalizePatternSectionRole(options.sectionRole);
     if (patternScope === "section" && !sectionRole) {
-        throw new Error("`wp-typia add pattern --scope section` requires --section-role <role>.");
+        throw new Error("`wp-typia add pattern --scope section` requires --section-role <role> because section-scoped patterns need a typed catalog section role.");
     }
     if (patternScope !== "section" && sectionRole) {
-        throw new Error("`--section-role` requires `--scope section`.");
+        throw new Error("`--section-role` only applies with `--scope section`. Use `--scope section --section-role <role>` or omit `--section-role` for full patterns.");
     }
     const title = options.catalogTitle && options.catalogTitle.trim() !== ""
         ? options.catalogTitle.trim()

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

@@ -7,7 +7,7 @@
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, PATTERN_CATALOG_SCOPE_IDS, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, normalizeBlockSlug, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export type { AddBlockTemplateId, AddKindId, EditorPluginSlotId, PatternCatalogScope, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddCoreVariationCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddIntegrationEnvCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";

package/dist/runtime/cli-add.js

@@ -7,7 +7,7 @@
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, PATTERN_CATALOG_SCOPE_IDS, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, normalizeBlockSlug, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddCoreVariationCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddIntegrationEnvCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
 export { getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, } from "./workspace-inventory.js";

package/dist/runtime/cli-help.js

@@ -27,7 +27,7 @@ export function formatHelpText() {
   wp-typia add variation <name> --block <block-slug>
   wp-typia add style <name> --block <block-slug>
   wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug>
-  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>|--tag <tag>...] [--thumbnail-url <url>]
+  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--tag <tag>...] [--thumbnail-url <url>]
   wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--from-post-meta|--post-meta <post-meta> [--meta-path <field>]]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <method[,method...]>]
   wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>|--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--secret-field <field>] [--secret-state-field|--secret-has-value-field <field>] [--secret-preserve-on-empty <true|false>]
@@ -68,7 +68,7 @@ Notes:
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
   \`add style\` registers a Block Styles option for an existing generated block.
   \`add transform\` adds a block-to-block transform into an existing generated block.
-  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, and pass \`--tags hero,landing\` or repeat \`--tag hero --tag landing\` to set catalog tags.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, pass \`--tags hero,landing\` for a comma-separated tag list, and repeat \`--tag hero --tag landing\` for single tag values.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare a bindable generated-block attribute. Pass \`--from-post-meta\` or \`--post-meta\` to back the source from a typed post-meta contract and \`--meta-path\` to choose its default top-level field.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`.
   \`add rest-resource --manual\` tracks an external/provider REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files while still allowing route-owner metadata such as permission callbacks and controller classes. Settings contracts can add \`--secret-field\` plus \`--secret-preserve-on-empty\` to model write-only credentials and preserve blank submissions.

package/dist/runtime/cli-scaffold-emission.d.ts

@@ -0,0 +1,124 @@
+import { scaffoldProject } from "./scaffold.js";
+import type { PackageManagerId } from "./package-managers.js";
+import type { ScaffoldProgressEvent } from "./scaffold.js";
+type ScaffoldProjectOptions = Parameters<typeof scaffoldProject>[0];
+/**
+ * Dependency installation hook accepted by scaffold emission.
+ */
+export type ScaffoldInstallDependencies = ScaffoldProjectOptions["installDependencies"];
+/**
+ * Dry-run metadata returned after rendering a scaffold into a preview directory.
+ */
+export interface ScaffoldDryRunPlan {
+    /**
+     * Whether dependency installation would run or is skipped by --no-install.
+     */
+    dependencyInstall: "skipped-by-flag" | "would-install";
+    /**
+     * Sorted project-relative paths that would be written by the scaffold.
+     */
+    files: string[];
+}
+/**
+ * Normalized scaffold emission options shared by real and dry-run flows.
+ */
+export interface ScaffoldEmissionOptions {
+    /**
+     * Whether an existing target directory may be reused.
+     */
+    allowExistingDir: boolean;
+    /**
+     * Optional alternate render target specification for supported templates.
+     */
+    alternateRenderTargets?: ScaffoldProjectOptions["alternateRenderTargets"];
+    /**
+     * Resolved scaffold answers used by template variable generation.
+     */
+    answers: ScaffoldProjectOptions["answers"];
+    /**
+     * Caller working directory used to resolve relative template inputs.
+     */
+    cwd: string;
+    /**
+     * Persistence storage mode for templates that support storage options.
+     */
+    dataStorageMode?: ScaffoldProjectOptions["dataStorageMode"];
+    /**
+     * Optional public root id selected from an external layer package.
+     */
+    externalLayerId?: string;
+    /**
+     * Optional external layer source package, path, or locator.
+     */
+    externalLayerSource?: string;
+    /**
+     * Display label for the external layer source before path resolution.
+     */
+    externalLayerSourceLabel?: string;
+    /**
+     * Optional dependency installer override used by tests and callers.
+     */
+    installDependencies?: ScaffoldProjectOptions["installDependencies"];
+    /**
+     * Whether generated projects should skip dependency installation.
+     */
+    noInstall: boolean;
+    /**
+     * Optional callback for scaffold progress events.
+     */
+    onProgress?: ((event: ScaffoldProgressEvent) => void | Promise<void>) | undefined;
+    /**
+     * Package manager used for generated metadata and follow-up commands.
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Persistence access policy for templates that support server storage.
+     */
+    persistencePolicy?: ScaffoldProjectOptions["persistencePolicy"];
+    /**
+     * Optional create profile that enables preset groups such as plugin QA.
+     */
+    profile?: ScaffoldProjectOptions["profile"];
+    /**
+     * Absolute target directory for the generated project.
+     */
+    projectDir: string;
+    /**
+     * Resolved template id or external template locator to render.
+     */
+    templateId: string;
+    /**
+     * Optional built-in or external template variant id.
+     */
+    variant?: string;
+    /**
+     * Whether migration UI support should be added when supported.
+     */
+    withMigrationUi: boolean;
+    /**
+     * Whether scaffold test presets should be emitted.
+     */
+    withTestPreset: boolean;
+    /**
+     * Whether local wp-env support should be emitted.
+     */
+    withWpEnv: boolean;
+}
+/**
+ * Emit scaffold files into the target project directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns The scaffold result produced by the runtime renderer.
+ */
+export declare function emitScaffoldProject(options: ScaffoldEmissionOptions): Promise<Awaited<ReturnType<typeof scaffoldProject>>>;
+/**
+ * Build a dry-run scaffold plan without mutating the requested target directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns Preview metadata and the scaffold result from the temp render.
+ */
+export declare function buildScaffoldDryRunPlan(options: ScaffoldEmissionOptions): Promise<{
+    plan: ScaffoldDryRunPlan;
+    result: Awaited<ReturnType<typeof scaffoldProject>>;
+}>;
+export {};

package/dist/runtime/cli-scaffold-emission.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { assertDryRunTargetDirectoryReady, listRelativeProjectFiles, } from "./cli-scaffold-files.js";
+import { scaffoldProject } from "./scaffold.js";
+import { createManagedTempRoot } from "./temp-roots.js";
+/**
+ * Emit scaffold files into the target project directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns The scaffold result produced by the runtime renderer.
+ */
+export async function emitScaffoldProject(options) {
+    return scaffoldProject(options);
+}
+/**
+ * Build a dry-run scaffold plan without mutating the requested target directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns Preview metadata and the scaffold result from the temp render.
+ */
+export async function buildScaffoldDryRunPlan(options) {
+    await assertDryRunTargetDirectoryReady(options.projectDir, options.allowExistingDir);
+    const { path: tempRoot, cleanup } = await createManagedTempRoot("wp-typia-scaffold-plan-");
+    const previewProjectDir = path.join(tempRoot, "preview-project");
+    try {
+        const result = await emitScaffoldProject({
+            ...options,
+            allowExistingDir: false,
+            noInstall: true,
+            projectDir: previewProjectDir,
+        });
+        const files = await listRelativeProjectFiles(previewProjectDir);
+        return {
+            plan: {
+                dependencyInstall: options.noInstall
+                    ? "skipped-by-flag"
+                    : "would-install",
+                files,
+            },
+            result,
+        };
+    }
+    finally {
+        await cleanup();
+    }
+}

package/dist/runtime/cli-scaffold-files.d.ts

@@ -0,0 +1,22 @@
+/**
+ * List every file emitted under a scaffold project using POSIX-style paths.
+ *
+ * @param rootDir Root project directory to scan recursively.
+ * @returns Sorted relative file paths suitable for dry-run preview output.
+ */
+export declare function listRelativeProjectFiles(rootDir: string): Promise<string[]>;
+/**
+ * Ensure a dry-run target would be legal before rendering into a temp preview.
+ *
+ * @param projectDir Real target project directory requested by the user.
+ * @param allowExistingDir Whether existing target directories are allowed.
+ * @throws Error when the target exists, is non-empty, and is not allowed.
+ */
+export declare function assertDryRunTargetDirectoryReady(projectDir: string, allowExistingDir: boolean): Promise<void>;
+/**
+ * Read script names from the package manifest emitted by a scaffold run.
+ *
+ * @param projectDir Generated project directory containing package.json.
+ * @returns Script names, or undefined when the manifest is absent or invalid.
+ */
+export declare function readGeneratedPackageScripts(projectDir: string): Promise<string[] | undefined>;

package/dist/runtime/cli-scaffold-files.js

@@ -0,0 +1,69 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.js";
+import { pathExists } from "./fs-async.js";
+import { readJsonFile } from "./json-utils.js";
+/**
+ * List every file emitted under a scaffold project using POSIX-style paths.
+ *
+ * @param rootDir Root project directory to scan recursively.
+ * @returns Sorted relative file paths suitable for dry-run preview output.
+ */
+export async function listRelativeProjectFiles(rootDir) {
+    const relativeFiles = [];
+    async function visit(currentDir) {
+        const entries = await fsp.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolutePath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolutePath);
+                continue;
+            }
+            relativeFiles.push(path
+                .relative(rootDir, absolutePath)
+                .replace(path.sep === "\\" ? /\\/gu : /\//gu, "/"));
+        }
+    }
+    await visit(rootDir);
+    return relativeFiles.sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Ensure a dry-run target would be legal before rendering into a temp preview.
+ *
+ * @param projectDir Real target project directory requested by the user.
+ * @param allowExistingDir Whether existing target directories are allowed.
+ * @throws Error when the target exists, is non-empty, and is not allowed.
+ */
+export async function assertDryRunTargetDirectoryReady(projectDir, allowExistingDir) {
+    if (!(await pathExists(projectDir)) || allowExistingDir) {
+        return;
+    }
+    const entries = await fsp.readdir(projectDir);
+    if (entries.length > 0) {
+        throw new Error(formatNonEmptyTargetDirectoryError(projectDir));
+    }
+}
+/**
+ * Read script names from the package manifest emitted by a scaffold run.
+ *
+ * @param projectDir Generated project directory containing package.json.
+ * @returns Script names, or undefined when the manifest is absent or invalid.
+ */
+export async function readGeneratedPackageScripts(projectDir) {
+    try {
+        const parsedPackageJson = await readJsonFile(path.join(projectDir, "package.json"), {
+            context: "generated package manifest",
+        });
+        const scripts = parsedPackageJson.scripts &&
+            typeof parsedPackageJson.scripts === "object" &&
+            !Array.isArray(parsedPackageJson.scripts)
+            ? parsedPackageJson.scripts
+            : {};
+        return Object.entries(scripts)
+            .filter(([, value]) => typeof value === "string")
+            .map(([scriptName]) => scriptName);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runtime/cli-scaffold-output.d.ts

@@ -0,0 +1,79 @@
+import type { PackageManagerId } from "./package-managers.js";
+/**
+ * Inputs used to build CLI next-step commands after scaffolding succeeds.
+ */
+export interface ScaffoldNextStepsOptions {
+    /**
+     * Whether install instructions should be printed because install was skipped.
+     */
+    noInstall: boolean;
+    /**
+     * Package manager used to format install and run commands.
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Absolute scaffold target directory.
+     */
+    projectDir: string;
+    /**
+     * Project path exactly as provided to the CLI.
+     */
+    projectInput: string;
+    /**
+     * Resolved template id used to choose the primary development script.
+     */
+    templateId: string;
+}
+/**
+ * Inputs used to compute optional onboarding guidance after scaffolding.
+ */
+export interface ScaffoldOptionalOnboardingOptions {
+    /**
+     * Script names discovered from the generated package manifest.
+     */
+    availableScripts?: string[];
+    /**
+     * Package manager used to format optional commands.
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Resolved template id used to select template-specific guidance.
+     */
+    templateId: string;
+    /**
+     * Whether compound persistence support is present in generated variables.
+     */
+    compoundPersistenceEnabled?: boolean;
+}
+/**
+ * User-facing optional onboarding copy and command list.
+ */
+export interface OptionalOnboardingGuidance {
+    /**
+     * Full note shown in the detailed completion output.
+     */
+    note: string;
+    /**
+     * Short note shown in compact completion output.
+     */
+    shortNote: string;
+    /**
+     * Optional follow-up commands to show after next steps.
+     */
+    steps: string[];
+}
+/**
+ * Build the printed next-step commands for a scaffolded project.
+ *
+ * @param options Project location and package-manager details used to format
+ * next-step commands.
+ * @returns Ordered shell commands shown after scaffolding succeeds.
+ */
+export declare function getNextSteps({ projectInput, projectDir, packageManager, noInstall, templateId, }: ScaffoldNextStepsOptions): string[];
+/**
+ * Compute optional onboarding guidance shown after scaffolding completes.
+ *
+ * @param options Package-manager and template context for optional guidance.
+ * @returns Optional onboarding note and step list.
+ */
+export declare function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled, }: ScaffoldOptionalOnboardingOptions): OptionalOnboardingGuidance;

package/dist/runtime/cli-scaffold-output.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
+import { getOptionalOnboardingNote, getOptionalOnboardingShortNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
+import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
+function quoteShellValue(value) {
+    if (!value.startsWith("-") &&
+        /^[A-Za-z0-9._/@:-]+(?:\/[A-Za-z0-9._@:-]+)*$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+/**
+ * Build the printed next-step commands for a scaffolded project.
+ *
+ * @param options Project location and package-manager details used to format
+ * next-step commands.
+ * @returns Ordered shell commands shown after scaffolding succeeds.
+ */
+export function getNextSteps({ projectInput, projectDir, packageManager, noInstall, templateId, }) {
+    const cdTarget = path.isAbsolute(projectInput) ? projectDir : projectInput;
+    const steps = [`cd ${quoteShellValue(cdTarget)}`];
+    if (noInstall) {
+        steps.push(formatInstallCommand(packageManager));
+    }
+    steps.push(formatRunScript(packageManager, getPrimaryDevelopmentScript(templateId)));
+    return steps;
+}
+/**
+ * Compute optional onboarding guidance shown after scaffolding completes.
+ *
+ * @param options Package-manager and template context for optional guidance.
+ * @returns Optional onboarding note and step list.
+ */
+export function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled = false, }) {
+    return {
+        note: getOptionalOnboardingNote(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
+        shortNote: getOptionalOnboardingShortNote(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
+        steps: getOptionalOnboardingSteps(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
+    };
+}

package/dist/runtime/cli-scaffold-validation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Validate the project directory argument before template resolution.
+ *
+ * @param projectInput Raw project directory input from the CLI.
+ * @throws Error when the input is empty or points at the current/parent directory.
+ */
+export declare function validateCreateProjectInput(projectInput: string): void;
+/**
+ * Collect warnings for project directory names that are awkward in shells.
+ *
+ * @param projectDir Absolute target project directory.
+ * @returns User-facing warning messages for non-fatal directory concerns.
+ */
+export declare function collectProjectDirectoryWarnings(projectDir: string): string[];
+/**
+ * Determine whether a template should resolve persistence-related options.
+ *
+ * @param templateId Resolved template id.
+ * @param options Explicit persistence flags provided by the caller.
+ * @returns True when persistence defaults or prompts should be applied.
+ */
+export declare function templateUsesPersistenceSettings(templateId: string, options: {
+    dataStorageMode?: string;
+    persistencePolicy?: string;
+}): boolean;
+/**
+ * Collect warnings for flags that do not apply to the selected template.
+ *
+ * @param options Template id and raw CLI flags that may be ignored.
+ * @returns User-facing warnings for non-fatal capability mismatches.
+ */
+export declare function collectTemplateCapabilityWarnings(options: {
+    queryPostType?: string;
+    templateId: string;
+    withMigrationUi?: boolean;
+}): string[];
+/**
+ * Validate create flags that depend on the selected template capability set.
+ *
+ * @param options Raw create flags plus the resolved template id.
+ * @throws Error when a flag is unsupported for the selected template.
+ */
+export declare function validateCreateFlagContract(options: {
+    alternateRenderTargets?: string;
+    dataStorageMode?: string;
+    innerBlocksPreset?: string;
+    persistencePolicy?: string;
+    templateId: string;
+    variant?: string;
+}): void;
+/**
+ * Resolve an optional string selection from explicit input, prompts, or defaults.
+ *
+ * @param options Selection configuration including allowed values and prompt hooks.
+ * @returns The resolved value, or undefined when resolution is disabled.
+ * @throws Error when an explicit value is not in the allowed set.
+ */
+export declare function resolveOptionalSelection<T extends string>({ defaultValue, explicitValue, isInteractive, isValue, label, allowedValues, select, shouldResolve, yes, }: {
+    defaultValue: T;
+    explicitValue?: string;
+    isInteractive: boolean;
+    isValue: (input: string) => input is T;
+    label: string;
+    allowedValues: readonly T[];
+    select?: () => Promise<T>;
+    shouldResolve?: boolean;
+    yes: boolean;
+}): Promise<T | undefined>;
+/**
+ * Resolve an optional boolean flag from explicit input, prompts, or defaults.
+ *
+ * @param options Boolean selection configuration and optional prompt hook.
+ * @returns The resolved boolean value.
+ */
+export declare function resolveOptionalBooleanFlag({ defaultValue, disabled, explicitValue, isInteractive, select, yes, }: {
+    defaultValue?: boolean;
+    disabled?: boolean;
+    explicitValue?: boolean;
+    isInteractive: boolean;
+    select?: () => Promise<boolean>;
+    yes: boolean;
+}): Promise<boolean>;