@ykdz/template 0.0.42 → 0.1.0-experimental.0

package/node_modules/@ykdz/template-workspace/dist/dependency-catalog.d.ts

@@ -0,0 +1,25 @@
+export type TemplateDependencyCatalog = Record<string, string>;
+export type GeneratedDependencyCatalogOptions = {
+    readonly dependencies: readonly string[];
+    readonly packages?: readonly string[];
+    readonly allowBuilds?: Record<string, boolean>;
+    readonly dependencyLinker?: {
+        readonly kind: "isolated";
+    } | {
+        readonly kind: "hoisted";
+        readonly evidence: string;
+    };
+    readonly minimumReleaseAgeExclude?: readonly string[];
+    readonly overrides?: Readonly<Record<string, string>>;
+};
+export type GeneratedPackageManifestDependencies = {
+    readonly dependencies?: Record<string, string>;
+    readonly devDependencies?: Record<string, string>;
+    readonly optionalDependencies?: Record<string, string>;
+    readonly peerDependencies?: Record<string, string>;
+};
+export declare function loadTemplateDependencyCatalog(): TemplateDependencyCatalog;
+export declare function selectTemplateDependencyCatalogEntries(dependencies: readonly string[], catalog?: TemplateDependencyCatalog): TemplateDependencyCatalog;
+export declare function collectGeneratedManifestCatalogReferences(manifests: readonly GeneratedPackageManifestDependencies[]): string[];
+export declare function pnpmWorkspaceYamlWithCatalogDependencies(workspaceYaml: string, dependencies: readonly string[], templateCatalog?: TemplateDependencyCatalog): string;
+export declare function renderGeneratedPnpmWorkspaceYaml(options: GeneratedDependencyCatalogOptions): string;

package/node_modules/@ykdz/template-workspace/dist/dependency-catalog.js

