@ykdz/template 0.0.35 → 0.0.37

package/dist/application.js

@@ -1,57 +1,35 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { builtInPresetRegistry, createGenerationContext, planGeneratedRepositoryInitialization, planGeneratedRepositoryPackageAddition, templateSources, } from "#template-builtin-presets";
-import { assertProjectBlueprintV2, validateProjectBlueprintV2, } from "#template-core/project-blueprint-v2";
-import { reconcileAndApplyProjectProjections, } from "#template-core/project-projection";
-import { renderNewProject } from "#template-core/renderer";
-import { resolveToolchainVersions, } from "#template-core/toolchain-resolution";
-export function normalizeNpmScope(value) {
-    const scope = value.startsWith("@") ? value.slice(1) : value;
-    if (value !== value.trim() || !/^[a-z0-9][a-z0-9._-]*$/.test(scope)) {
-        throw new Error("--scope must be a valid npm scope without whitespace");
-    }
-    return scope;
-}
-export function formatPresetCatalog() {
-    return [
-        "Built-in presets",
-        "",
-        ...formatRows(builtInPresetRegistry
-            .all()
-            .map((definition) => [
-            definition.metadata.name,
-            `${definition.metadata.title} - ${definition.metadata.description}`,
-        ])),
-    ].join("\n");
-}
-function toolchainSourceFromEnv(env) {
-    const source = env.TEMPLATE_TOOLCHAIN_RESOLUTION;
-    return source === "online" || source === "bundled-fallback"
-        ? source
-        : undefined;
-}
-async function resolveToolchain(env) {
-    return await resolveToolchainVersions({
-        source: toolchainSourceFromEnv(env),
-        nodeReleaseIndexUrl: env.TEMPLATE_TOOLCHAIN_NODE_RELEASE_INDEX_URL,
-        pnpmRegistryUrl: env.TEMPLATE_TOOLCHAIN_PNPM_REGISTRY_URL,
-    });
+import { builtInPresetRegistry, prepareGeneratedRepositoryPackageAddition, validateGeneratedRepositoryInitializationInput, prepareGeneratedRepositoryInitialization, templateSources, } from "@ykdz/template-builtin-presets";
+import { validateProjectBlueprint } from "@ykdz/template-core/project-blueprint";
+import { reconcileAndApplyProjectProjections, materializeProjectProjection, } from "@ykdz/template-core/project-projection";
+import { releaseToolchainSnapshot } from "@ykdz/template-core/release-toolchain-snapshot";
+import { renderNewProject } from "@ykdz/template-core/renderer";
+export function listPresetCatalog() {
+    return {
+        schemaVersion: 1,
+        command: "presets",
+        status: "success",
+        presets: builtInPresetRegistry.all().map((definition) => ({
+            name: definition.metadata.name,
+            title: definition.metadata.title,
+            description: definition.metadata.description,
+        })),
+    };
 }
-function toolchainReport(toolchain) {
+/**
+ * 初始化结果如实报告随 CLI 发版的不可变工具链快照：没有在线解析来源，也没有回退诊断。
+ */
+function toolchainReport() {
     return {
-        nodeLtsMajor: toolchain.nodeLtsMajor.value,
-        packageManagerPin: toolchain.packageManagerPin.value,
-        source: toolchain.source,
-        diagnostics: toolchain.diagnostics,
+        nodeVersion: releaseToolchainSnapshot.nodeVersion,
+        packageManagerPin: releaseToolchainSnapshot.packageManagerPin,
     };
 }
 function formatRows(rows) {
     const width = Math.max(...rows.map(([label]) => `${label}:`.length));
     return rows.map(([label, value]) => `  ${`${label}:`.padEnd(width)} ${value}`);
 }
-function formatLineSpan(span) {
-    return `line ${span.startLine} (${span.lineCount} line${span.lineCount === 1 ? "" : "s"})`;
-}
 function packageAdditionConflict(conflict) {
     const { before, current, after, ...details } = conflict;
     return {
@@ -59,192 +37,314 @@ function packageAdditionConflict(conflict) {
         context: { before, current, after },
     };
 }
-export function renderPackageAdditionResult(result, options, preset) {
-    if (result.status === "conflict") {
-        return [
-            "Package Addition conflict",
-            "",
-            ...result.conflicts.flatMap((conflict) => [
-                `  ${conflict.path} (${conflict.driver})`,
-                ...(conflict.location === undefined
-                    ? []
-                    : [`    Location: ${conflict.location || "<document root>"}`]),
-                ...(conflict.region === undefined
-                    ? []
-                    : [
-                        `    Region: Before ${formatLineSpan(conflict.region.before)}; Current ${formatLineSpan(conflict.region.current)}; After ${formatLineSpan(conflict.region.after)}`,
-                    ]),
-                ...(conflict.attribute === undefined
-                    ? []
-                    : [`    Attribute: ${conflict.attribute}`]),
-                `    Reason: ${conflict.reason}`,
-                `    Before: ${conflict.context.before}`,
-                `    Current: ${conflict.context.current}`,
-                `    After: ${conflict.context.after}`,
-            ]),
-        ].join("\n");
+export async function validateBlueprintFile(filePath, runtime) {
+    const resolvedPath = path.resolve(runtime.cwd, filePath);
+    let source;
+    try {
+        source = await readFile(resolvedPath, "utf8");
     }
-    return [
-        result.dryRun ? "Package Addition preview" : "Added package",
-        "",
-        ...formatRows([
-            ["Preset", preset],
-            ["Name", options.name],
-        ]),
-        "",
-        ...(result.actions.length === 0
-            ? ["No changes"]
-            : result.actions.map((action) => `  ${action.action} ${action.path} (${action.driver})`)),
-    ].join("\n");
-}
-async function readBlueprint(filePath) {
-    const value = JSON.parse(await readFile(filePath, "utf8"));
-    if (typeof value === "object" &&
-        value !== null &&
-        "schemaVersion" in value &&
-        value.schemaVersion === 1) {
-        throw new Error("Unsupported Local Template Metadata: Blueprint version 1 is not supported");
+    catch (error) {
+        return readBlueprintFailure(resolvedPath, error);
     }
-    return assertProjectBlueprintV2(value);
-}
-export async function validateBlueprintFile(filePath, runtime) {
-    const value = JSON.parse(await readFile(path.resolve(runtime.cwd, filePath), "utf8"));
-    if (typeof value === "object" &&
-        value !== null &&
-        "schemaVersion" in value &&
-        value.schemaVersion === 1) {
-        throw new Error("Unsupported Local Template Metadata: Blueprint version 1 is not supported");
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        return {
+            schemaVersion: 1,
+            command: "blueprint validate",
+            status: "operation-failure",
+            code: "OPERATION_BLUEPRINT_PARSE_FAILED",
+            path: resolvedPath,
+            reason: "invalid-json",
+            error: {
+                message: "Blueprint JSON 格式无效。",
+                suggestion: "修正 JSON 语法后重新验证；若文件来源不明确，请人工处理。",
+            },
+        };
     }
-    const result = validateProjectBlueprintV2(value);
+    const result = validateProjectBlueprint(value);
     if (!result.ok) {
-        throw new Error(result.issues
-            .map((issue) => `${issue.path}: ${issue.message}`)
-            .join("\n"));
+        return {
+            schemaVersion: 1,
+            command: "blueprint validate",
+            status: "invalid",
+            code: "BLUEPRINT_INVALID",
+            path: resolvedPath,
+            issues: result.issues,
+        };
     }
-    return "Blueprint is valid";
+    return {
+        schemaVersion: 1,
+        command: "blueprint validate",
+        status: "success",
+        path: resolvedPath,
+    };
 }
-function deriveExistingPackageScope(blueprint) {
-    const scopes = new Set();
-    for (const definition of blueprint.packages) {
-        const match = definition.name.match(/^@([^/]+)\//);
-        if (!match?.[1]) {
-            throw new Error(`Package Addition requires a scoped Package Definition: ${definition.name}`);
-        }
-        scopes.add(match[1]);
-    }
-    if (scopes.size !== 1) {
-        throw new Error(`Package Addition requires exactly one existing npm scope; found ${[...scopes].join(", ") || "none"}`);
-    }
-    return [...scopes][0];
+function readBlueprintFailure(filePath, error) {
+    const errorCode = typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+    const [reason, message, suggestion] = errorCode === "ENOENT"
+        ? ["not-found", "找不到 Blueprint 文件。", "检查路径是否正确后重新验证。"]
+        : errorCode === "EACCES" || errorCode === "EPERM"
+            ? [
+                "permission-denied",
+                "没有读取 Blueprint 文件的权限。",
+                "授予读取权限后重新验证；若权限归属不明确，请人工处理。",
+            ]
+            : errorCode === "EISDIR" || errorCode === "ENOTDIR"
+                ? [
+                    "not-a-file",
+                    "Blueprint 目标不是可读取的文件。",
+                    "提供一个可读取的 Blueprint JSON 文件路径后重新验证。",
+                ]
+                : [
+                    "unreadable",
+                    "无法读取 Blueprint 文件。",
+                    "检查路径、文件权限和挂载状态后重试；若需要其他访问权限，请人工处理。",
+                ];
+    return {
+        schemaVersion: 1,
+        command: "blueprint validate",
+        status: "operation-failure",
+        code: "OPERATION_BLUEPRINT_READ_FAILED",
+        path: filePath,
+        reason,
+        error: { message, suggestion },
+    };
 }
-export async function runInit(options, runtime) {
-    const definition = builtInPresetRegistry.require(options.preset);
-    const toolchain = await resolveToolchain(runtime.env);
-    const context = createGenerationContext({
-        targetDir: path.resolve(runtime.cwd, options.dir),
-        ...(options.scope ? { scope: normalizeNpmScope(options.scope) } : {}),
-        toolchain: {
-            nodeLtsMajor: toolchain.nodeLtsMajor.value,
-            packageManagerPin: toolchain.packageManagerPin.value,
+function initOperationFailure(options) {
+    const phase = options.phase === "preset"
+        ? "预设准备"
+        : options.phase === "planning"
+            ? "生成规划"
+            : options.phase === "preflight"
+                ? "生成预检"
+                : options.phase === "materialization"
+                    ? "生成物料化"
+                    : "目标目录渲染";
+    return {
+        schemaVersion: 1,
+        command: "init",
+        status: "operation-failure",
+        code: "OPERATION_INIT_FAILED",
+        phase: options.phase,
+        targetDir: options.targetDir,
+        error: {
+            message: `${phase}失败。`,
+            suggestion: "检查目标目录与运行环境后重试；若问题持续发生，请人工处理。",
         },
+    };
+}
+export async function runInit(options, runtime) {
+    if (!options.dryRun &&
+        !options.yes &&
+        (options.json || !runtime.tty.stdin || !runtime.tty.stdout)) {
+        return {
+            schemaVersion: 1,
+            command: "init",
+            status: "usage-error",
+            code: "USAGE_INIT_INVALID",
+            targetDir: options.dir,
+            issues: [{ code: "NON_INTERACTIVE_CONFIRMATION_REQUIRED" }],
+        };
+    }
+    const targetDir = path.resolve(runtime.cwd, options.dir);
+    const overrides = (options.name ?? options.path ?? options.scope) === undefined
+        ? undefined
+        : {
+            ...(options.name === undefined ? {} : { name: options.name }),
+            ...(options.path === undefined ? {} : { path: options.path }),
+            ...(options.scope === undefined ? {} : { scope: options.scope }),
+        };
+    const input = validateGeneratedRepositoryInitializationInput({
+        preset: options.preset,
+        targetDir,
+        ...(overrides === undefined ? {} : { overrides }),
+    });
+    if (input.status === "input-invalid") {
+        return {
+            schemaVersion: 1,
+            command: "init",
+            status: "usage-error",
+            code: "USAGE_INIT_INVALID",
+            targetDir: options.dir,
+            issues: input.issues,
+        };
+    }
+    const preparation = prepareGeneratedRepositoryInitialization({
+        preset: options.preset,
+        targetDir,
+        ...(overrides === undefined ? {} : { overrides }),
     });
-    const plan = planGeneratedRepositoryInitialization({ definition, context });
+    if (preparation.status === "input-invalid") {
+        return {
+            schemaVersion: 1,
+            command: "init",
+            status: "usage-error",
+            code: "USAGE_INIT_INVALID",
+            targetDir: options.dir,
+            issues: preparation.issues,
+        };
+    }
+    if (preparation.status === "operation-failure") {
+        return initOperationFailure({
+            phase: preparation.phase,
+            targetDir: options.dir,
+        });
+    }
+    const { plan, resolved, publicationSetup } = preparation;
+    const operations = [
+        ...plan.operations,
+        ...(options.todo
+            ? [
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.foundation,
+                    from: "TODO.md.template",
+                    to: "TODO.md",
+                    replacements: {
+                        NEXT_STEPS: plan.nextStepInstructions
+                            .map((instruction, index) => `${index + 1}. \`${instruction.display}\``)
+                            .join("\n"),
+                    },
+                },
+            ]
+            : []),
+    ];
+    try {
+        await materializeProjectProjection({
+            operations,
+            reconciliation: plan.reconciliation,
+        });
+    }
+    catch {
+        return initOperationFailure({
+            phase: "materialization",
+            targetDir: options.dir,
+        });
+    }
     const output = {
+        schemaVersion: 1,
         command: "init",
+        status: "success",
         dryRun: options.dryRun,
         targetDir: options.dir,
+        resolved,
         blueprint: plan.blueprint,
         generationRecord: plan.generationRecord,
-        toolchain: toolchainReport(toolchain),
+        toolchain: toolchainReport(),
         nextSteps: plan.nextStepInstructions,
+        publicationSetup,
         followUpDocument: {
             enabled: options.todo,
-            path: options.todo ? "TODO.md" : undefined,
+            ...(options.todo ? { path: "TODO.md" } : {}),
         },
     };
     if (options.dryRun)
-        return JSON.stringify(output, null, 2);
-    if (!options.yes &&
-        (options.json || !runtime.tty.stdin || !runtime.tty.stdout)) {
-        throw new Error("Non-interactive init requires --yes");
-    }
+        return output;
     if (!options.yes &&
         !(await runtime.confirmation.confirm({
             message: [
-                "Planned project",
+                "计划生成的项目",
                 "",
                 ...formatRows([
-                    ["Target", options.dir],
-                    ["Packages", String(plan.blueprint.packages.length)],
+                    ["预设", resolved.preset],
+                    ["名称", resolved.packages.map(({ name }) => name).join(", ")],
+                    [
+                        "路径",
+                        resolved.packages
+                            .map(({ path: packagePath }) => packagePath)
+                            .join(", "),
+                    ],
+                    ["Scope", resolved.scope],
+                    ["目标", options.dir],
+                    ["包数量", String(plan.blueprint.packages.length)],
                 ]),
             ].join("\n"),
-            prompt: "Generate this project? [y/N] ",
+            prompt: "生成这个项目？[y/N] ",
         }))) {
-        throw new Error("Init cancelled");
+        return {
+            schemaVersion: 1,
+            command: "init",
+            status: "cancelled",
+            code: "CANCELLED",
+            targetDir: options.dir,
+        };
     }
-    await renderNewProject({
-        targetRoot: path.resolve(runtime.cwd, options.dir),
-        operations: [
-            ...plan.operations,
-            ...(options.todo
-                ? [
-                    {
-                        kind: "writeTextTemplate",
-                        source: templateSources.foundation,
-                        from: "TODO.md.template",
-                        to: "TODO.md",
-                        replacements: {
-                            NEXT_STEPS: plan.nextStepInstructions
-                                .map((instruction, index) => `${index + 1}. \`${instruction.display}\``)
-                                .join("\n"),
-                        },
-                    },
-                ]
-                : []),
-        ],
-    });
-    if (options.json)
-        return JSON.stringify(output, null, 2);
-    return [
-        "Initialized project",
-        "",
-        ...formatRows([
-            ["Preset", definition.metadata.name],
-            ["Target", options.dir],
-        ]),
-        "",
-        "Next steps",
-        "",
-        ...plan.nextStepInstructions.map((instruction, index) => `  ${index + 1}. ${instruction.display}`),
-    ].join("\n");
+    try {
+        await renderNewProject({
+            targetRoot: path.resolve(runtime.cwd, options.dir),
+            operations,
+        });
+    }
+    catch {
+        return initOperationFailure({ phase: "render", targetDir: options.dir });
+    }
+    return output;
 }
 export async function runAddPackage(options, runtime) {
-    const blueprint = await readBlueprint(path.join(runtime.cwd, ".template/blueprint.json"));
-    const toolchain = await resolveToolchain(runtime.env);
-    const definition = builtInPresetRegistry.require(options.preset);
-    const context = createGenerationContext({
-        targetDir: runtime.cwd,
-        scope: deriveExistingPackageScope(blueprint),
-        toolchain: {
-            nodeLtsMajor: toolchain.nodeLtsMajor.value,
-            packageManagerPin: toolchain.packageManagerPin.value,
-        },
-    });
-    const plan = planGeneratedRepositoryPackageAddition({
-        definition,
-        context,
-        blueprint,
+    const preparation = prepareGeneratedRepositoryPackageAddition({
+        repositoryRoot: runtime.cwd,
+        preset: options.preset,
         packageLeafName: options.name,
-        ...(options.path ? { packagePath: options.path } : {}),
-        ...(options.linkFrom.length > 0 ? { linkFrom: options.linkFrom } : {}),
-    });
-    const reconciliation = await reconcileAndApplyProjectProjections({
-        targetRoot: runtime.cwd,
-        ...plan.projectProjections,
-        dryRun: options.dryRun,
+        ...(options.path === undefined ? {} : { packagePath: options.path }),
+        ...(options.linkFrom.length === 0 ? {} : { linkFrom: options.linkFrom }),
     });
+    if (preparation.status === "input-invalid") {
+        return {
+            schemaVersion: 1,
+            command: "add package",
+            status: "usage-error",
+            code: "USAGE_ADD_PACKAGE_INVALID",
+            issues: preparation.issues,
+        };
+    }
+    if (preparation.status === "operation-failure") {
+        return packageAdditionOperationFailure(preparation.phase, preparation.diagnostic);
+    }
+    if (preparation.status === "conflict") {
+        return {
+            schemaVersion: 1,
+            command: "add package",
+            status: "conflict",
+            dryRun: options.dryRun,
+            actions: [],
+            conflicts: [
+                {
+                    kind: preparation.conflict.kind,
+                    existing: {
+                        name: preparation.conflict.existing.name,
+                        path: preparation.conflict.existing.path,
+                        role: preparation.conflict.existing.role,
+                    },
+                    requested: {
+                        name: preparation.conflict.requested.name,
+                        path: preparation.conflict.requested.path,
+                        role: preparation.conflict.requested.role,
+                    },
+                    ...(preparation.conflict.missingLink === undefined
+                        ? {}
+                        : { missingLink: preparation.conflict.missingLink }),
+                },
+            ],
+        };
+    }
+    let reconciliation;
+    try {
+        reconciliation = await reconcileAndApplyProjectProjections({
+            targetRoot: runtime.cwd,
+            ...preparation.plan.projectProjections,
+            dryRun: options.dryRun,
+        });
+    }
+    catch {
+        return packageAdditionOperationFailure("reconciliation");
+    }
     if (!reconciliation.ok) {
-        const output = {
+        return {
             schemaVersion: 1,
             command: "add package",
             status: "conflict",
@@ -252,24 +352,25 @@ export async function runAddPackage(options, runtime) {
             actions: [],
             conflicts: reconciliation.conflicts.map(packageAdditionConflict),
         };
-        return options.json
-            ? { exitCode: 1, stdout: JSON.stringify(output, null, 2) }
-            : {
-                exitCode: 1,
-                stderr: renderPackageAdditionResult(output, options, options.preset),
-            };
     }
-    const output = {
+    return {
         schemaVersion: 1,
         command: "add package",
         status: "success",
         dryRun: options.dryRun,
         actions: reconciliation.actions,
     };
+}
+function packageAdditionOperationFailure(phase, diagnostic) {
     return {
-        exitCode: 0,
-        stdout: options.json
-            ? JSON.stringify(output, null, 2)
-            : renderPackageAdditionResult(output, options, definition.metadata.name),
+        schemaVersion: 1,
+        command: "add package",
+        status: "operation-failure",
+        code: "OPERATION_ADD_PACKAGE_FAILED",
+        phase,
+        error: diagnostic ?? {
+            message: "添加 Package 时发生操作失败。",
+            suggestion: "检查生成仓库元数据与工作区状态后重试；若问题持续发生，请人工处理。",
+        },
     };
 }

package/dist/command-result.d.ts

@@ -0,0 +1,9 @@
+import { type BlueprintValidationCommandResult, type InitCommandResult, type PackageAdditionCommandResult, type PresetCatalogCommandResult } from "./application.ts";
+export type TemplateCommandResult = PresetCatalogCommandResult | BlueprintValidationCommandResult | InitCommandResult | PackageAdditionCommandResult;
+export type CommandPresentation = {
+    readonly destination: "stdout" | "stderr";
+    readonly text: string;
+    readonly exitCode: 0 | 1 | 2 | 64 | 65;
+};
+/** 纯投影；main 拥有身份前缀和实际流写入。 */
+export declare function projectCommandResult(result: TemplateCommandResult, json: boolean, cliVersion: string): CommandPresentation;