@ykdz/template 0.0.42 → 0.1.0-experimental.0

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

@@ -1,1150 +0,0 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { isBuiltin } from "node:module";
-import path from "node:path";
-
-import { parse as parseSemver, valid as validSemver } from "semver";
-import parseSpdxExpression from "spdx-expression-parse";
-
-import {
-  inspectPackageReleaseChangelog,
-  type ChangelogBlockerCode,
-} from "./changelog.ts";
-import { cliCommandIdentity } from "./cli-command-identity.ts";
-
-export type NpmPublicationReadinessBlockerCode =
-  | "package-name"
-  | "cli-bin"
-  | "description"
-  | "version"
-  | "private"
-  | "manifest-contract"
-  | "license-id"
-  | "license-content"
-  | "repository"
-  | "homepage"
-  | "bugs"
-  | "readme-missing"
-  | "readme-content"
-  | "license-missing"
-  | "license-mismatch"
-  | "changelog-missing"
-  | ChangelogBlockerCode
-  | "local-template-metadata-missing"
-  | "local-template-metadata-invalid"
-  | "local-template-metadata-mismatch"
-  | "private-runtime-dependency";
-
-export type NpmPublicationReadinessBlocker = {
-  readonly code: NpmPublicationReadinessBlockerCode;
-  readonly owner: {
-    readonly path: string;
-    readonly pointer?: string;
-  };
-  readonly observed: string;
-  readonly expected: string;
-  readonly nextAction: string;
-};
-
-export type NpmPublicationReadiness =
-  | {
-      readonly kind: "blocked";
-      readonly mode: "safe-unconfigured" | "public-intent";
-      readonly target: { readonly packagePath: string };
-      readonly blockers: readonly [
-        NpmPublicationReadinessBlocker,
-        ...NpmPublicationReadinessBlocker[],
-      ];
-    }
-  | {
-      readonly kind: "ready";
-      readonly target: { readonly packagePath: string };
-      readonly blockers: readonly [];
-      readonly publication: {
-        readonly packagePath: string;
-        readonly packageName: string;
-        readonly commandName: string;
-        readonly version: string;
-        readonly repository: string;
-        readonly releaseDate: string;
-        readonly releaseNotes: string;
-      };
-    };
-
-type JsonObject = Record<string, unknown>;
-
-type TextFact =
-  | { readonly kind: "present"; readonly source: string }
-  | { readonly kind: "missing" }
-  | { readonly kind: "unreadable"; readonly reason: string };
-
-const publicationFiles = [
-  "dist",
-  "README.md",
-  "LICENSE",
-  "CHANGELOG.md",
-] as const;
-
-const canonicalPublicationPrepack = "pnpm exec turbo run build --filter=.";
-
-// 私有根 engines.node 允许两种形态：旧仓库的纯大版本（"24"）与初始化投影发版快照
-// 的精确三段版本（"24.16.0"），两者都能派生大版本；范围表达式、两段版本与 v 前缀
-// 等未声明形态一律拒绝。
-const nodeMajorOrExactVersionPattern = /^(\d+)(?:\.(\d+\.\d+))?$/u;
-
-// 公开候选范围与根声明形态配对：精确根只接受同一精确值的 caret 范围，旧大版本根
-// 只接受原有 `>=major`；精确根不得回退到无上界范围。
-function expectedPublicNodeRange(
-  rootNodeDeclaration: string,
-): string | undefined {
-  const parsed = nodeMajorOrExactVersionPattern.exec(rootNodeDeclaration);
-  if (parsed === null) return undefined;
-  const [, major, exactRemainder] = parsed;
-  return exactRemainder === undefined
-    ? `>=${major}`
-    : `^${major}.${exactRemainder}`;
-}
-
-function isObject(value: unknown): value is JsonObject {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function display(value: unknown): string {
-  if (value === undefined) return "missing";
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return `[unserializable ${typeof value}]`;
-  }
-}
-
-function blocker(options: {
-  readonly code: NpmPublicationReadinessBlockerCode;
-  readonly path: string;
-  readonly pointer?: string;
-  readonly observed: string;
-  readonly expected: string;
-  readonly nextAction: string;
-}): NpmPublicationReadinessBlocker {
-  return {
-    code: options.code,
-    owner: {
-      path: options.path,
-      ...(options.pointer === undefined ? {} : { pointer: options.pointer }),
-    },
-    observed: options.observed,
-    expected: options.expected,
-    nextAction: options.nextAction,
-  };
-}
-
-function compareBlockers(
-  left: NpmPublicationReadinessBlocker,
-  right: NpmPublicationReadinessBlocker,
-): number {
-  const leftKey = `${left.owner.path}\u0000${left.owner.pointer ?? ""}\u0000${left.code}`;
-  const rightKey = `${right.owner.path}\u0000${right.owner.pointer ?? ""}\u0000${right.code}`;
-  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
-}
-
-async function textFact(filePath: string): Promise<TextFact> {
-  try {
-    return { kind: "present", source: await readFile(filePath, "utf8") };
-  } catch (error) {
-    if (
-      isObject(error) &&
-      (error.code === "ENOENT" || error.code === "ENOTDIR")
-    ) {
-      return { kind: "missing" };
-    }
-    return {
-      kind: "unreadable",
-      reason: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-function parseJsonFact(fact: TextFact): JsonObject | undefined {
-  if (fact.kind !== "present") return undefined;
-  try {
-    const value: unknown = JSON.parse(fact.source);
-    return isObject(value) ? value : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function validNpmPackageName(value: string): boolean {
-  if (
-    value.length === 0 ||
-    value.length > 214 ||
-    value !== value.trim() ||
-    value !== value.toLowerCase() ||
-    value === "." ||
-    value === ".." ||
-    value === "node_modules" ||
-    value === "favicon.ico" ||
-    isBuiltin(value)
-  ) {
-    return false;
-  }
-
-  const scoped = /^@([^/]+)\/([^/]+)$/u.exec(value);
-  if (value.startsWith("@") && scoped === null) return false;
-  const scope = scoped?.[1];
-  const leaf = scoped?.[2] ?? value;
-  if (scope === undefined && /^[._-]/u.test(leaf)) return false;
-  if (scope !== undefined && leaf.startsWith(".")) return false;
-  if (/[~'!()*]/u.test(leaf)) return false;
-  return (
-    encodeURIComponent(leaf) === leaf &&
-    (scope === undefined || encodeURIComponent(scope) === scope)
-  );
-}
-
-function stableVersion(value: unknown): value is string {
-  if (typeof value !== "string" || validSemver(value) !== value) return false;
-  const parsed = parseSemver(value);
-  return (
-    parsed !== null &&
-    parsed.prerelease.length === 0 &&
-    parsed.build.length === 0
-  );
-}
-
-function validSpdx(value: unknown): value is string {
-  if (typeof value !== "string" || value.length === 0) return false;
-  try {
-    parseSpdxExpression(value);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function exactStringSet(value: unknown, expected: readonly string[]): boolean {
-  return (
-    Array.isArray(value) &&
-    value.every((item): item is string => typeof item === "string") &&
-    value.length === expected.length &&
-    new Set(value).size === value.length &&
-    expected.every((item) => value.includes(item))
-  );
-}
-
-function nonPlaceholderText(source: string): boolean {
-  const normalized = source.trim();
-  return (
-    normalized.length > 0 &&
-    !/\bTODO\b/iu.test(normalized) &&
-    !/^(?:your name|name of copyright owner|copyright holder|\{\{[A-Z][A-Z0-9_]*\}\}|\[(?:yyyy|name of copyright owner|copyright holder)\])$/iu.test(
-      normalized,
-    )
-  );
-}
-
-function hasNonPlaceholderCopyrightHolder(source: string): boolean {
-  return [
-    ...source.matchAll(
-      /^Copyright(?: \(c\))?\s+(?:\d{4}(?:-\d{4})?\s+)?([^\r\n]+)$/gimu,
-    ),
-  ].some(
-    (match) =>
-      nonPlaceholderText(match[1]!) &&
-      !/\[(?:yyyy|name of copyright owner|copyright holder)\]/iu.test(
-        match[1]!,
-      ),
-  );
-}
-
-function githubRepository(
-  value: unknown,
-  packagePath: string,
-):
-  | {
-      readonly canonicalUrl: string;
-      readonly webUrl: string;
-    }
-  | undefined {
-  if (!isObject(value)) return undefined;
-  if (
-    Object.keys(value).toSorted().join("\u0000") !==
-      ["directory", "type", "url"].toSorted().join("\u0000") ||
-    value.type !== "git" ||
-    value.directory !== packagePath ||
-    typeof value.url !== "string"
-  ) {
-    return undefined;
-  }
-  const match =
-    /^git\+https:\/\/github\.com\/([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]+)\.git$/u.exec(
-      value.url,
-    );
-  if (match === null || match[2]!.endsWith(".")) return undefined;
-  return {
-    canonicalUrl: value.url,
-    webUrl: `https://github.com/${match[1]}/${match[2]}`,
-  };
-}
-
-function validRecordOfStrings(value: unknown): value is JsonObject {
-  return (
-    isObject(value) &&
-    Object.values(value).every((item) => typeof item === "string")
-  );
-}
-
-function jsonPointerSegment(value: string): string {
-  return value.replaceAll("~", "~0").replaceAll("/", "~1");
-}
-
-function runtimeDependencyNames(manifest: JsonObject): readonly string[] {
-  return [manifest.dependencies, manifest.optionalDependencies].flatMap(
-    (value) => (isObject(value) ? Object.keys(value) : []),
-  );
-}
-
-function workspacePatterns(source: string): readonly string[] {
-  const lines = source.split(/\r?\n/u);
-  const patterns: string[] = [];
-  let inPackages = false;
-  for (const line of lines) {
-    if (/^packages:\s*$/u.test(line)) {
-      inPackages = true;
-      continue;
-    }
-    if (inPackages && /^\S/u.test(line)) break;
-    const item = /^\s+-\s+["']?([^"']+?)["']?\s*$/u.exec(line)?.[1];
-    if (inPackages && item !== undefined) patterns.push(item);
-  }
-  return patterns;
-}
-
-async function actualWorkspaceManifests(repositoryRoot: string): Promise<{
-  readonly manifests: readonly {
-    readonly path: string;
-    readonly manifest: JsonObject;
-  }[];
-  readonly failures: readonly {
-    readonly path: string;
-    readonly reason: string;
-  }[];
-}> {
-  const workspace = await textFact(
-    path.join(repositoryRoot, "pnpm-workspace.yaml"),
-  );
-  if (workspace.kind !== "present") {
-    return {
-      manifests: [],
-      failures: [
-        {
-          path: "pnpm-workspace.yaml",
-          reason: workspace.kind === "missing" ? "missing" : workspace.reason,
-        },
-      ],
-    };
-  }
-  const manifests: { path: string; manifest: JsonObject }[] = [];
-  const failures: { path: string; reason: string }[] = [];
-  const patterns = workspacePatterns(workspace.source);
-  if (patterns.length === 0) {
-    failures.push({
-      path: "pnpm-workspace.yaml",
-      reason: "No workspace package patterns were found",
-    });
-  }
-  for (const pattern of patterns) {
-    const match = /^([a-z0-9][a-z0-9-]*)\/\*$/u.exec(pattern);
-    if (match === null) {
-      failures.push({
-        path: "pnpm-workspace.yaml",
-        reason: `Unsupported workspace package pattern ${JSON.stringify(pattern)}`,
-      });
-      continue;
-    }
-    const collection = match[1]!;
-    let entries;
-    try {
-      entries = await readdir(path.join(repositoryRoot, collection), {
-        withFileTypes: true,
-      });
-    } catch (error) {
-      if (isObject(error) && error.code === "ENOENT") continue;
-      failures.push({
-        path: collection,
-        reason: error instanceof Error ? error.message : String(error),
-      });
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const packagePath = `${collection}/${entry.name}`;
-      const manifestFact = await textFact(
-        path.join(repositoryRoot, packagePath, "package.json"),
-      );
-      if (manifestFact.kind === "missing") continue;
-      const manifest = parseJsonFact(manifestFact);
-      if (manifest === undefined) {
-        failures.push({
-          path: `${packagePath}/package.json`,
-          reason:
-            manifestFact.kind === "unreadable"
-              ? manifestFact.reason
-              : "Invalid JSON object",
-        });
-        continue;
-      }
-      if (manifest !== undefined)
-        manifests.push({ path: packagePath, manifest });
-    }
-  }
-  return { manifests, failures };
-}
-
-function addManifestBlockers(options: {
-  readonly manifest: JsonObject;
-  readonly manifestPath: string;
-  readonly packagePath: string;
-  readonly rootManifest: JsonObject | undefined;
-  readonly blockers: NpmPublicationReadinessBlocker[];
-}): {
-  readonly packageName?: string;
-  readonly commandName?: string;
-  readonly version?: string;
-  readonly repository?: {
-    readonly canonicalUrl: string;
-    readonly webUrl: string;
-  };
-  readonly license?: string;
-} {
-  const { blockers, manifest, manifestPath, packagePath, rootManifest } =
-    options;
-  const packageName =
-    typeof manifest.name === "string" && validNpmPackageName(manifest.name)
-      ? manifest.name
-      : undefined;
-  if (packageName === undefined) {
-    blockers.push(
-      blocker({
-        code: "package-name",
-        path: manifestPath,
-        pointer: "/name",
-        observed: display(manifest.name),
-        expected: "A valid scoped or unscoped npm package name",
-        nextAction: "Set the final public npm package name.",
-      }),
-    );
-  }
-
-  let commandName: string | undefined;
-  try {
-    commandName = cliCommandIdentity(manifest).commandName;
-  } catch (error) {
-    blockers.push(
-      blocker({
-        code: "cli-bin",
-        path: manifestPath,
-        pointer: "/bin",
-        observed: error instanceof Error ? error.message : String(error),
-        expected: 'Exactly one safe bin that executes "./dist/cli.js"',
-        nextAction: "Correct the public CLI bin declaration.",
-      }),
-    );
-  }
-
-  if (
-    typeof manifest.description !== "string" ||
-    manifest.description.trim().length === 0
-  ) {
-    blockers.push(
-      blocker({
-        code: "description",
-        path: manifestPath,
-        pointer: "/description",
-        observed: display(manifest.description),
-        expected: "A non-empty public package description",
-        nextAction: "Describe the CLI for npm consumers.",
-      }),
-    );
-  }
-
-  const version = stableVersion(manifest.version)
-    ? manifest.version
-    : undefined;
-  if (version === undefined) {
-    blockers.push(
-      blocker({
-        code: "version",
-        path: manifestPath,
-        pointer: "/version",
-        observed: display(manifest.version),
-        expected: "A stable exact SemVer version",
-        nextAction: "Set the reviewed public package version.",
-      }),
-    );
-  }
-
-  if (Object.hasOwn(manifest, "private")) {
-    blockers.push(
-      blocker({
-        code: "private",
-        path: manifestPath,
-        pointer: "/private",
-        observed: display(manifest.private),
-        expected: "The private field to be absent",
-        nextAction:
-          "Remove private only after every publication fact is ready.",
-      }),
-    );
-  }
-
-  const license = validSpdx(manifest.license) ? manifest.license : undefined;
-  if (license === undefined) {
-    blockers.push(
-      blocker({
-        code: "license-id",
-        path: manifestPath,
-        pointer: "/license",
-        observed: display(manifest.license),
-        expected: "A valid SPDX license expression",
-        nextAction: "Set the reviewed SPDX license identifier.",
-      }),
-    );
-  }
-
-  const repository = githubRepository(manifest.repository, packagePath);
-  if (repository === undefined) {
-    blockers.push(
-      blocker({
-        code: "repository",
-        path: manifestPath,
-        pointer: "/repository",
-        observed: display(manifest.repository),
-        expected:
-          "A canonical public GitHub repository object with the Package Path directory",
-        nextAction: "Set the exact public GitHub repository metadata.",
-      }),
-    );
-  }
-  if (
-    repository === undefined ||
-    manifest.homepage !== `${repository.webUrl}#readme`
-  ) {
-    blockers.push(
-      blocker({
-        code: "homepage",
-        path: manifestPath,
-        pointer: "/homepage",
-        observed: display(manifest.homepage),
-        expected:
-          repository === undefined
-            ? "A homepage derived from the canonical GitHub repository"
-            : `${repository.webUrl}#readme`,
-        nextAction: "Set the package homepage from the public repository.",
-      }),
-    );
-  }
-  const expectedBugs =
-    repository === undefined ? undefined : `${repository.webUrl}/issues`;
-  if (
-    expectedBugs === undefined ||
-    !isObject(manifest.bugs) ||
-    Object.keys(manifest.bugs).length !== 1 ||
-    manifest.bugs.url !== expectedBugs
-  ) {
-    blockers.push(
-      blocker({
-        code: "bugs",
-        path: manifestPath,
-        pointer: "/bugs",
-        observed: display(manifest.bugs),
-        expected:
-          expectedBugs === undefined
-            ? "An issues URL derived from the canonical GitHub repository"
-            : display({ url: expectedBugs }),
-        nextAction: "Set the package issues URL from the public repository.",
-      }),
-    );
-  }
-
-  const rootNodeDeclaration =
-    isObject(rootManifest?.engines) &&
-    typeof rootManifest.engines.node === "string"
-      ? rootManifest.engines.node
-      : undefined;
-  const expectedPublicNodeRangeFromRoot =
-    rootNodeDeclaration === undefined
-      ? undefined
-      : expectedPublicNodeRange(rootNodeDeclaration);
-  const publishConfig = manifest.publishConfig;
-  const scripts = manifest.scripts;
-  const forbiddenFields = [
-    "main",
-    "types",
-    "exports",
-    "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(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 &&
-    scripts.prepack === canonicalPublicationPrepack &&
-    isObject(publishConfig) &&
-    Object.keys(publishConfig).toSorted().join("\u0000") ===
-      ["access", "registry"].join("\u0000") &&
-    publishConfig.access === "public" &&
-    publishConfig.registry === "https://registry.npmjs.org/" &&
-    forbiddenFields.length === 0;
-  if (!manifestContractValid) {
-    blockers.push(
-      blocker({
-        code: "manifest-contract",
-        path: manifestPath,
-        observed: display({
-          type: manifest.type,
-          files: manifest.files,
-          engines: manifest.engines,
-          scripts: manifest.scripts,
-          dependencies: manifest.dependencies,
-          publishConfig: manifest.publishConfig,
-          forbiddenFields,
-        }),
-        expected:
-          "The minimal public CLI manifest contract derived from the root Node baseline",
-        nextAction:
-          "Restore the minimal CLI files, engines, scripts, dependencies, and public publish configuration.",
-      }),
-    );
-  }
-
-  return {
-    ...(packageName === undefined ? {} : { packageName }),
-    ...(commandName === undefined ? {} : { commandName }),
-    ...(version === undefined ? {} : { version }),
-    ...(repository === undefined ? {} : { repository }),
-    ...(license === undefined ? {} : { license }),
-  };
-}
-
-async function addDocumentBlockers(options: {
-  readonly repositoryRoot: string;
-  readonly packagePath: string;
-  readonly version?: string;
-  readonly license?: string;
-  readonly blockers: NpmPublicationReadinessBlocker[];
-}): Promise<{
-  readonly releaseDate?: string;
-  readonly releaseNotes?: string;
-}> {
-  const { blockers, packagePath, repositoryRoot } = options;
-  const readmePath = `${packagePath}/README.md`;
-  const readme = await textFact(path.join(repositoryRoot, readmePath));
-  if (readme.kind === "missing") {
-    blockers.push(
-      blocker({
-        code: "readme-missing",
-        path: readmePath,
-        observed: "missing",
-        expected: "An independent package README",
-        nextAction: "Create the public package README.",
-      }),
-    );
-  } else if (
-    readme.kind === "unreadable" ||
-    !nonPlaceholderText(readme.source)
-  ) {
-    blockers.push(
-      blocker({
-        code: "readme-content",
-        path: readmePath,
-        observed:
-          readme.kind === "unreadable"
-            ? readme.reason
-            : "empty or placeholder text",
-        expected: "Non-placeholder documentation for npm consumers",
-        nextAction: "Write the public package README.",
-      }),
-    );
-  }
-
-  const rootLicensePath = "LICENSE";
-  const packageLicensePath = `${packagePath}/LICENSE`;
-  const [rootLicense, packageLicense] = await Promise.all([
-    textFact(path.join(repositoryRoot, rootLicensePath)),
-    textFact(path.join(repositoryRoot, packageLicensePath)),
-  ]);
-  for (const [licensePath, fact] of [
-    [rootLicensePath, rootLicense],
-    [packageLicensePath, packageLicense],
-  ] as const) {
-    if (fact.kind === "missing") {
-      blockers.push(
-        blocker({
-          code: "license-missing",
-          path: licensePath,
-          observed: "missing",
-          expected: "The reviewed public package license text",
-          nextAction: "Create matching root and package LICENSE files.",
-        }),
-      );
-    } else if (fact.kind === "unreadable" || !nonPlaceholderText(fact.source)) {
-      blockers.push(
-        blocker({
-          code: "license-content",
-          path: licensePath,
-          observed:
-            fact.kind === "unreadable"
-              ? fact.reason
-              : "empty or placeholder text",
-          expected: "Non-placeholder reviewed license text",
-          nextAction: "Write the selected license text and real holder facts.",
-        }),
-      );
-    }
-  }
-  if (
-    rootLicense.kind === "present" &&
-    packageLicense.kind === "present" &&
-    rootLicense.source !== packageLicense.source
-  ) {
-    blockers.push(
-      blocker({
-        code: "license-mismatch",
-        path: packageLicensePath,
-        observed: "Package LICENSE bytes differ from root LICENSE",
-        expected: "Byte-identical root and package LICENSE files",
-        nextAction: "Copy the reviewed license bytes to both owners.",
-      }),
-    );
-  }
-  if (
-    options.license !== undefined &&
-    (options.license === "MIT" || options.license === "Apache-2.0") &&
-    packageLicense.kind === "present" &&
-    !hasNonPlaceholderCopyrightHolder(packageLicense.source)
-  ) {
-    blockers.push(
-      blocker({
-        code: "license-content",
-        path: packageLicensePath,
-        observed: "LICENSE does not contain a non-placeholder copyright holder",
-        expected: `${options.license} license text with a non-placeholder copyright holder`,
-        nextAction:
-          "Write the selected license with the real copyright holder.",
-      }),
-    );
-  }
-
-  const changelogPath = `${packagePath}/CHANGELOG.md`;
-  const changelog = await textFact(path.join(repositoryRoot, changelogPath));
-  if (changelog.kind !== "present") {
-    blockers.push(
-      blocker({
-        code: "changelog-missing",
-        path: changelogPath,
-        observed: changelog.kind === "missing" ? "missing" : changelog.reason,
-        expected: "A package-local Keep a Changelog document",
-        nextAction: "Create the reviewed package changelog.",
-      }),
-    );
-    return {};
-  }
-  if (options.version === undefined) return {};
-  const inspected = inspectPackageReleaseChangelog(
-    changelog.source,
-    options.version,
-  );
-  if (inspected.blockers.length > 0) {
-    blockers.push(
-      ...inspected.blockers.map((item) => ({
-        ...item,
-        owner: { path: changelogPath },
-      })),
-    );
-    return {};
-  }
-  return {
-    ...(inspected.releaseDate === undefined
-      ? {}
-      : { releaseDate: inspected.releaseDate }),
-    ...(inspected.releaseNotes === undefined
-      ? {}
-      : { releaseNotes: inspected.releaseNotes }),
-  };
-}
-
-async function addMetadataBlockers(options: {
-  readonly repositoryRoot: string;
-  readonly packagePath: string;
-  readonly packageName?: string;
-  readonly rootManifest?: JsonObject;
-  readonly blockers: NpmPublicationReadinessBlocker[];
-}): Promise<void> {
-  const metadataRoot = path.join(options.repositoryRoot, ".template");
-  let metadataRootState: "absent" | "directory" | "invalid";
-  let metadataRootReason: string | undefined;
-  try {
-    metadataRootState = (await stat(metadataRoot)).isDirectory()
-      ? "directory"
-      : "invalid";
-    if (metadataRootState === "invalid") {
-      metadataRootReason = "Local Template Metadata root is not a directory";
-    }
-  } catch (error) {
-    if (isObject(error) && error.code === "ENOENT") {
-      metadataRootState = "absent";
-    } else {
-      metadataRootState = "invalid";
-      metadataRootReason =
-        error instanceof Error ? error.message : String(error);
-    }
-  }
-  const blueprintPath = ".template/blueprint.json";
-  const generationPath = ".template/generation.json";
-  const [blueprintFact, generationFact] = await Promise.all([
-    textFact(path.join(options.repositoryRoot, blueprintPath)),
-    textFact(path.join(options.repositoryRoot, generationPath)),
-  ]);
-  if (
-    metadataRootState === "absent" &&
-    blueprintFact.kind === "missing" &&
-    generationFact.kind === "missing"
-  ) {
-    return;
-  }
-  if (metadataRootState === "invalid") {
-    options.blockers.push(
-      blocker({
-        code: "local-template-metadata-invalid",
-        path: ".template",
-        observed:
-          metadataRootReason ?? "Unreadable Local Template Metadata root",
-        expected: "A readable Local Template Metadata directory",
-        nextAction:
-          "Restore the .template directory before checking publication readiness.",
-      }),
-    );
-  }
-  for (const [metadataPath, fact] of [
-    [blueprintPath, blueprintFact],
-    [generationPath, generationFact],
-  ] as const) {
-    if (fact.kind === "missing") {
-      options.blockers.push(
-        blocker({
-          code: "local-template-metadata-missing",
-          path: metadataPath,
-          observed: "missing",
-          expected: "Complete Local Template Metadata when .template exists",
-          nextAction: "Restore both supported Local Template Metadata files.",
-        }),
-      );
-    } else if (fact.kind === "unreadable") {
-      options.blockers.push(
-        blocker({
-          code: "local-template-metadata-invalid",
-          path: metadataPath,
-          observed: fact.reason,
-          expected: "Readable Local Template Metadata JSON",
-          nextAction: "Restore the supported Local Template Metadata file.",
-        }),
-      );
-    }
-  }
-  const blueprint = parseJsonFact(blueprintFact);
-  const generation = parseJsonFact(generationFact);
-  const blueprintPackages =
-    blueprint?.schemaVersion === 3 && Array.isArray(blueprint.packages)
-      ? blueprint.packages
-      : undefined;
-  if (blueprintFact.kind === "present" && blueprintPackages === undefined) {
-    options.blockers.push(
-      blocker({
-        code: "local-template-metadata-invalid",
-        path: blueprintPath,
-        observed: "Unreadable Blueprint publication facts",
-        expected: "Blueprint schema version 3 with package facts",
-        nextAction: "Restore the canonical Blueprint.",
-      }),
-    );
-  }
-  const generationPackages =
-    generation?.schemaVersion === 2 &&
-    typeof generation.repositoryName === "string" &&
-    generation.repositoryName.trim().length > 0 &&
-    typeof generation.defaultPackageScope === "string" &&
-    generation.defaultPackageScope.trim().length > 0 &&
-    Array.isArray(generation.packages)
-      ? generation.packages
-      : undefined;
-  if (generationFact.kind === "present" && generationPackages === undefined) {
-    options.blockers.push(
-      blocker({
-        code: "local-template-metadata-invalid",
-        path: generationPath,
-        observed: "Unreadable Generation Record publication facts",
-        expected:
-          "Generation Record schema version 2 with repository, default scope, and package facts",
-        nextAction: "Restore the canonical Generation Record.",
-      }),
-    );
-  }
-  if (
-    blueprintPackages === undefined ||
-    generationPackages === undefined ||
-    generation === undefined
-  ) {
-    return;
-  }
-  const definitions = blueprintPackages.filter(
-    (item): item is JsonObject =>
-      isObject(item) && item.path === options.packagePath,
-  );
-  const records = generationPackages.filter(
-    (item): item is JsonObject =>
-      isObject(item) && item.path === options.packagePath,
-  );
-  const definition = definitions[0];
-  const record = records[0];
-  const targetId =
-    definition !== undefined &&
-    typeof definition.packageDefinitionId === "string"
-      ? definition.packageDefinitionId
-      : undefined;
-  const definitionsWithTargetId =
-    targetId === undefined
-      ? []
-      : blueprintPackages.filter(
-          (item): item is JsonObject =>
-            isObject(item) && item.packageDefinitionId === targetId,
-        );
-  const recordsWithTargetId =
-    targetId === undefined
-      ? []
-      : generationPackages.filter(
-          (item): item is JsonObject =>
-            isObject(item) && item.packageDefinitionId === targetId,
-        );
-  const candidateProvenance = generationPackages.filter(
-    (item): item is JsonObject =>
-      isObject(item) &&
-      item.definitionName === "ts-cli" &&
-      item.contributionIdentity === "cli-publication-candidate",
-  );
-  const initCandidates = candidateProvenance.filter(
-    (item) => item.planningContribution === "planInitialization",
-  );
-  const definitionMatches =
-    definitions.length === 1 &&
-    definition !== undefined &&
-    targetId !== undefined &&
-    targetId.length > 0 &&
-    definitionsWithTargetId.length === 1 &&
-    definition.name === options.packageName &&
-    definition.role === "cli-tool";
-  const recordMatches =
-    records.length === 1 &&
-    record !== undefined &&
-    definition !== undefined &&
-    recordsWithTargetId.length === 1 &&
-    record.packageDefinitionId === definition.packageDefinitionId &&
-    candidateProvenance.length === 1 &&
-    initCandidates.length === 1 &&
-    initCandidates[0] === record;
-  const repositoryMatches =
-    generation.repositoryName === options.rootManifest?.name;
-  if (!definitionMatches || !recordMatches || !repositoryMatches) {
-    options.blockers.push(
-      blocker({
-        code: "local-template-metadata-mismatch",
-        path: !definitionMatches ? blueprintPath : generationPath,
-        observed: display({
-          definitions,
-          records,
-          definitionsWithTargetId,
-          recordsWithTargetId,
-          candidateProvenance,
-          repositoryName: generation.repositoryName,
-        }),
-        expected:
-          "Exactly one matching public CLI target with stable ID and candidate provenance",
-        nextAction:
-          "Restore the matching Blueprint name and unchanged candidate planning facts.",
-      }),
-    );
-  }
-}
-
-export async function inspectNpmPublicationReadiness(options: {
-  readonly repositoryRoot: string;
-  readonly packagePath: string;
-}): Promise<NpmPublicationReadiness> {
-  const repositoryRoot = path.resolve(options.repositoryRoot);
-  const packagePath = options.packagePath.split(path.sep).join("/");
-  const targetRoot = path.resolve(repositoryRoot, packagePath);
-  const safePackagePath =
-    /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/u.test(packagePath) &&
-    targetRoot.startsWith(`${repositoryRoot}${path.sep}`);
-  const manifestPath = `${packagePath}/package.json`;
-  const blockers: NpmPublicationReadinessBlocker[] = [];
-  if (!safePackagePath) {
-    blockers.push(
-      blocker({
-        code: "manifest-contract",
-        path: manifestPath,
-        observed: options.packagePath,
-        expected: "A safe two-segment Package Path inside the repository",
-        nextAction:
-          "Use the candidate Package Path projected by the repository.",
-      }),
-    );
-    return {
-      kind: "blocked",
-      mode: "public-intent",
-      target: { packagePath },
-      blockers: blockers as [
-        NpmPublicationReadinessBlocker,
-        ...NpmPublicationReadinessBlocker[],
-      ],
-    };
-  }
-
-  const [manifestFact, rootManifestFact] = await Promise.all([
-    textFact(path.join(repositoryRoot, manifestPath)),
-    textFact(path.join(repositoryRoot, "package.json")),
-  ]);
-  const manifest = parseJsonFact(manifestFact);
-  const rootManifest = parseJsonFact(rootManifestFact);
-  if (manifest === undefined) {
-    blockers.push(
-      blocker({
-        code: "manifest-contract",
-        path: manifestPath,
-        observed:
-          manifestFact.kind === "missing"
-            ? "missing"
-            : manifestFact.kind === "unreadable"
-              ? manifestFact.reason
-              : "Invalid JSON object",
-        expected: "A readable public CLI package manifest",
-        nextAction: "Restore the candidate package manifest.",
-      }),
-    );
-    return {
-      kind: "blocked",
-      mode: "public-intent",
-      target: { packagePath },
-      blockers: blockers as [
-        NpmPublicationReadinessBlocker,
-        ...NpmPublicationReadinessBlocker[],
-      ],
-    };
-  }
-
-  const mode =
-    manifest.private === true && manifest.version === undefined
-      ? "safe-unconfigured"
-      : "public-intent";
-  const identity = addManifestBlockers({
-    manifest,
-    manifestPath,
-    packagePath,
-    rootManifest,
-    blockers,
-  });
-  const documents = await addDocumentBlockers({
-    repositoryRoot,
-    packagePath,
-    ...(identity.version === undefined ? {} : { version: identity.version }),
-    ...(identity.license === undefined ? {} : { license: identity.license }),
-    blockers,
-  });
-  await addMetadataBlockers({
-    repositoryRoot,
-    packagePath,
-    ...(rootManifest === undefined ? {} : { rootManifest }),
-    ...(identity.packageName === undefined
-      ? {}
-      : { packageName: identity.packageName }),
-    blockers,
-  });
-
-  const workspaceFacts = await actualWorkspaceManifests(repositoryRoot);
-  for (const failure of workspaceFacts.failures) {
-    blockers.push(
-      blocker({
-        code: "manifest-contract",
-        path: failure.path,
-        observed: failure.reason,
-        expected: "Readable actual workspace package manifests",
-        nextAction: "Restore the generated workspace membership and manifests.",
-      }),
-    );
-  }
-  for (const dependencyName of runtimeDependencyNames(manifest)) {
-    const dependencyField =
-      isObject(manifest.dependencies) &&
-      Object.hasOwn(manifest.dependencies, dependencyName)
-        ? "dependencies"
-        : "optionalDependencies";
-    for (const dependency of workspaceFacts.manifests) {
-      if (
-        dependency.manifest.name !== dependencyName ||
-        dependency.manifest.private !== true
-      ) {
-        continue;
-      }
-      blockers.push(
-        blocker({
-          code: "private-runtime-dependency",
-          path: manifestPath,
-          pointer: `/${dependencyField}/${jsonPointerSegment(dependencyName)}`,
-          observed: `${dependencyName} resolves to private workspace package ${dependency.path}`,
-          expected: "Every direct public runtime dependency to be installable",
-          nextAction:
-            "Publish the dependency separately or remove the private runtime edge.",
-        }),
-      );
-    }
-  }
-
-  blockers.sort(compareBlockers);
-  if (blockers.length > 0) {
-    return {
-      kind: "blocked",
-      mode,
-      target: { packagePath },
-      blockers: blockers as [
-        NpmPublicationReadinessBlocker,
-        ...NpmPublicationReadinessBlocker[],
-      ],
-    };
-  }
-
-  return {
-    kind: "ready",
-    target: { packagePath },
-    blockers: [],
-    publication: {
-      packagePath,
-      packageName: identity.packageName!,
-      commandName: identity.commandName!,
-      version: identity.version!,
-      repository: identity.repository!.canonicalUrl,
-      releaseDate: documents.releaseDate!,
-      releaseNotes: documents.releaseNotes!,
-    },
-  };
-}