@@ -0,0 +1,159 @@
+import { dependencyCatalogSnapshot } from "./workspace-policy-snapshot.js";
+const exactNpmPackageIdentityPattern = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+function assertMinimumReleaseAgeExclusions(exclusions) {
+    if (exclusions.some((dependency) => dependency.length === 0)) {
+        throw new Error("Dependency maturity exclusions must be non-empty");
+    }
+    if (new Set(exclusions).size !== exclusions.length) {
+        throw new Error("Dependency maturity exclusions must be unique");
+    }
+    const invalid = exclusions.find((dependency) => dependency.length > 214 ||
+        !exactNpmPackageIdentityPattern.test(dependency));
+    if (invalid !== undefined) {
+        throw new Error(`Dependency maturity exclusions must be exact npm package identities: ${JSON.stringify(invalid)}`);
+    }
+}
+function parseTemplateCatalogSection(workspaceYaml, sectionName) {
+    const catalog = {};
+    const lines = workspaceYaml.split(/\r?\n/);
+    const catalogStart = lines.findIndex((line) => line === `${sectionName}:`);
+    if (catalogStart === -1) {
+        return catalog;
+    }
+    for (const line of lines.slice(catalogStart + 1)) {
+        if (line.length > 0 && !line.startsWith("  ")) {
+            break;
+        }
+        const match = /^  (?:"([^"]+)"|([^:]+)): (.+)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        const key = match[1] ?? match[2];
+        const version = match[3];
+        if (key === undefined || version === undefined) {
+            continue;
+        }
+        catalog[key] = version;
+    }
+    return catalog;
+}
+function parseTemplateDependencyCatalog(workspaceYaml) {
+    return parseTemplateCatalogSection(workspaceYaml, "catalog");
+}
+export function loadTemplateDependencyCatalog() {
+    return { ...dependencyCatalogSnapshot };
+}
+export function selectTemplateDependencyCatalogEntries(dependencies, catalog = loadTemplateDependencyCatalog()) {
+    const selected = {};
+    for (const dependency of dependencies.toSorted()) {
+        const version = catalog[dependency];
+        if (version === undefined) {
+            throw new Error(`Template Dependency Catalog is missing dependency: ${dependency}`);
+        }
+        selected[dependency] = version;
+    }
+    return selected;
+}
+export function collectGeneratedManifestCatalogReferences(manifests) {
+    const dependencies = new Set();
+    for (const manifest of manifests) {
+        for (const dependencyMap of [
+            manifest.dependencies,
+            manifest.devDependencies,
+            manifest.optionalDependencies,
+            manifest.peerDependencies,
+        ]) {
+            for (const [dependency, specifier] of Object.entries(dependencyMap ?? {})) {
+                if (specifier.startsWith("catalog:")) {
+                    dependencies.add(dependency);
+                }
+            }
+        }
+    }
+    return [...dependencies].toSorted();
+}
+function renderCatalogKey(key) {
+    return key.startsWith("@") ? JSON.stringify(key) : key;
+}
+export function pnpmWorkspaceYamlWithCatalogDependencies(workspaceYaml, dependencies, templateCatalog = loadTemplateDependencyCatalog()) {
+    const catalogStart = workspaceYaml
+        .split(/\r?\n/)
+        .findIndex((line) => line === "catalog:");
+    if (catalogStart === -1) {
+        throw new Error("Cannot update pnpm Dependency Catalog: missing catalog section");
+    }
+    const existingCatalog = parseTemplateDependencyCatalog(workspaceYaml);
+    const missingDependencies = dependencies.filter((dependency) => existingCatalog[dependency] === undefined);
+    if (missingDependencies.length === 0) {
+        return workspaceYaml;
+    }
+    const nextCatalog = {
+        ...existingCatalog,
+        ...selectTemplateDependencyCatalogEntries(missingDependencies, templateCatalog),
+    };
+    const lines = workspaceYaml.split(/\r?\n/);
+    const catalogEnd = lines.findIndex((line, index) => index > catalogStart && line.length > 0 && !line.startsWith("  "));
+    const replacementEnd = catalogEnd === -1 ? lines.length : catalogEnd;
+    const catalogLines = [
+        "catalog:",
+        ...Object.entries(nextCatalog)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([dependency, version]) => `  ${renderCatalogKey(dependency)}: ${version}`),
+        "",
+    ];
+    return [
+        ...lines.slice(0, catalogStart),
+        ...catalogLines,
+        ...lines.slice(replacementEnd),
+    ].join("\n");
+}
+export function renderGeneratedPnpmWorkspaceYaml(options) {
+    const minimumReleaseAgeExclude = options.minimumReleaseAgeExclude ?? [];
+    assertMinimumReleaseAgeExclusions(minimumReleaseAgeExclude);
+    if (options.dependencyLinker?.kind === "hoisted" &&
+        (options.dependencyLinker.evidence.trim().length === 0 ||
+            options.dependencyLinker.evidence.includes("\n"))) {
+        throw new Error("Hoisted linking requires single-line compatibility evidence");
+    }
+    const catalog = selectTemplateDependencyCatalogEntries(options.dependencies);
+    const packages = options.packages ?? ["."];
+    const dependencyLinker = options.dependencyLinker?.kind ?? "isolated";
+    const lines = [
+        "packages:",
+        ...packages.map((workspacePackage) => `  - ${workspacePackage}`),
+        "",
+        ...(options.dependencyLinker?.kind === "hoisted"
+            ? [
+                `# Hoisted linker compatibility evidence: ${options.dependencyLinker.evidence}`,
+            ]
+            : []),
+        `nodeLinker: ${dependencyLinker}`,
+        "autoInstallPeers: false",
+        "resolvePeersFromWorkspaceRoot: false",
+        "injectWorkspacePackages: false",
+        "dedupeInjectedDeps: false",
+        "syncInjectedDepsAfterScripts:",
+        "  - build",
+        "minimumReleaseAge: 1440",
+        "minimumReleaseAgeStrict: true",
+        "",
+    ];
+    if (minimumReleaseAgeExclude.length) {
+        lines.push("minimumReleaseAgeExclude:", ...minimumReleaseAgeExclude
+            .toSorted()
+            .map((dependency) => `  - ${JSON.stringify(dependency)}`), "");
+    }
+    if (options.allowBuilds) {
+        lines.push("allowBuilds:", ...Object.entries(options.allowBuilds)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([dependency, allowed]) => `  ${dependency}: ${allowed}`), "");
+    }
+    const overrides = options.overrides ?? {};
+    if (Object.keys(overrides).length > 0) {
+        lines.push("overrides:", ...Object.entries(overrides)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([dependency, version]) => `  ${JSON.stringify(dependency)}: ${JSON.stringify(version)}`), "");
+    }
+    lines.push("catalog:", ...Object.entries(catalog).map(([dependency, version]) => `  ${renderCatalogKey(dependency)}: ${version}`), "");
+    return lines.join("\n");
+}

