@ykdz/template 0.0.35 → 0.0.37

package/dist/command-result.js

@@ -0,0 +1,231 @@
+import {} from "./application.js";
+/** 纯投影；main 拥有身份前缀和实际流写入。 */
+export function projectCommandResult(result, json, cliVersion) {
+    const exitCode = exitCodeFor(result);
+    if (json) {
+        return {
+            destination: "stdout",
+            text: `${JSON.stringify({ ...result, cliVersion })}\n`,
+            exitCode,
+        };
+    }
+    return {
+        destination: exitCode === 0 ? "stdout" : "stderr",
+        text: `${formatHuman(result)}\n`,
+        exitCode,
+    };
+}
+function exitCodeFor(result) {
+    if (result.command === "presets")
+        return 0;
+    if (result.command === "blueprint validate") {
+        return result.status === "success"
+            ? 0
+            : result.status === "invalid"
+                ? 1
+                : 65;
+    }
+    switch (result.status) {
+        case "success":
+            return 0;
+        case "conflict":
+            return 1;
+        case "cancelled":
+            return 2;
+        case "usage-error":
+            return 64;
+        case "operation-failure":
+            return 65;
+    }
+}
+function formatHuman(result) {
+    if (result.command === "presets")
+        return formatPresets(result);
+    if (result.command === "blueprint validate")
+        return formatBlueprint(result);
+    if (result.command === "init")
+        return formatInit(result);
+    return formatAddition(result);
+}
+function formatInit(result) {
+    switch (result.status) {
+        case "success":
+            return [
+                result.dryRun ? "项目生成预览" : "已初始化项目",
+                "",
+                ...rows([
+                    ["预设", result.resolved.preset],
+                    ["名称", result.resolved.packages.map(({ name }) => name).join(", ")],
+                    ["路径", result.resolved.packages.map(({ path }) => path).join(", ")],
+                    ["Scope", result.resolved.scope],
+                    ["目标", result.targetDir],
+                ]),
+                ...(result.dryRun
+                    ? []
+                    : [
+                        "",
+                        "下一步",
+                        "",
+                        ...result.nextSteps.map((item, index) => `  ${index + 1}. ${item.display}`),
+                    ]),
+                ...(result.publicationSetup === null
+                    ? []
+                    : [
+                        "",
+                        "一次性 npm 发布设置",
+                        "",
+                        `  ${result.publicationSetup.command}`,
+                    ]),
+            ].join("\n");
+        case "cancelled":
+            return "已取消初始化；没有写入目标目录。";
+        case "usage-error":
+            return [
+                `错误 [${result.code}]: 初始化参数无效。`,
+                ...result.issues.map((issue) => `  ${initIssueMessage(issue.code)}`),
+                "建议: 修正上述输入后重新运行初始化。",
+            ].join("\n");
+        case "operation-failure":
+            return [
+                `错误 [${result.code}]: ${result.error.message}`,
+                `目标: ${result.targetDir}`,
+                `建议: ${result.error.suggestion}`,
+            ].join("\n");
+    }
+}
+function rows(items) {
+    const width = Math.max(...items.map(([label]) => `${label}:`.length));
+    return items.map(([label, value]) => `  ${`${label}:`.padEnd(width)} ${value}`);
+}
+function initIssueMessage(code) {
+    switch (code) {
+        case "PRESET_UNKNOWN":
+            return "--preset 必须指定一个已支持的内置预设。";
+        case "FIXED_TOPOLOGY_OVERRIDE":
+            return "该预设使用固定初始包拓扑，不能同时使用 --name 或 --path。";
+        case "INVALID_PACKAGE_NAME":
+            return "--name 必须是有效的无 scope 包叶名称。";
+        case "INVALID_PACKAGE_PATH":
+            return "--path 必须恰好包含两个安全路径段。";
+        case "RESERVED_PACKAGE_PATH":
+            return "--path 不能使用保留的工作区集合。";
+        case "INVALID_PACKAGE_SCOPE":
+            return "--scope 必须是不含空白字符的有效 npm scope。";
+        case "INVALID_REPOSITORY_SCOPE":
+            return "目标目录名不能作为默认包 scope；请传入有效的 --scope。";
+        case "CONFLICTING_PACKAGE_IDENTITY":
+            return "初始包身份不能与 Foundation 的 TypeScript 配置包冲突。";
+        case "NON_INTERACTIVE_CONFIRMATION_REQUIRED":
+            return "非交互式初始化必须显式传入 --yes 接受默认值。";
+    }
+}
+function formatPresets(result) {
+    const width = Math.max(...result.presets.map((preset) => `${preset.name}:`.length));
+    return [
+        "内置预设",
+        "",
+        ...result.presets.map((preset) => `  ${`${preset.name}:`.padEnd(width)} ${preset.title} - ${preset.description}`),
+    ].join("\n");
+}
+function formatBlueprint(result) {
+    switch (result.status) {
+        case "success":
+            return "蓝图有效。";
+        case "invalid":
+            return [
+                `错误 [BLUEPRINT_INVALID]: 蓝图无效。`,
+                "",
+                ...result.issues.map((issue) => `  ${issue.path}: 该位置的 Blueprint 定义不符合要求；请检查必填字段、数据类型和拓扑约束。`),
+                "",
+                "建议: 修正上述 Blueprint 问题后重新验证。",
+            ].join("\n");
+        case "operation-failure":
+            return [
+                `错误 [${result.code}]: ${result.error.message}`,
+                `路径: ${result.path}`,
+                `建议: ${result.error.suggestion}`,
+            ].join("\n");
+    }
+}
+function formatAddition(result) {
+    switch (result.status) {
+        case "success":
+            return [
+                result.dryRun ? "Package Addition 预览" : "已添加 Package",
+                "",
+                ...(result.actions.length === 0
+                    ? ["没有变更。"]
+                    : result.actions.map((action) => `  ${action.action} ${action.path} (${action.driver})`)),
+            ].join("\n");
+        case "conflict":
+            return [
+                "Package Addition 冲突",
+                "",
+                ...result.conflicts.flatMap((conflict) => "kind" in conflict
+                    ? [
+                        `  ${conflict.kind === "missing-link" ? "Package Link" : "Package Identity"}`,
+                        `    已有: ${conflict.existing.name} (${conflict.existing.path}, ${conflict.existing.role})`,
+                        `    请求: ${conflict.requested.name} (${conflict.requested.path}, ${conflict.requested.role})`,
+                        ...(conflict.missingLink === undefined
+                            ? []
+                            : [
+                                `    缺少链接: ${conflict.missingLink.consumerPackagePath} -> ${conflict.missingLink.providerPackagePath}`,
+                            ]),
+                    ]
+                    : [
+                        `  ${conflict.path} (${conflict.driver})`,
+                        ...(conflict.location === undefined
+                            ? []
+                            : [`    位置: ${conflict.location || "<文档根>"}`]),
+                        ...(conflict.region === undefined
+                            ? []
+                            : [
+                                `    区域: 生成前第 ${conflict.region.before.startLine} 行；当前第 ${conflict.region.current.startLine} 行；请求后第 ${conflict.region.after.startLine} 行`,
+                            ]),
+                        ...(conflict.attribute === undefined
+                            ? []
+                            : [`    属性: ${conflict.attribute}`]),
+                        `    原因: ${conflict.reason}`,
+                        `    生成前: ${conflict.context.before}`,
+                        `    当前: ${conflict.context.current}`,
+                        `    请求后: ${conflict.context.after}`,
+                    ]),
+                "",
+                "建议: 处理冲突后重试；命令没有写入工作区。",
+            ].join("\n");
+        case "usage-error":
+            return [
+                `错误 [${result.code}]: Package Addition 输入无效。`,
+                ...result.issues.map((issue) => `  ${additionIssueMessage(issue.code)}`),
+                "建议: 修正上述输入后重新运行。",
+            ].join("\n");
+        case "operation-failure":
+            return [
+                `错误 [${result.code}]: ${result.error.message}`,
+                `阶段: ${result.phase}`,
+                `建议: ${result.error.suggestion}`,
+            ].join("\n");
+    }
+}
+function additionIssueMessage(code) {
+    switch (code) {
+        case "PRESET_UNKNOWN":
+            return "未找到该预设；使用 template presets 查看可用预设。";
+        case "PRESET_NOT_ADDABLE":
+            return "该预设不支持添加 Package；选择支持 Package Addition 的预设。";
+        case "INVALID_PACKAGE_NAME":
+            return "Package 名称必须是有效的小写 npm 叶名称。";
+        case "INVALID_PACKAGE_PATH":
+            return "Package 路径必须是两段小写路径，例如 packages/example。";
+        case "RESERVED_PACKAGE_PATH":
+            return "Package 路径不能使用保留工作区目录。";
+        case "INVALID_LINK_FROM":
+            return "--link-from 必须是两段现有 Package 路径。";
+        case "RESERVED_LINK_FROM":
+            return "--link-from 不能使用保留工作区目录。";
+        case "UNKNOWN_LINK_FROM":
+            return "--link-from 指向的 consumer Package 不存在；选择 Blueprint 中已有的 Package 路径。";
+        case "UNSUPPORTED_LINK":
+            return "该 consumer 与 provider 不支持 Package Link；选择兼容的 Package 角色与公开接口。";
+    }
+}

