@ykdz/template 0.0.38 → 0.0.41

package/node_modules/@ykdz/template-builtin-presets/templates/ts-cli/publication/handoff.ts

@@ -287,6 +287,7 @@ const ticket09ReceiptFilePaths = [
   "package/dist/cli-command-identity.js",
   "package/dist/cli.js",
   "package/dist/main.js",
+  "package/dist/standard-schema.js",
   "package/package.json",
 ] as const;
 
@@ -315,23 +316,94 @@ function hasCanonicalReceiptFiles(files: Receipt["files"]): boolean {
   return true;
 }
 
+/** 发布消费检查与交接校验共用原生结果的业务判据。 */
+export function hasLookupEvidence(source: string): boolean {
+  try {
+    const result: unknown = JSON.parse(source);
+    return (
+      isRecord(result) &&
+      result.schemaVersion === "1" &&
+      result.command === "lookup" &&
+      result.kind === "data" &&
+      result.variant === "found" &&
+      isRecord(result.data) &&
+      result.data.name === "ada" &&
+      result.data.title === "Ada Lovelace"
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function hasSchemaEvidence(
+  source: string,
+  commandName: string,
+): boolean {
+  try {
+    const result: unknown = JSON.parse(source);
+    if (
+      !isRecord(result) ||
+      result.schemaVersion !== "1" ||
+      result.command !== "schema" ||
+      result.kind !== "data" ||
+      result.variant !== "exported" ||
+      !isRecord(result.data)
+    )
+      return false;
+    const manifest = result.data.manifest;
+    if (
+      !isRecord(manifest) ||
+      !isRecord(manifest.commands) ||
+      typeof manifest.root !== "string"
+    )
+      return false;
+    const root = manifest.commands[manifest.root];
+    const lookup = manifest.commands.lookup;
+    const schema = manifest.commands.schema;
+    return (
+      isRecord(root) &&
+      root.name === commandName &&
+      isRecord(schema) &&
+      schema.name === "schema" &&
+      isRecord(lookup) &&
+      lookup.name === "lookup" &&
+      isRecord(lookup.input) &&
+      isRecord(lookup.input.inputSchema) &&
+      isRecord(lookup.success) &&
+      isRecord(lookup.success.variants) &&
+      isRecord(lookup.success.variants.found) &&
+      lookup.success.variants.found.exitCode === 0 &&
+      isRecord(lookup.failures) &&
+      isRecord(lookup.failures.notFound) &&
+      lookup.failures.notFound.exitCode === 1
+    );
+  } catch {
+    return false;
+  }
+}
+
 function hasStableSmokeEvidence(receipt: Receipt): boolean {
-  const [runtimeImport, help, version, greet] = receipt.smokes;
+  const [runtimeImport, help, version, lookup, schema] = receipt.smokes;
   return (
-    receipt.smokes.length === 4 &&
+    receipt.smokes.length === 5 &&
     runtimeImport?.name === "runtime-import" &&
     sameArguments(runtimeImport.args, []) &&
     runtimeImport.stdout === "" &&
     help?.name === "help" &&
     sameArguments(help.args, ["--help"]) &&
-    help.stdout.includes(`Usage: ${receipt.publication.commandName}`) &&
-    help.stdout.includes("greet") &&
+    help.stdout.includes(receipt.publication.commandName) &&
+    help.stdout.includes("lookup") &&
+    help.stdout.includes("schema") &&
     version?.name === "version" &&
     sameArguments(version.args, ["--version"]) &&
-    version.stdout === `${receipt.publication.version}\n` &&
-    greet?.name === "greet" &&
-    sameArguments(greet.args, ["greet", "  Ada Lovelace  "]) &&
-    greet.stdout === "Hello, Ada Lovelace\n"
+    version.stdout ===
+      `${receipt.publication.commandName} ${receipt.publication.version}\n` &&
+    lookup?.name === "lookup" &&
+    sameArguments(lookup.args, ["lookup", "ada"]) &&
+    hasLookupEvidence(lookup.stdout) &&
+    schema?.name === "schema" &&
+    sameArguments(schema.args, ["schema"]) &&
+    hasSchemaEvidence(schema.stdout, receipt.publication.commandName)
   );
 }
 

package/node_modules/@ykdz/template-builtin-presets/templates/ts-cli/publication/readiness.ts

@@ -584,15 +584,19 @@ function addManifestBlockers(options: {
     "imports",
     "provenance",
   ].filter((field) => Object.hasOwn(manifest, field));
+  const runtimeDependencies = manifest.dependencies;
   const manifestContractValid =
     manifest.type === "module" &&
     exactStringSet(manifest.files, publicationFiles) &&
     expectedPublicNodeRangeFromRoot !== undefined &&
     isObject(manifest.engines) &&
     manifest.engines.node === expectedPublicNodeRangeFromRoot &&
-    validRecordOfStrings(manifest.dependencies) &&
-    typeof manifest.dependencies.commander === "string" &&
-    manifest.dependencies.commander.trim().length > 0 &&
+    validRecordOfStrings(runtimeDependencies) &&
+    ["@ykdz/cli-contract", "@valibot/to-json-schema", "valibot"].every(
+      (name) =>
+        typeof runtimeDependencies[name] === "string" &&
+        runtimeDependencies[name].trim().length > 0,
+    ) &&
     isObject(scripts) &&
     typeof scripts.build === "string" &&
     scripts.build.length > 0 &&

package/node_modules/@ykdz/template-builtin-presets/templates/ts-cli/src/cli.ts

@@ -1,27 +1,17 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 
+import { nodeCliOutput } from "@ykdz/cli-contract/node";
+
 import { cliCommandIdentity } from "./cli-command-identity.ts";
-import { runCli, type CliRuntime } from "./main.ts";
+import { runCli } from "./main.ts";
 
 const require = createRequire(import.meta.url);
-const packageManifest = require("../package.json") as unknown;
-
-const runtime: CliRuntime = {
+process.exitCode = await runCli({
   argv: process.argv,
-  streams: {
-    stdin: process.stdin,
-    stdout: process.stdout,
-    stderr: process.stderr,
+  write: nodeCliOutput({ stdout: process.stdout, stderr: process.stderr }),
+  // 身份读取和校验也使用 runCli 的意外故障出口。
+  get identity() {
+    return cliCommandIdentity(require("../package.json"));
   },
-  cwd: process.cwd(),
-  env: process.env,
-  tty: {
-    stdin: Boolean(process.stdin.isTTY),
-    stdout: Boolean(process.stdout.isTTY),
-    stderr: Boolean(process.stderr.isTTY),
-  },
-  identity: cliCommandIdentity(packageManifest),
-};
-
-process.exitCode = await runCli(runtime);
+});

package/node_modules/@ykdz/template-builtin-presets/templates/ts-cli/src/main.ts

@@ -1,78 +1,162 @@
-import { Command, CommanderError } from "commander";
+import {
+  CliWriteError,
+  defineCli,
+  executeCli,
+  helpCapability,
+  outputCapability,
+  parseCliInvocation,
+  text,
+  versionCapability,
+  type WriteCliOutput,
+} from "@ykdz/cli-contract";
+import { isNodeBrokenPipe } from "@ykdz/cli-contract/node";
+import * as v from "valibot";
 
 import type { CliCommandIdentity } from "./cli-command-identity.ts";
-
-export type Greeting = {
-  readonly message: string;
-};
+import { standardSchema } from "./standard-schema.ts";
 
 export type CliRuntime = {
   readonly argv: readonly string[];
-  readonly streams: {
-    readonly stdin: object;
-    readonly stdout: { write(chunk: string): unknown };
-    readonly stderr: { write(chunk: string): unknown };
-  };
-  readonly cwd: string;
-  readonly env: Readonly<Record<string, string | undefined>>;
-  readonly tty: {
-    readonly stdin: boolean;
-    readonly stdout: boolean;
-    readonly stderr: boolean;
-  };
+  readonly write: WriteCliOutput;
   readonly identity: CliCommandIdentity;
 };
 
-export function greet(name: string): Greeting {
-  const normalizedName = name.trim();
-  if (normalizedName.length === 0) {
-    throw new Error("Name must not be empty");
-  }
-  return { message: `Hello, ${normalizedName}` };
-}
+const records = [
+  { name: "ada", title: "Ada Lovelace" },
+  { name: "grace", title: "Grace Hopper" },
+];
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export function createCliCommand(runtime: CliRuntime): Command {
-  const command = new Command()
-    .name(runtime.identity.commandName)
-    .description("A TypeScript command-line tool.")
-    .version(runtime.identity.version)
-    .configureOutput({
-      writeOut: (text) => runtime.streams.stdout.write(text),
-      writeErr: (text) => runtime.streams.stderr.write(text),
-    })
-    .showHelpAfterError()
-    .exitOverride();
-  const greetCommand = command
-    .command("greet")
-    .description("Greet a person.")
-    .argument("<name>", "name to greet")
-    .action((name: string) => {
-      try {
-        runtime.streams.stdout.write(`${greet(name).message}\n`);
-      } catch (error) {
-        greetCommand.error(`error: ${errorMessage(error)}`, {
-          exitCode: 1,
-          code: "cli.greet.invalid-name",
-        });
-      }
-    });
-  return command;
+function createCliContract(identity: CliCommandIdentity) {
+  const define = defineCli<{ getManifest(): Record<string, unknown> }>();
+  return define({
+    root: "cli",
+    help: helpCapability({
+      shortAlias: "-h",
+      headings: {
+        usage: "用法",
+        commands: "命令",
+        arguments: "参数",
+        options: "选项",
+      },
+      wording: {
+        commandPlaceholder: "命令",
+        choices: "候选：{choices}",
+        default: "默认：{value}",
+      },
+    }),
+    version: versionCapability({
+      value: text.line(`${identity.commandName} ${identity.version}`),
+      shortAlias: "-V",
+    }),
+    output: outputCapability({ defaultFormat: "structured", text: true }),
+    usageFailureExitCode: 2,
+    commands: {
+      cli: {
+        kind: "rootGroup",
+        name: identity.commandName,
+        description: "查询示例记录。",
+      },
+      ...define.command("lookup")({
+        kind: "command",
+        parent: "cli",
+        name: "lookup",
+        description: "按名称查询内存记录。",
+        fields: {
+          name: { kind: "positional", description: "小写字母组成的记录名称" },
+        },
+        input: standardSchema(
+          v.object({
+            name: v.pipe(
+              v.string(),
+              v.regex(/^[a-z]+$/, "名称只能包含小写字母。"),
+            ),
+          }),
+        ),
+        success: {
+          kind: "data",
+          variants: {
+            found: {
+              description: "找到记录",
+              exitCode: 0,
+              schema: standardSchema(
+                v.object({ name: v.string(), title: v.string() }),
+              ),
+              text: ({ name, title }) =>
+                text.line(`找到记录：${title}（${name}）`),
+            },
+          },
+        },
+        failures: {
+          notFound: {
+            description: "记录不存在",
+            exitCode: 1,
+            schema: standardSchema(v.object({ name: v.string() })),
+            text: ({ name }) => text.line(`未找到记录：${name}。`),
+          },
+        },
+        handler({ input, outcome }) {
+          const record = records.find(({ name }) => name === input.name);
+          return record === undefined
+            ? outcome.failure.notFound({ name: input.name })
+            : outcome.data.found(record);
+        },
+      }),
+      ...define.command("schema")({
+        kind: "command",
+        parent: "cli",
+        name: "schema",
+        description: "导出完整 CLI 契约及输入/输出 Schema。",
+        input: standardSchema(v.object({})),
+        fields: {},
+        success: {
+          kind: "data",
+          variants: {
+            exported: {
+              description: "完整 CLI 契约",
+              exitCode: 0,
+              schema: standardSchema(
+                v.object({ manifest: v.record(v.string(), v.unknown()) }),
+              ),
+              text: ({ manifest }) =>
+                text.lines([
+                  "CLI 契约",
+                  ...JSON.stringify(manifest, null, 2).split("\n"),
+                ]),
+            },
+          },
+        },
+        failures: {},
+        handler: ({ dependencies, outcome }) =>
+          outcome.data.exported({ manifest: dependencies.getManifest() }),
+      }),
+    },
+  });
 }
 
 export async function runCli(runtime: CliRuntime): Promise<number> {
   try {
-    await createCliCommand(runtime).parseAsync([...runtime.argv], {
-      from: "node",
+    const contract = createCliContract(runtime.identity);
+    const result = await executeCli(contract, {
+      invocation: parseCliInvocation(contract, runtime.argv.slice(2)),
+      dependencies: { getManifest: () => ({ ...contract.manifest }) },
+      write: runtime.write,
     });
-    return 0;
+    return result.exitCode;
   } catch (error) {
-    if (error instanceof CommanderError) {
-      return error.exitCode;
+    if (
+      error instanceof CliWriteError &&
+      error.destination === "stdout" &&
+      isNodeBrokenPipe(error)
+    )
+      return 0;
+    try {
+      await runtime.write({
+        destination: "stderr",
+        chunk: "命令执行失败；请检查运行环境或报告此问题。\n",
+      });
+    } catch {
+      // 诊断通道故障不能改变原定退出类别。
     }
-    throw error;
+    return 70;
   }
 }

package/node_modules/@ykdz/template-builtin-presets/templates/ts-cli/src/standard-schema.ts

@@ -0,0 +1,37 @@
+import { toStandardJsonSchema } from "@valibot/to-json-schema";
+import type * as v from "valibot";
+
+/** 上游执行器要求失败结果不带 value；保留 Valibot 的验证及官方 JSON Schema 投影。 */
+export function standardSchema<
+  T extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>,
+>(schema: T, ignoreActions: string[] = []) {
+  const converted = toStandardJsonSchema(schema);
+  const adapted: typeof converted = {
+    "~standard": {
+      ...converted["~standard"],
+      jsonSchema: {
+        input: (options) =>
+          converted["~standard"].jsonSchema.input({
+            ...options,
+            libraryOptions: { ...options.libraryOptions, ignoreActions },
+          }),
+        output: (options) =>
+          converted["~standard"].jsonSchema.output({
+            ...options,
+            libraryOptions: { ...options.libraryOptions, ignoreActions },
+          }),
+      },
+      validate(value) {
+        const result = converted["~standard"].validate(value);
+        if (result instanceof Promise)
+          return result.then((resolved) =>
+            resolved.issues === undefined
+              ? resolved
+              : { issues: resolved.issues },
+          );
+        return result.issues === undefined ? result : { issues: result.issues };
+      },
+    },
+  };
+  return adapted;
+}

package/node_modules/@ykdz/template-builtin-presets/templates/ts-cli/test/e2e/journeys/lookup.journey.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { cliCommandIdentity } from "../../../src/cli-command-identity.ts";
+import type { CliJourney } from "../journey.ts";
+
+const journey: CliJourney = {
+  name: "lookup",
+  modes: ["source", "distribution", "packed"],
+  async setup() {},
+  commands() {
+    return [
+      { name: "查询记录", args: ["lookup", "ada"] },
+      { name: "文本查询", args: ["lookup", "ada", "--output-format", "text"] },
+      { name: "未找到记录", args: ["lookup", "missing"] },
+      {
+        name: "文本失败",
+        args: ["lookup", "missing", "--output-format", "text"],
+      },
+      { name: "非法输入", args: ["lookup", "   ", "--output-format", "text"] },
+      { name: "完整契约", args: ["schema"] },
+      { name: "帮助", args: ["--help"] },
+      { name: "版本", args: ["--version"] },
+    ];
+  },
+  async assertions({ context, results }) {
+    const identity = cliCommandIdentity(
+      JSON.parse(
+        await readFile(path.join(context.packageRoot, "package.json"), "utf8"),
+      ),
+    );
+    assert.equal(results[0]?.exitCode, 0);
+    assert.equal(results[0]?.stderr, "");
+    assert.deepEqual(JSON.parse(results[0]?.stdout ?? ""), {
+      schemaVersion: "1",
+      command: "lookup",
+      kind: "data",
+      variant: "found",
+      data: { name: "ada", title: "Ada Lovelace" },
+    });
+    assert.equal(results[1]?.exitCode, 0);
+    assert.equal(results[1]?.stderr, "");
+    assert.match(results[1]?.stdout ?? "", /找到记录：Ada Lovelace/u);
+    for (const result of results.slice(2, 4)) {
+      assert.equal(result.exitCode, 1);
+      assert.equal(result.stdout, "");
+    }
+    assert.equal(JSON.parse(results[2]?.stderr ?? "").variant, "notFound");
+    assert.match(results[3]?.stderr ?? "", /未找到记录：missing/u);
+    assert.equal(results[4]?.exitCode, 2);
+    assert.equal(results[4]?.stdout, "");
+    assert.equal(JSON.parse(results[4]?.stderr ?? "").kind, "usageFailure");
+    for (const result of results.slice(5)) {
+      assert.equal(result.exitCode, 0);
+      assert.equal(result.stderr, "");
+    }
+    const schema = JSON.parse(results[5]?.stdout ?? "");
+    assert.equal(schema.command, "schema");
+    for (const fact of ["lookup", "schema", "found", "notFound"])
+      assert.ok(JSON.stringify(schema.data.manifest).includes(fact));
+    assert.match(results[6]?.stdout ?? "", /lookup/u);
+    assert.ok(results[6]?.stdout.includes(identity.commandName));
+    assert.equal(
+      results[7]?.stdout,
+      `${identity.commandName} ${identity.version}\n`,
+    );
+  },
+};
+
+export default journey;