package/node_modules/@ykdz/template-workspace/dist/development-container.d.ts

@@ -0,0 +1,3 @@
+import type { DevelopmentContainerToolLayer } from "@ykdz/template-environment/development-container-tool-layer";
+/** 工作区当前 Playwright 事实由工作区持有，再交给环境层构造资源。 */
+export declare function browserTestDevelopmentContainerToolLayer(): DevelopmentContainerToolLayer;

package/node_modules/@ykdz/template-workspace/dist/development-container.js

@@ -0,0 +1,36 @@
+import { environmentSources } from "./default-environment-sources.js";
+import { loadTemplateDependencyCatalog } from "./dependency-catalog.js";
+/** 工作区当前 Playwright 事实由工作区持有，再交给环境层构造资源。 */
+export function browserTestDevelopmentContainerToolLayer() {
+    const playwrightTestVersion = loadTemplateDependencyCatalog()["@playwright/test"];
+    if (playwrightTestVersion === undefined) {
+        throw new Error("模板依赖目录缺少依赖：@playwright/test");
+    }
+    return {
+        identity: "browser-test",
+        dockerfile: {
+            source: environmentSources.devcontainer,
+            from: "browser-test.Dockerfile",
+        },
+        requires: ["node-pnpm"],
+        buildArguments: [
+            {
+                name: "PLAYWRIGHT_CLI_PACKAGE",
+                value: `@playwright/test@${playwrightTestVersion}`,
+            },
+        ],
+        probes: [
+            {
+                identity: "playwright",
+                command: "npx",
+                args: [
+                    "--yes",
+                    "--package",
+                    `@playwright/test@${playwrightTestVersion}`,
+                    "playwright",
+                    "--version",
+                ],
+            },
+        ],
+    };
+}

package/node_modules/@ykdz/template-workspace/dist/development-environment.d.ts

@@ -0,0 +1,36 @@
+import { type WriteTextOperation } from "@ykdz/template-core/renderer";
+import { type DevelopmentContainerToolLayer, type DevelopmentContainerToolLayerPlan } from "@ykdz/template-environment/development-container-tool-layer";
+import { loadEditorCustomizationDeclarations, type EditorCustomization, type EditorCustomizationCapability } from "./editor-customization.ts";
+export declare function githubCliDevelopmentContainerToolLayer(): DevelopmentContainerToolLayer;
+export declare function browserTestDevelopmentContainerToolLayer(playwrightTestVersion: string): DevelopmentContainerToolLayer;
+export type PreparedBuiltInDevelopmentContainerResources = {
+    readonly configuration: Readonly<Record<string, unknown>> & {
+        readonly features: Readonly<Record<string, Record<string, unknown>>>;
+    };
+    readonly dockerfileFragments: Readonly<Record<string, string>>;
+};
+/** 环境 owner 在工作区策略准备阶段读取其有限配置与 Dockerfile 资源。 */
+export declare function prepareBuiltInDevelopmentContainerResources(): PreparedBuiltInDevelopmentContainerResources;
+declare function completeBuiltInDevelopmentContainer(options: {
+    readonly nodeVersion: string;
+    readonly layers?: readonly DevelopmentContainerToolLayer[];
+    readonly resources: PreparedBuiltInDevelopmentContainerResources;
+}): DevelopmentContainerToolLayerPlan & {
+    readonly configuration: PreparedBuiltInDevelopmentContainerResources["configuration"];
+    readonly features: Readonly<Record<string, Record<string, unknown>>>;
+    readonly dockerfileOperation: WriteTextOperation;
+};
+/** 只消费所属环境准备事实并投影所选开发容器能力。 */
+export declare function projectBuiltInDevelopmentContainer(options: {
+    readonly nodeVersion: string;
+    readonly layers?: readonly DevelopmentContainerToolLayer[];
+    readonly resources: PreparedBuiltInDevelopmentContainerResources;
+}): ReturnType<typeof completeBuiltInDevelopmentContainer>;
+/** 非生成策略消费者的便利入口；生成策略应先准备再调用纯 project。 */
+export declare function rustDevelopmentContainerToolLayer(rustVersion: string): DevelopmentContainerToolLayer;
+export declare function shellCheckDevelopmentContainerToolLayer(): DevelopmentContainerToolLayer;
+/** 环境 owner 在策略准备阶段读取并验证编辑器能力声明。 */
+export declare function prepareBuiltInEditorCustomizationDeclarations(): import("./editor-customization.ts").EditorCustomizationDeclarations;
+/** 只组合已准备的编辑器声明与实际能力。 */
+export declare function projectBuiltInEditorCustomization(capabilities: readonly EditorCustomizationCapability[], declarations: ReturnType<typeof loadEditorCustomizationDeclarations>): EditorCustomization;
+export {};