package/dist/main.d.ts

@@ -13,5 +13,8 @@ export type CliRuntime = ApplicationRuntime & {
     };
     readonly version: string;
 };
-export declare function createCliCommand(runtime: CliRuntime): Command;
+export declare function createCliCommand(runtime: CliRuntime, commanderOutput?: {
+    stdout: string;
+    stderr: string;
+}): Command;
 export declare function runCli(runtime: CliRuntime): Promise<number>;

package/dist/main.js

@@ -1,5 +1,6 @@
 import { Command, CommanderError } from "commander";
-import { formatPresetCatalog, runAddPackage, runInit, validateBlueprintFile, } from "./application.js";
+import { listPresetCatalog, runAddPackage, runInit, validateBlueprintFile, } from "./application.js";
+import { projectCommandResult, } from "./command-result.js";
 class HandledCliExit extends Error {
     exitCode;
     constructor(exitCode) {
@@ -7,24 +8,257 @@ class HandledCliExit extends Error {
         this.exitCode = exitCode;
     }
 }
-function writeResult(runtime, result) {
-    if (result.stdout !== undefined) {
-        runtime.streams.stdout.write(`${result.stdout}\n`);
+class OutputFailure extends Error {
+    destination;
+    epiped;
+    constructor(destination, error) {
+        super("Unable to write CLI output");
+        this.destination = destination;
+        this.epiped =
+            typeof error === "object" && error !== null && "code" in error
+                ? error.code === "EPIPE"
+                : false;
     }
-    if (result.stderr !== undefined) {
-        runtime.streams.stderr.write(`${result.stderr}\n`);
+}
+class ConfirmationFailure extends Error {
+    constructor() {
+        super("Confirmation adapter failed");
+    }
+}
+function isConfirmationOutputResourceFailure(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return false;
+    }
+    return error.code === "EPIPE" || error.code === "ENOSPC";
+}
+class HumanCommandIdentity {
+    #runtime;
+    #written = false;
+    constructor(runtime) {
+        this.#runtime = runtime;
+    }
+    write(destination) {
+        if (this.#written)
+            return;
+        this.#written = true;
+        this.#write(destination, `template ${this.#runtime.version}\n`);
+    }
+    writeText(destination, text) {
+        this.write(destination);
+        this.#write(destination, text);
+    }
+    #write(destination, text) {
+        try {
+            this.#runtime.streams[destination].write(text);
+        }
+        catch (error) {
+            throw new OutputFailure(destination, error);
+        }
+    }
+}
+function commandName(argv) {
+    const [first, second] = argv.slice(2);
+    if (first === "init" || first === "presets")
+        return first;
+    if (first === "add")
+        return second === "package" ? "add package" : "add";
+    if (first === "blueprint") {
+        return second === "validate" ? "blueprint validate" : "blueprint";
     }
-    if (result.exitCode !== 0)
-        throw new HandledCliExit(result.exitCode);
+    return "template";
 }
-export function createCliCommand(runtime) {
+function hasJsonControlIntent(argv) {
+    return argv.slice(2).includes("--json");
+}
+function localizeHelp(text) {
+    return text
+        .replaceAll("Usage:", "用法:")
+        .replaceAll("Options:", "选项:")
+        .replaceAll("Commands:", "命令:")
+        .replaceAll("output the version number", "输出版本号")
+        .replaceAll("display help for command", "显示命令帮助")
+        .replaceAll("Resolve a Preset, initial package name and path, and package scope before initialization.", "初始化前解析预设、初始包名称、路径和包 scope。")
+        .replaceAll("Project preset to generate", "要生成的项目预设")
+        .replaceAll("Unscoped leaf name when the Preset supports Primary Package Identity overrides", "预设支持主包身份覆盖时使用的无 scope 叶名称")
+        .replaceAll("Two-segment path when the Preset supports Primary Package Identity overrides", "预设支持主包身份覆盖时使用的两段路径")
+        .replaceAll("Resolved default package scope", "解析后的默认包 scope")
+        .replaceAll("Accept defaults for non-interactive generation", "接受非交互式生成的默认值")
+        .replaceAll("Print the planned generation without writing files", "打印生成计划而不写文件")
+        .replaceAll("Print machine-readable output", "输出机器可读结果")
+        .replaceAll("Do not write the generated follow-up TODO.md", "不写入生成后的 TODO.md")
+        .replaceAll("Add to a Generated Repository; package supports --dry-run and --json.", "向生成仓库添加内容；package 支持 --dry-run 和 --json。")
+        .replaceAll("Add a Package Boundary.", "添加一个 Package Boundary。")
+        .replaceAll("Package preset to add", "要添加的 Package 预设")
+        .replaceAll("Package name to add", "要添加的 Package 名称")
+        .replaceAll("Two-segment Package Path to add", "要添加的两段 Package Path")
+        .replaceAll("Existing consumer Package Path to link from; repeatable", "要链接的现有 consumer Package Path；可重复传入")
+        .replaceAll("Preview the Addition Delta without writing files", "预览 Addition Delta 而不写文件")
+        .replaceAll("List Built-in Presets.", "列出内置预设。")
+        .replaceAll("Work with Project Blueprints.", "处理 Project Blueprint。")
+        .replaceAll("Validate a Project Blueprint.", "校验 Project Blueprint。");
+}
+function commanderFailure(error, command, capturedError) {
+    const usage = capturedError
+        .split("\n")
+        .find((line) => line.startsWith("Usage:"));
+    const suggestion = error.message.match(/Did you mean (.+)\?/u)?.[1];
+    const message = error.code === "commander.optionMissingArgument"
+        ? error.message.replace(/option ('[^']+') argument missing/u, "选项 $1 缺少参数。")
+        : error.code === "commander.excessArguments"
+            ? `命令 ${command} 参数过多。`
+            : error.message;
+    const localizedMessage = message
+        .replace(/^error:\s*/u, "")
+        .replace(/unknown command/u, "未知命令")
+        .replace(/unknown option/u, "未知选项")
+        .replace(/required option/u, "缺少必需选项")
+        .replace(/missing required argument/u, "缺少必需参数")
+        .replace(/ not specified$/u, "。");
+    let code = "USAGE_INVALID_INVOCATION";
+    if (error.code === "commander.unknownCommand") {
+        code = "USAGE_UNKNOWN_COMMAND";
+    }
+    else if (error.code === "commander.unknownOption") {
+        code = "USAGE_UNKNOWN_OPTION";
+    }
+    else if (error.code === "commander.optionMissingArgument") {
+        code = "USAGE_OPTION_MISSING_ARGUMENT";
+    }
+    else if (error.code === "commander.excessArguments") {
+        code = "USAGE_EXCESS_ARGUMENTS";
+    }
+    else if (error.message.includes("required option")) {
+        code = "USAGE_MISSING_REQUIRED_OPTION";
+    }
+    else if (error.message.includes("required argument")) {
+        code = "USAGE_MISSING_REQUIRED_ARGUMENT";
+    }
+    return {
+        code,
+        command,
+        message: localizedMessage,
+        ...(suggestion === undefined
+            ? {}
+            : { suggestion: `Did you mean ${suggestion}?` }),
+        ...(usage === undefined
+            ? {}
+            : { usage: localizeHelp(usage).replace(/^用法:\s*/u, "") }),
+    };
+}
+function applicationFailure(error, command) {
+    return {
+        code: "OPERATION_INTERNAL_ERROR",
+        command,
+        message: "命令遇到了内部错误；请重试，若持续发生请人工处理。",
+    };
+}
+function exitCodeForOutputFailure(error) {
+    return error.destination === "stdout" && error.epiped ? 0 : 65;
+}
+function writeFailure(runtime, identity, json, failure) {
+    if (json) {
+        try {
+            runtime.streams.stdout.write(`${JSON.stringify({
+                schemaVersion: 1,
+                cliVersion: runtime.version,
+                command: failure.command,
+                code: failure.code,
+                status: "error",
+                error: {
+                    message: failure.message,
+                    ...(failure.suggestion === undefined
+                        ? {}
+                        : { suggestion: failure.suggestion }),
+                    ...(failure.usage === undefined ? {} : { usage: failure.usage }),
+                },
+            })}\n`);
+            return;
+        }
+        catch (error) {
+            throw new OutputFailure("stdout", error);
+        }
+    }
+    const lines = [`错误 [${failure.code}]: ${failure.message}`];
+    if (failure.suggestion !== undefined) {
+        lines.push(`建议: ${failure.suggestion}`);
+    }
+    if (failure.usage !== undefined) {
+        lines.push("", `用法: ${failure.usage}`);
+    }
+    identity.writeText("stderr", `${lines.join("\n")}\n`);
+}
+function writeOutput(runtime, destination, text) {
+    try {
+        runtime.streams[destination].write(text);
+    }
+    catch (error) {
+        if (error instanceof OutputFailure)
+            throw error;
+        throw new OutputFailure(destination, error);
+    }
+}
+function writeClosedCommandResult(runtime, result, json) {
+    const presentation = projectCommandResult(result, json, runtime.version);
+    writeOutput(runtime, presentation.destination, presentation.text);
+    if (presentation.exitCode !== 0)
+        throw new HandledCliExit(presentation.exitCode);
+}
+function withHumanIdentity(runtime, json) {
+    const identity = new HumanCommandIdentity(runtime);
+    if (json)
+        return { runtime, identity };
+    return {
+        identity,
+        runtime: {
+            ...runtime,
+            streams: {
+                ...runtime.streams,
+                stdout: {
+                    write(chunk) {
+                        identity.writeText("stdout", chunk);
+                    },
+                },
+                stderr: {
+                    write(chunk) {
+                        identity.writeText("stderr", chunk);
+                    },
+                },
+            },
+            confirmation: {
+                async confirm(request) {
+                    identity.write("stdout");
+                    try {
+                        return await runtime.confirmation.confirm(request);
+                    }
+                    catch (error) {
+                        if (isConfirmationOutputResourceFailure(error)) {
+                            throw new OutputFailure("stdout", error);
+                        }
+                        throw new ConfirmationFailure();
+                    }
+                },
+            },
+        },
+    };
+}
+export function createCliCommand(runtime, commanderOutput) {
     const command = new Command()
         .name("template")
-        .description("Create repositories from maintained project presets.")
+        .description("从维护的项目预设创建仓库。")
         .version(runtime.version)
         .configureOutput({
-        writeOut: (text) => runtime.streams.stdout.write(text),
-        writeErr: (text) => runtime.streams.stderr.write(text),
+        writeOut: (text) => {
+            if (commanderOutput === undefined)
+                runtime.streams.stdout.write(text);
+            else
+                commanderOutput.stdout += text;
+        },
+        writeErr: (text) => {
+            if (commanderOutput === undefined)
+                runtime.streams.stderr.write(text);
+            else
+                commanderOutput.stderr += text;
+        },
     })
         .configureHelp({
         subcommandTerm(subcommand) {
@@ -46,13 +280,15 @@ export function createCliCommand(runtime) {
         .exitOverride();
     command
         .command("init <dir>")
-        .description("Initialize a repository.")
-        .requiredOption("--preset <name>", "Project preset to generate")
-        .option("--scope <name>", "Package scope for workspace package names")
-        .option("-y, --yes", "Accept defaults for non-interactive generation")
-        .option("--dry-run", "Print the planned generation without writing files")
-        .option("--json", "Print machine-readable output")
-        .option("--no-todo", "Do not write the generated follow-up TODO.md")
+        .description("初始化前解析预设、初始包名称、路径和包 scope。")
+        .requiredOption("--preset <name>", "要生成的项目预设")
+        .option("--name <name>", "预设支持主包身份覆盖时使用的无 scope 叶名称")
+        .option("--path <path>", "预设支持主包身份覆盖时使用的两段路径")
+        .option("--scope <name>", "解析后的默认包 scope")
+        .option("-y, --yes", "接受非交互式生成的默认值")
+        .option("--dry-run", "打印生成计划而不写文件")
+        .option("--json", "输出机器可读结果")
+        .option("--no-todo", "不写入生成后的 TODO.md")
         .action(async (dir, options) => {
         const initOptions = {
             dir,
@@ -61,22 +297,24 @@ export function createCliCommand(runtime) {
             dryRun: Boolean(options.dryRun),
             json: Boolean(options.json),
             todo: options.todo,
+            ...(options.name === undefined ? {} : { name: options.name }),
+            ...(options.path === undefined ? {} : { path: options.path }),
             ...(options.scope === undefined ? {} : { scope: options.scope }),
         };
-        runtime.streams.stdout.write(`${await runInit(initOptions, runtime)}\n`);
+        writeClosedCommandResult(runtime, await runInit(initOptions, runtime), initOptions.json);
     });
     const addCommand = command
         .command("add")
-        .description("Add to a Generated Repository; package supports --dry-run and --json.");
+        .description("向生成仓库添加内容；package 支持 --dry-run 和 --json。");
     addCommand
         .command("package")
-        .description("Add a Package Boundary.")
-        .requiredOption("--preset <name>", "Package preset to add")
-        .requiredOption("--name <name>", "Package name to add")
-        .option("--path <path>", "Two-segment Package Path to add")
-        .option("--link-from <path>", "Existing consumer Package Path to link from; repeatable", (value, previous) => [...previous, value], [])
-        .option("--dry-run", "Preview the Addition Delta without writing files")
-        .option("--json", "Print machine-readable output")
+        .description("添加一个 Package Boundary。")
+        .requiredOption("--preset <name>", "要添加的 Package 预设")
+        .requiredOption("--name <name>", "要添加的 Package 名称")
+        .option("--path <path>", "要添加的两段 Package Path")
+        .option("--link-from <path>", "要链接的现有 consumer Package Path；可重复传入", (value, previous) => [...previous, value], [])
+        .option("--dry-run", "预览 Addition Delta 而不写文件")
+        .option("--json", "输出机器可读结果")
         .action(async (options) => {
         const addOptions = {
             preset: options.preset,
@@ -86,44 +324,78 @@ export function createCliCommand(runtime) {
             dryRun: Boolean(options.dryRun),
             json: Boolean(options.json),
         };
-        writeResult(runtime, await runAddPackage(addOptions, runtime));
+        writeClosedCommandResult(runtime, await runAddPackage(addOptions, runtime), addOptions.json);
     });
     command
         .command("presets")
-        .description("List Built-in Presets.")
-        .action(() => {
-        runtime.streams.stdout.write(`${formatPresetCatalog()}\n`);
+        .description("列出内置预设。")
+        .option("--json", "输出机器可读结果")
+        .action((options) => {
+        writeClosedCommandResult(runtime, listPresetCatalog(), Boolean(options.json));
     });
     command
         .command("blueprint")
-        .description("Work with Project Blueprints.")
+        .description("处理 Project Blueprint。")
         .command("validate <path>")
-        .description("Validate a Project Blueprint.")
-        .action(async (filePath) => {
-        runtime.streams.stdout.write(`${await validateBlueprintFile(filePath, runtime)}\n`);
+        .description("校验 Project Blueprint。")
+        .option("--json", "输出机器可读结果")
+        .action(async (filePath, options) => {
+        writeClosedCommandResult(runtime, await validateBlueprintFile(filePath, runtime), Boolean(options.json));
     });
     return command;
 }
 export async function runCli(runtime) {
+    let command = "template";
+    let json = false;
+    let commandRuntime = runtime;
+    let identity = new HumanCommandIdentity(runtime);
+    const commanderOutput = { stdout: "", stderr: "" };
     try {
-        const command = createCliCommand(runtime);
-        if (runtime.argv.length <= 2) {
-            command.error("error: missing command", {
-                exitCode: 1,
-                code: "commander.missingCommand",
-            });
+        command = commandName(runtime.argv);
+        json = hasJsonControlIntent(runtime.argv);
+        ({ runtime: commandRuntime, identity } = withHumanIdentity(runtime, json));
+        const cli = createCliCommand(commandRuntime, commanderOutput);
+        if (commandRuntime.argv.length <= 2) {
+            cli.outputHelp();
+            identity.writeText("stdout", localizeHelp(commanderOutput.stdout));
+            return 0;
         }
-        await command.parseAsync([...runtime.argv], {
-            from: "node",
-        });
+        await cli.parseAsync([...commandRuntime.argv], { from: "node" });
         return 0;
     }
     catch (error) {
+        if (error instanceof OutputFailure)
+            return exitCodeForOutputFailure(error);
         if (error instanceof HandledCliExit)
             return error.exitCode;
-        if (error instanceof CommanderError)
-            return error.exitCode;
-        runtime.streams.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n\nRun \`template --help\` for usage.\n`);
-        return 1;
+        if (error instanceof CommanderError &&
+            (error.code === "commander.helpDisplayed" ||
+                error.code === "commander.version")) {
+            try {
+                identity.writeText("stdout", error.code === "commander.version"
+                    ? ""
+                    : localizeHelp(commanderOutput.stdout));
+            }
+            catch (writeError) {
+                if (writeError instanceof OutputFailure) {
+                    return exitCodeForOutputFailure(writeError);
+                }
+                return 65;
+            }
+            return 0;
+        }
+        const failure = error instanceof CommanderError
+            ? commanderFailure(error, command, commanderOutput.stderr)
+            : applicationFailure(error, command);
+        try {
+            writeFailure(runtime, identity, json, failure);
+        }
+        catch (writeError) {
+            if (writeError instanceof OutputFailure) {
+                return exitCodeForOutputFailure(writeError);
+            }
+            return 65;
+        }
+        return failure.code.startsWith("USAGE_") ? 64 : 65;
     }
 }