@ykdz/template 0.0.41 → 0.1.0-experimental.0

package/node_modules/@ykdz/reference-ts-cli/native/test/e2e/run-journeys.ts

@@ -0,0 +1,240 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import type {
+  CliJourney,
+  CliJourneyCommand,
+  CliJourneyMode,
+  CliJourneyResult,
+} from "./journey.ts";
+
+const e2eRoot = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(e2eRoot, "..", "..");
+
+function assertNever(value: never): never {
+  throw new Error(`不支持的旅程模式：${String(value)}`);
+}
+
+type JourneyRunTarget = {
+  readonly mode: CliJourneyMode;
+  readonly packedBin?: string;
+};
+
+const journeyRunnerUsage = [
+  "用法：",
+  "  run-journeys.ts source",
+  "  run-journeys.ts packed <bin-path>",
+].join("\n");
+
+function invalidArguments(message: string): never {
+  throw new Error(`${message}\n${journeyRunnerUsage}`);
+}
+
+function parseJourneyRunTargets(
+  args: readonly string[],
+): readonly JourneyRunTarget[] {
+  const first = args[0];
+  if (first === undefined) {
+    invalidArguments("缺少旅程模式。");
+  }
+
+  if (first === "packed") {
+    if (args.length === 1) {
+      invalidArguments("packed 模式必须提供一个可执行文件路径。");
+    }
+    if (args.length !== 2) {
+      invalidArguments(
+        "packed 模式只能跟一个可执行文件路径，不能同时运行其他模式。",
+      );
+    }
+    const packedBin = args[1]!;
+    if (packedBin === "source" || packedBin === "packed") {
+      invalidArguments(
+        `packed 可执行文件路径不能是旅程模式 ${JSON.stringify(packedBin)}。`,
+      );
+    }
+    return [{ mode: "packed", packedBin }];
+  }
+
+  const seen = new Set<CliJourneyMode>();
+  const targets: JourneyRunTarget[] = [];
+  for (const argument of args) {
+    switch (argument) {
+      case "source":
+        if (seen.has(argument)) {
+          invalidArguments(
+            `旅程模式 ${JSON.stringify(argument)} 重复；每个模式只能指定一次。`,
+          );
+        }
+        seen.add(argument);
+        targets.push({ mode: argument });
+        break;
+      case "packed":
+        invalidArguments("packed 模式不能与 source 模式同时指定。");
+      default:
+        invalidArguments(
+          `未知旅程模式 ${JSON.stringify(argument)}；可用值：source、packed。`,
+        );
+    }
+  }
+  return targets;
+}
+
+async function discoverJourneys(): Promise<readonly CliJourney[]> {
+  const journeyRoot = path.join(e2eRoot, "journeys");
+  const entries = await readdir(journeyRoot, { withFileTypes: true });
+  const journeyFiles = entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        (entry.name.endsWith(".journey.ts") ||
+          entry.name.endsWith(".journey.js")),
+    )
+    .map((entry) => entry.name)
+    .toSorted();
+  return await Promise.all(
+    journeyFiles.map(async (fileName) => {
+      const loaded = (await import(
+        pathToFileURL(path.join(journeyRoot, fileName)).href
+      )) as { default: CliJourney };
+      return loaded.default;
+    }),
+  );
+}
+
+function invocation(
+  mode: CliJourneyMode,
+  packedBin: string | undefined,
+): { readonly executable: string; readonly prefix: readonly string[] } {
+  switch (mode) {
+    case "source":
+      return {
+        executable: process.execPath,
+        prefix: [
+          "--conditions=source",
+          path.join(packageRoot, "src", "cli.ts"),
+        ],
+      };
+    case "packed":
+      if (packedBin === undefined) {
+        throw new Error("packed 模式必须提供包管理器安装的可执行文件路径。");
+      }
+      return { executable: packedBin, prefix: [] };
+    default:
+      return assertNever(mode);
+  }
+}
+
+async function runCommand(options: {
+  readonly mode: CliJourneyMode;
+  readonly packedBin: string | undefined;
+  readonly command: CliJourneyCommand;
+  readonly cwd: string;
+}): Promise<CliJourneyResult> {
+  const target = invocation(options.mode, options.packedBin);
+  return await new Promise((resolve, reject) => {
+    const child = spawn(
+      target.executable,
+      [...target.prefix, ...options.command.args],
+      {
+        cwd: options.cwd,
+        env: { ...process.env, ...options.command.env },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.once("error", reject);
+    child.once("close", (exitCode) => {
+      resolve({
+        commandName: options.command.name,
+        exitCode: exitCode ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+export async function runJourneys(options: {
+  readonly mode: CliJourneyMode;
+  readonly packedBin?: string;
+}): Promise<readonly string[]> {
+  const passed: string[] = [];
+  for (const journey of await discoverJourneys()) {
+    if (!journey.modes.includes(options.mode)) continue;
+    const workDir = await mkdtemp(
+      path.join(tmpdir(), `cli-${journey.name}-${options.mode}-`),
+    );
+    const context = { mode: options.mode, packageRoot, workDir };
+    try {
+      await journey.setup(context);
+      const results: CliJourneyResult[] = [];
+      for (const command of journey.commands(context)) {
+        results.push(
+          await runCommand({
+            mode: options.mode,
+            packedBin: options.packedBin,
+            command,
+            cwd: workDir,
+          }),
+        );
+      }
+      await journey.assertions({ context, results });
+      passed.push(`${options.mode}:${journey.name}:passed`);
+    } finally {
+      await rm(workDir, { recursive: true, force: true });
+    }
+  }
+  return passed;
+}
+
+async function runJourneyTargets(
+  targets: readonly JourneyRunTarget[],
+): Promise<readonly string[]> {
+  const passed: string[] = [];
+  for (const target of targets) {
+    switch (target.mode) {
+      case "source":
+        passed.push(...(await runJourneys({ mode: target.mode })));
+        break;
+      case "packed":
+        passed.push(
+          ...(await runJourneys({
+            mode: target.mode,
+            ...(target.packedBin === undefined
+              ? {}
+              : { packedBin: target.packedBin }),
+          })),
+        );
+        break;
+      default:
+        assertNever(target.mode);
+    }
+  }
+  return passed;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  try {
+    const passed = await runJourneyTargets(
+      parseJourneyRunTargets(process.argv.slice(2)),
+    );
+    process.stdout.write(`${passed.join("\n")}\n`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`错误：${message}\n`);
+    process.exitCode = 1;
+  }
+}

package/node_modules/@ykdz/reference-ts-cli/native/test/e2e/source-journeys.test.ts

@@ -0,0 +1,9 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { runJourneys } from "./run-journeys.ts";
+
+void test("runs all source CLI journeys", { timeout: 180_000 }, async () => {
+  const passed = await runJourneys({ mode: "source" });
+  assert.notStrictEqual(passed.length, 0);
+});

package/node_modules/@ykdz/reference-ts-cli/native/test/integration/command.test.ts

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { describe, it } from "node:test";
+
+import { runCli, type CliRuntime } from "../../src/main.ts";
+import { cliCommandIdentity } from "../../src/publication/cli-command-identity.ts";
+
+const identity = cliCommandIdentity(
+  createRequire(import.meta.url)("../../package.json"),
+);
+
+function testRuntime(args: readonly string[]) {
+  let stdout = "";
+  let stderr = "";
+  const runtime: CliRuntime = {
+    argv: ["node", identity.commandName, ...args],
+    identity,
+    write: ({ destination, chunk }) => {
+      if (destination === "stdout") stdout += chunk;
+      else stderr += chunk;
+    },
+  };
+  return { runtime, stdout: () => stdout, stderr: () => stderr };
+}
+
+void describe("CLI 契约", () => {
+  void it("查询成功默认返回结构化数据，也支持中文文本", async () => {
+    const output = testRuntime(["lookup", "ada"]);
+    assert.equal(await runCli(output.runtime), 0);
+    assert.deepStrictEqual(JSON.parse(output.stdout()), {
+      schemaVersion: "2",
+      command: "lookup",
+      kind: "data",
+      variant: "found",
+      data: { name: "ada", title: "Ada Lovelace" },
+    });
+    assert.equal(output.stderr(), "");
+    const human = testRuntime(["lookup", "ada", "--output-format", "text"]);
+    assert.equal(await runCli(human.runtime), 0);
+    assert.ok(human.stdout().includes("找到记录"));
+    assert.ok(human.stdout().includes("Ada Lovelace"));
+  });
+
+  void it("未找到记录是已声明失败，非法名称是用法错误", async () => {
+    const missing = testRuntime(["lookup", "missing"]);
+    assert.equal(await runCli(missing.runtime), 1);
+    assert.equal(missing.stdout(), "");
+    assert.partialDeepStrictEqual(JSON.parse(missing.stderr()), {
+      kind: "failure",
+      variant: "notFound",
+      data: { name: "missing" },
+    });
+    for (const args of [["lookup"], ["lookup", "   "]]) {
+      const invalid = testRuntime([...args, "--output-format", "text"]);
+      assert.equal(await runCli(invalid.runtime), 2);
+      assert.equal(invalid.stdout(), "");
+      assert.partialDeepStrictEqual(JSON.parse(invalid.stderr()), {
+        kind: "usageFailure",
+      });
+    }
+  });
+
+  void it("帮助和版本使用 manifest 身份，schema 导出完整契约", async () => {
+    const version = testRuntime(["--version"]);
+    assert.equal(await runCli(version.runtime), 0);
+    assert.equal(
+      version.stdout(),
+      `${identity.commandName} ${identity.version}\n`,
+    );
+    const help = testRuntime(["--help"]);
+    assert.equal(await runCli(help.runtime), 0);
+    assert.ok(help.stdout().includes(identity.commandName));
+    assert.ok(help.stdout().includes("lookup"));
+    assert.ok(help.stdout().includes("schema"));
+    const schema = testRuntime(["schema"]);
+    assert.equal(await runCli(schema.runtime), 0);
+    const humanSchema = testRuntime(["schema", "--output-format", "text"]);
+    assert.equal(await runCli(humanSchema.runtime), 0);
+    assert.ok(humanSchema.stdout().includes("CLI 契约"));
+    assert.ok(humanSchema.stdout().includes('"commands"'));
+    const manifest = JSON.parse(schema.stdout()).data.manifest;
+    assert.partialDeepStrictEqual(manifest, {
+      schemaVersion: "4",
+      commands: {
+        lookup: {
+          input: {
+            inputSchema: {
+              properties: { name: { pattern: "^[a-z]+$" } },
+              required: ["name"],
+            },
+          },
+          success: { variants: { found: { exitCode: 0 } } },
+          failures: { notFound: { exitCode: 1 } },
+        },
+        schema: { success: { variants: { exported: { exitCode: 0 } } } },
+      },
+      controls: {
+        output: {
+          defaultFormat: "structured",
+          formats: ["structured", "text"],
+        },
+      },
+      usageFailure: { exitCode: 2 },
+    });
+  });
+
+  void it("等待输出完成，仅 stdout EPIPE 安静成功", async () => {
+    const output = testRuntime(["lookup", "ada"]);
+    assert.equal(
+      await runCli({
+        ...output.runtime,
+        write: async () => {
+          throw Object.assign(new Error("pipe"), { code: "EPIPE" });
+        },
+      }),
+      0,
+    );
+    assert.equal(
+      await runCli({
+        ...output.runtime,
+        write: async () => {
+          throw new Error("disk");
+        },
+      }),
+      70,
+    );
+    const failure = testRuntime(["lookup", "missing"]);
+    assert.equal(
+      await runCli({
+        ...failure.runtime,
+        write: async () => {
+          throw Object.assign(new Error("pipe"), { code: "EPIPE" });
+        },
+      }),
+      70,
+    );
+    const argv = ["node", identity.commandName];
+    Object.defineProperty(argv, "slice", {
+      value() {
+        throw new Error("内部细节");
+      },
+    });
+    assert.equal(await runCli({ ...output.runtime, argv }), 70);
+    assert.ok(output.stderr().includes("命令执行失败"));
+    assert.ok(!output.stderr().includes("内部细节"));
+  });
+});

package/node_modules/@ykdz/reference-ts-cli/native/test/unit/cli-command-identity.test.ts

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  cliCommandIdentity,
+  validateCliCommandName,
+} from "../../src/publication/cli-command-identity.ts";
+
+void describe("CLI command identity", () => {
+  for (const { name, command, message } of [
+    { name: "path separator", command: "tools/release", message: "path" },
+    { name: "backslash path", command: "tools\\release", message: "path" },
+    { name: "whitespace", command: "release tool", message: "whitespace" },
+    { name: "control character", command: "release\u0000", message: "control" },
+    { name: "leading hyphen", command: "-release", message: "leading hyphen" },
+    { name: "uppercase ASCII", command: "Release", message: "lowercase ASCII" },
+    { name: "non-ASCII", command: "发布", message: "lowercase ASCII" },
+  ]) {
+    void it(`拒绝格式不合法的命令名：${name}`, () => {
+      assert.throws(
+        () => validateCliCommandName(command),
+        (error: unknown) => {
+          assert.ok(error instanceof Error);
+          assert.ok(error.message.includes(message));
+          return true;
+        },
+      );
+    });
+  }
+
+  void it("接受符合格式的命令名，并拒绝工作区中已使用的名称", () => {
+    assert.equal(validateCliCommandName("release-tool", []), "release-tool");
+    assert.throws(
+      () => validateCliCommandName("release-tool", ["release-tool"]),
+      /already used by another workspace package/,
+    );
+  });
+
+  void it("derives command and unpublished version only from manifest facts", () => {
+    assert.deepStrictEqual(
+      cliCommandIdentity({ bin: { release: "./dist/cli.js" } }),
+      { commandName: "release", version: "unpublished" },
+    );
+    assert.deepStrictEqual(
+      cliCommandIdentity({
+        bin: { ship: "./dist/cli.js" },
+        version: "2.3.4",
+      }),
+      { commandName: "ship", version: "2.3.4" },
+    );
+  });
+
+  void it("rejects malformed manifest identity facts", () => {
+    assert.throws(() => cliCommandIdentity(null), /must be an object/);
+    assert.throws(() => cliCommandIdentity({ bin: {} }), /exactly one bin/);
+    assert.throws(
+      () =>
+        cliCommandIdentity({
+          bin: { release: "./dist/cli.js", ship: "./dist/cli.js" },
+        }),
+      /exactly one bin/,
+    );
+    assert.throws(
+      () => cliCommandIdentity({ bin: { release: "./src/cli.ts" } }),
+      /must execute ".\/dist\/cli\.js"/,
+    );
+    assert.throws(
+      () =>
+        cliCommandIdentity({
+          bin: { release: "./dist/cli.js" },
+          version: 1,
+        }),
+      /version must be a non-empty string/,
+    );
+  });
+});

package/node_modules/@ykdz/reference-ts-cli/native/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.node.json",
+  "compilerOptions": {
+    "customConditions": [],
+    "declaration": false,
+    "declarationMap": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/node_modules/@ykdz/reference-ts-cli/native/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.node.json"
+    }
+  ]
+}

package/node_modules/@ykdz/reference-ts-cli/native/tsconfig.node.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@ykdz/reference-tooling-config/node.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts", "*.config.ts", "template/**/*.ts"]
+}

package/node_modules/@ykdz/reference-ts-cli/native/turbo.json

@@ -0,0 +1,75 @@
+{
+  "extends": ["//"],
+  "tags": ["app"],
+  "tasks": {
+    "build:template": {
+      "dependsOn": [
+        "@ykdz/template-core#build",
+        "@ykdz/template-workspace#build",
+        "@ykdz/reference-npm-publication#build:template"
+      ],
+      "inputs": [],
+      "outputs": ["template-dist/**"],
+      "tags": ["quality:light"]
+    },
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": [],
+      "outputs": ["dist/**"],
+      "cache": false,
+      "tags": ["work:preparation"]
+    },
+    "format:check": {
+      "inputs": [],
+      "outputs": [],
+      "tags": ["quality:light"]
+    },
+    "format:write": {
+      "dependsOn": ["lint:fix"],
+      "inputs": [],
+      "outputs": [],
+      "cache": false,
+      "tags": ["work:repair"]
+    },
+    "lint": {
+      "inputs": [],
+      "outputs": [],
+      "tags": ["quality:light"]
+    },
+    "lint:fix": {
+      "inputs": [],
+      "outputs": [],
+      "cache": false,
+      "tags": ["work:repair"]
+    },
+    "postbuild": {
+      "inputs": [],
+      "outputs": [],
+      "tags": ["work:lifecycle"]
+    },
+    "test": {
+      "dependsOn": [],
+      "inputs": [],
+      "outputs": [],
+      "tags": ["quality:light"]
+    },
+    "test:e2e": {
+      "dependsOn": [],
+      "inputs": [],
+      "outputs": [],
+      "cache": false,
+      "tags": ["quality:heavy"]
+    },
+    "typecheck": {
+      "dependsOn": ["^typecheck"],
+      "inputs": [],
+      "outputs": [],
+      "tags": ["quality:light"]
+    },
+    "check:author-planning-roles": {
+      "cache": false,
+      "outputs": [],
+      "tags": ["quality:light"]
+    }
+  }
+}

package/node_modules/@ykdz/reference-ts-cli/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@ykdz/reference-ts-cli",
+  "version": "0.0.0",
+  "type": "module",
+  "files": [
+    "native"
+  ],
+  "exports": {
+    "./reference": "./native/package.json",
+    "./template": {
+      "types": "./native/template-dist/definition.d.ts",
+      "default": "./native/template-dist/definition.js"
+    }
+  },
+  "dependencies": {
+    "@ykdz/reference-npm-publication": "0.0.0",
+    "@ykdz/template-core": "0.0.0",
+    "@ykdz/template-workspace": "0.0.0"
+  }
+}

package/node_modules/@ykdz/reference-ts-lib/native/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ykdz/reference-ts-lib",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#/*": {
+      "source": "./src/*.ts",
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./reference": "./package.json",
+    "./template": {
+      "source": "./template/definition.ts",
+      "types": "./template-dist/definition.d.ts",
+      "default": "./template-dist/definition.js"
+    }
+  },
+  "scripts": {
+    "check:author-planning-roles": "pnpm --workspace-root run author-planning-roles:workspace -- --owner-directory \"$PWD\"",
+    "format:check": "oxfmt --list-different .",
+    "format:write": "oxfmt --write .",
+    "lint": "oxlint --quiet --format=unix --ignore-pattern node_modules .",
+    "lint:fix": "oxlint --format=unix . --fix",
+    "typecheck": "tsc -p tsconfig.node.json --noEmit --pretty false",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json --pretty false",
+    "test": "node --conditions=source --test --test-reporter=spec 'test/**/*.test.ts'",
+    "build:template": "rm -rf template-dist && tsc -p tsconfig.template.json --pretty false"
+  },
+  "dependencies": {
+    "@ykdz/template-core": "workspace:*",
+    "valibot": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@ykdz/reference-npm-publication": "workspace:*",
+    "@ykdz/reference-tooling-config": "workspace:*",
+    "@ykdz/template-workspace": "workspace:*",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "oxlint-tsgolint": "catalog:",
+    "typescript-7": "catalog:"
+  },
+  "engines": {
+    "node": "24"
+  }
+}

package/node_modules/@ykdz/reference-ts-lib/native/template-dist/definition.d.ts

@@ -0,0 +1 @@
+export declare const referencePackage: import("@ykdz/template-workspace/reference-package").ReferencePackage<import("@ykdz/template-core/workspace-strategy").PackageCreationInput, undefined>;