package/node_modules/@ykdz/template-workspace/dist/development-environment.js

@@ -0,0 +1,241 @@
+import { readFileSync } from "node:fs";
+import { resolveTemplateSource, } from "@ykdz/template-core/renderer";
+import { developmentContainerDockerfileFromText, planDevelopmentContainerToolLayersFromTexts, } from "@ykdz/template-environment/development-container-tool-layer";
+import { environmentSources } from "./default-environment-sources.js";
+import { editorCustomizationForCapabilities, loadEditorCustomizationDeclarations, } from "./editor-customization.js";
+export function githubCliDevelopmentContainerToolLayer() {
+    return {
+        identity: "github-cli",
+        dockerfile: {
+            source: environmentSources.devcontainer,
+            from: "github-cli.Dockerfile",
+        },
+        requires: ["node-pnpm"],
+        probes: [
+            {
+                identity: "github-cli",
+                command: "gh",
+                args: ["--version"],
+            },
+        ],
+    };
+}
+export function browserTestDevelopmentContainerToolLayer(playwrightTestVersion) {
+    return {
+        identity: "browser-test",
+        dockerfile: {
+            source: environmentSources.devcontainer,
+            from: "browser-test.Dockerfile",
+        },
+        requires: ["node-pnpm"],
+        buildArguments: [
+            {
+                name: "PLAYWRIGHT_CLI_PACKAGE",
+                value: `@playwright/test@${playwrightTestVersion}`,
+            },
+        ],
+        probes: [
+            {
+                identity: "playwright",
+                command: "npx",
+                args: [
+                    "--yes",
+                    "--package",
+                    `@playwright/test@${playwrightTestVersion}`,
+                    "playwright",
+                    "--version",
+                ],
+            },
+        ],
+    };
+}
+const builtInDockerfileResources = [
+    "base.Dockerfile",
+    "github-cli.Dockerfile",
+    "rust.Dockerfile",
+    "browser-test.Dockerfile",
+    "shellcheck.Dockerfile",
+];
+/** 环境 owner 在工作区策略准备阶段读取其有限配置与 Dockerfile 资源。 */
+export function prepareBuiltInDevelopmentContainerResources() {
+    const read = (source, file) => {
+        try {
+            return readFileSync(resolveTemplateSource(source, file), "utf8");
+        }
+        catch (cause) {
+            throw new Error(`默认环境资源 @ykdz/template-workspace#./default-environment prepare 阶段无法读取 ${file}`, { cause });
+        }
+    };
+    const dockerfileFragments = Object.fromEntries(builtInDockerfileResources.map((file) => [
+        file,
+        read(file === "base.Dockerfile"
+            ? environmentSources.base
+            : environmentSources.devcontainer, file),
+    ]));
+    let configuration;
+    try {
+        configuration = JSON.parse(readFileSync(resolveTemplateSource(environmentSources.devcontainer, "workspace-template.json"), "utf8"));
+    }
+    catch (cause) {
+        throw new Error("默认环境资源 @ykdz/template-workspace#./default-environment prepare 阶段无法读取 workspace-template.json", { cause });
+    }
+    return { configuration, dockerfileFragments };
+}
+function baseDevelopmentContainerToolLayer(nodeVersion) {
+    return {
+        identity: "node-pnpm",
+        dockerfile: { source: environmentSources.base, from: "base.Dockerfile" },
+        buildArguments: [{ name: "NODE_VERSION", value: nodeVersion }],
+        probes: [
+            { identity: "procps", command: "ps", args: ["--version"] },
+            { identity: "bubblewrap", command: "bwrap", args: ["--version"] },
+            {
+                identity: "awk",
+                command: "awk",
+                args: ["BEGIN { exit (6 * 7 != 42) }"],
+            },
+            { identity: "ripgrep", command: "rg", args: ["--version"] },
+            {
+                identity: "jq",
+                command: "jq",
+                args: ["--exit-status", "--null-input", "{ ready: true } | .ready"],
+            },
+            {
+                identity: "python3",
+                command: "python3",
+                args: [
+                    "-c",
+                    'import json, pathlib, sqlite3, urllib.request; assert json.loads("true") is True',
+                ],
+            },
+            {
+                identity: "python",
+                command: "python",
+                args: [
+                    "-c",
+                    'import os, shutil, sys; assert sys.version_info.major == 3; assert os.path.samefile(sys.executable, shutil.which("python3"))',
+                ],
+            },
+            { identity: "openssh-client", command: "ssh", args: ["-V"] },
+            { identity: "unzip", command: "unzip", args: ["-v"] },
+            { identity: "file", command: "file", args: ["--version"] },
+            { identity: "iproute2", command: "ss", args: ["--version"] },
+        ],
+        mounts: [
+            {
+                identity: "pnpm-store",
+                type: "volume",
+                source: "${devcontainerId}-pnpm-store",
+                target: "/pnpm/store",
+            },
+        ],
+    };
+}
+function completeBuiltInDevelopmentContainer(options) {
+    const layers = [
+        githubCliDevelopmentContainerToolLayer(),
+        ...(options.layers ?? []),
+    ];
+    const plan = planDevelopmentContainerToolLayersFromTexts({
+        baseLayer: baseDevelopmentContainerToolLayer(options.nodeVersion),
+        layers,
+        fragmentTexts: options.resources.dockerfileFragments,
+    });
+    return {
+        ...plan,
+        configuration: options.resources.configuration,
+        features: options.resources.configuration.features,
+        dockerfileOperation: developmentContainerDockerfileFromText({
+            layers: plan.layers,
+            fragmentTexts: options.resources.dockerfileFragments,
+        }),
+        probes: [
+            ...plan.probes,
+            {
+                identity: "docker-daemon",
+                command: "docker",
+                args: ["version"],
+                failureMessage: "无法连接宿主 Docker；请检查宿主 daemon 是否运行，以及开发容器 Feature 的连接配置与权限。",
+            },
+            {
+                identity: "docker-buildx",
+                command: "docker",
+                args: ["buildx", "version"],
+                failureMessage: "Buildx 不可用；请重建开发容器以完成官方 Feature 安装。",
+            },
+            {
+                identity: "docker-compose",
+                command: "docker",
+                args: ["compose", "version"],
+                failureMessage: "Compose 不可用；请重建开发容器以完成官方 Feature 安装。",
+            },
+        ],
+    };
+}
+/** 只消费所属环境准备事实并投影所选开发容器能力。 */
+export function projectBuiltInDevelopmentContainer(options) {
+    return completeBuiltInDevelopmentContainer(options);
+}
+/** 非生成策略消费者的便利入口；生成策略应先准备再调用纯 project。 */
+export function rustDevelopmentContainerToolLayer(rustVersion) {
+    return {
+        identity: "rust",
+        dockerfile: {
+            source: environmentSources.devcontainer,
+            from: "rust.Dockerfile",
+        },
+        requires: ["node-pnpm"],
+        buildArguments: [{ name: "RUST_TOOLCHAIN", value: rustVersion }],
+        mounts: [
+            {
+                identity: "cargo-registry",
+                type: "volume",
+                source: "${devcontainerId}-cargo-registry",
+                target: "/usr/local/cargo/registry",
+            },
+            {
+                identity: "cargo-git",
+                type: "volume",
+                source: "${devcontainerId}-cargo-git",
+                target: "/usr/local/cargo/git",
+            },
+        ],
+        probes: [
+            { identity: "cargo", command: "cargo", args: ["--version"] },
+            { identity: "rustc", command: "rustc", args: ["--version"] },
+            { identity: "rustfmt", command: "cargo", args: ["fmt", "--version"] },
+            { identity: "clippy", command: "cargo", args: ["clippy", "--version"] },
+        ],
+    };
+}
+export function shellCheckDevelopmentContainerToolLayer() {
+    return {
+        identity: "shellcheck",
+        dockerfile: {
+            source: environmentSources.devcontainer,
+            from: "shellcheck.Dockerfile",
+        },
+        requires: ["node-pnpm"],
+        probes: [
+            { identity: "shellcheck", command: "shellcheck", args: ["--version"] },
+        ],
+    };
+}
+/** 环境 owner 在策略准备阶段读取并验证编辑器能力声明。 */
+export function prepareBuiltInEditorCustomizationDeclarations() {
+    try {
+        return loadEditorCustomizationDeclarations(resolveTemplateSource(environmentSources.editorCustomization, "capabilities.json"), "@ykdz/template-workspace#./assets/environment/editor-customization/capabilities.json");
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(`默认环境资源 @ykdz/template-workspace#./default-environment prepare 阶段失败：${detail}`, { cause });
+    }
+}
+/** 只组合已准备的编辑器声明与实际能力。 */
+export function projectBuiltInEditorCustomization(capabilities, declarations) {
+    const unknownCapability = capabilities.find((capability) => !declarations.capabilityOrder.includes(capability));
+    if (unknownCapability !== undefined) {
+        throw new Error(`未声明的编辑器能力：${unknownCapability}`);
+    }
+    return editorCustomizationForCapabilities(capabilities, declarations);
+}

package/node_modules/@ykdz/template-workspace/dist/editor-customization.d.ts

@@ -0,0 +1,18 @@
+/** 能力身份由默认工作区策略提供。 */
+export type EditorCustomizationCapability = string;
+export type EditorCustomization = {
+    readonly extensions: readonly string[];
+    readonly settings: Record<string, unknown>;
+};
+type CapabilityProjection = {
+    readonly extensions: readonly string[];
+    readonly settings: Record<string, unknown>;
+};
+export type EditorCustomizationDeclarations = {
+    readonly source: string;
+    readonly capabilityOrder: readonly EditorCustomizationCapability[];
+    readonly capabilities: Readonly<Record<EditorCustomizationCapability, CapabilityProjection>>;
+};
+export declare function loadEditorCustomizationDeclarations(resourcePath: string, sourceLabel: string): EditorCustomizationDeclarations;
+export declare function editorCustomizationForCapabilities(capabilities: readonly EditorCustomizationCapability[], declarations: EditorCustomizationDeclarations): EditorCustomization;
+export {};

package/node_modules/@ykdz/template-workspace/dist/editor-customization.js

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import * as v from "valibot";
+const capabilityProjectionSchema = v.object({
+    extensions: v.array(v.string()),
+    settings: v.record(v.string(), v.unknown()),
+});
+const editorCustomizationDeclarationsSchema = v.object({
+    capabilityOrder: v.array(v.string()),
+    capabilities: v.record(v.string(), capabilityProjectionSchema),
+});
+function editorCustomizationDeclarationIssuePath(issue) {
+    const segments = issue.path?.flatMap((item) => typeof item.key === "string" || typeof item.key === "number"
+        ? [String(item.key)]
+        : []) ?? [];
+    return segments.length === 0 ? "$" : `$.${segments.join(".")}`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function editorCustomizationSharedResourceLabel(resourcePath) {
+    return `编辑器定制共享资源 ${resourcePath}`;
+}
+export function loadEditorCustomizationDeclarations(resourcePath, sourceLabel) {
+    const resourceLabel = editorCustomizationSharedResourceLabel(resourcePath);
+    let resourceText;
+    try {
+        resourceText = readFileSync(resourcePath, "utf8");
+    }
+    catch (error) {
+        throw new Error(`${resourceLabel} 无法读取：${errorMessage(error)}`, {
+            cause: error,
+        });
+    }
+    let parsedSource;
+    try {
+        parsedSource = JSON.parse(resourceText);
+    }
+    catch (error) {
+        throw new Error(`${resourceLabel} 内容无效：JSON 语法错误：${errorMessage(error)}`, { cause: error });
+    }
+    const result = v.safeParse(editorCustomizationDeclarationsSchema, parsedSource);
+    if (!result.success) {
+        throw new Error(`${resourceLabel} 内容无效：${result.issues
+            .map((issue) => `${editorCustomizationDeclarationIssuePath(issue)}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    return { ...result.output, source: sourceLabel };
+}
+function jsonPointerToken(value) {
+    return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+export function editorCustomizationForCapabilities(capabilities, declarations) {
+    const selected = new Set(capabilities);
+    const extensions = new Set();
+    const settings = {};
+    const settingSources = new Map();
+    for (const capability of declarations.capabilityOrder) {
+        if (!selected.has(capability)) {
+            continue;
+        }
+        const projection = declarations.capabilities[capability];
+        if (projection === undefined) {
+            throw new Error(`编辑器定制策略列出了未声明的能力：${capability}`);
+        }
+        for (const extension of projection.extensions) {
+            extensions.add(extension);
+        }
+        for (const [setting, value] of Object.entries(projection.settings)) {
+            const source = `${declarations.source}#/capabilities/${jsonPointerToken(capability)}/settings/${jsonPointerToken(setting)}`;
+            const previous = settingSources.get(setting);
+            if (previous !== undefined && !isDeepStrictEqual(previous.value, value)) {
+                throw new Error(`编辑器设置 /settings/${jsonPointerToken(setting)} 冲突：${previous.source} 与 ${source}`);
+            }
+            settingSources.set(setting, { source, value });
+            settings[setting] = value;
+        }
+    }
+    return {
+        extensions: [...extensions],
+        settings,
+    };
+}

package/node_modules/@ykdz/template-workspace/dist/environment-needs.d.ts

@@ -0,0 +1,51 @@
+export type PackageBoundaryOwner = {
+    readonly kind: "package-boundary";
+    readonly path: string;
+};
+export type WorkspaceOrchestrationOwner = {
+    readonly kind: "workspace-orchestration";
+    readonly path: ".";
+};
+export type ComponentOwner = PackageBoundaryOwner | WorkspaceOrchestrationOwner;
+export type PlaywrightBrowserAssetsEnvironmentNeed = {
+    readonly kind: "playwright-browser-assets";
+    readonly browser: "chromium";
+    readonly owner: ComponentOwner;
+};
+export type ShellCheckEnvironmentNeed = {
+    readonly kind: "shellcheck-command";
+    readonly owner: ComponentOwner;
+};
+/** Rust 任务必须在本地与 CI 计划中使用已维护的工具链。 */
+export type RustToolchainEnvironmentNeed = {
+    readonly kind: "rust-toolchain";
+    readonly owner: ComponentOwner;
+    readonly toolchain: "stable";
+};
+/**
+ * Docker 仅在独立部署验收中使用，不属于应用于所有生成检查场景的常规检查环境需求。
+ */
+export type DockerEngineEnvironmentNeed = {
+    readonly kind: "docker-engine";
+};
+export type CheckEnvironmentNeed = PlaywrightBrowserAssetsEnvironmentNeed | ShellCheckEnvironmentNeed | RustToolchainEnvironmentNeed;
+export type DeploymentEnvironmentNeed = DockerEngineEnvironmentNeed;
+export type EnvironmentNeedsMetadata = {
+    readonly schemaVersion: 1;
+    readonly check: readonly CheckEnvironmentNeed[];
+    readonly deployment: readonly DeploymentEnvironmentNeed[];
+};
+/** 校验、去重并按固定顺序排列持久化环境需求。 */
+export declare function normalizeEnvironmentNeeds(options: {
+    readonly check: readonly CheckEnvironmentNeed[];
+    readonly deployment: readonly DeploymentEnvironmentNeed[];
+}): EnvironmentNeedsMetadata;
+/** 严格解析加包流程消费的本地模板元数据。 */
+export declare function parseEnvironmentNeedsMetadata(value: unknown): EnvironmentNeedsMetadata;
+export declare function rustToolchainEnvironmentNeed(owner: ComponentOwner): RustToolchainEnvironmentNeed;
+export declare function dockerEngineEnvironmentNeed(): DockerEngineEnvironmentNeed;
+export declare function playwrightBrowserAssetsEnvironmentNeed(options: {
+    readonly browser: "chromium";
+    readonly owner: ComponentOwner;
+}): PlaywrightBrowserAssetsEnvironmentNeed;
+export declare function shellCheckEnvironmentNeed(owner: ComponentOwner): ShellCheckEnvironmentNeed;