@ykdz/template 0.0.42 → 0.1.0-experimental.0

package/node_modules/@ykdz/template-workspace/dist/root-projection.js

@@ -0,0 +1,144 @@
+import { mapPackageNamesInJson } from "@ykdz/template-workspace-authoring/package-name-projection";
+import { stringify as stringifyYaml } from "yaml";
+import { workspaceInstallPolicySnapshot } from "./workspace-policy-snapshot.js";
+export const packageManifestKeyOrder = [
+    "name",
+    "version",
+    "private",
+    "bin",
+    "files",
+    "type",
+    "types",
+    "imports",
+    "exports",
+    "publishConfig",
+    "scripts",
+    "dependencies",
+    "devDependencies",
+    "dependenciesMeta",
+    "peerDependencies",
+    "optionalDependencies",
+    "engines",
+    "packageManager",
+];
+export const packageConditionKeyOrder = ["source", "types", "default"];
+export function createWorkspaceRootManifest(options) {
+    const scripts = {
+        check: "node --conditions=source scripts/task-gates.ts check",
+        "check:heavy": "node --conditions=source scripts/task-gates.ts check:heavy",
+        "check:full": "node --conditions=source scripts/task-gates.ts check:full",
+        boundaries: "turbo boundaries",
+        fix: "node --conditions=source scripts/task-gates.ts fix",
+        "format:check": "oxfmt --list-different --no-error-on-unmatched-pattern *.json pnpm-workspace.yaml pnpm-lock.yaml *.config.ts .gitignore .dockerignore Dockerfile TODO.md rust-toolchain.toml .vscode .github .devcontainer scripts",
+        "format:write": "oxfmt --write --no-error-on-unmatched-pattern *.json pnpm-workspace.yaml pnpm-lock.yaml *.config.ts .gitignore .dockerignore Dockerfile TODO.md rust-toolchain.toml .vscode .github .devcontainer scripts",
+        lint: "oxlint --quiet --format=unix --no-error-on-unmatched-pattern *.config.ts scripts",
+        "lint:fix": "oxlint --format=unix --no-error-on-unmatched-pattern *.config.ts scripts --fix",
+        typecheck: "tsc --build --noEmit --pretty false",
+    };
+    const developmentDependencies = {
+        ...(options.toolingConfigPackageName === undefined
+            ? {}
+            : {
+                [options.toolingConfigPackageName]: "workspace:*",
+            }),
+        "@types/node": "catalog:",
+        oxfmt: "catalog:",
+        oxlint: "catalog:",
+        "oxlint-tsgolint": "catalog:",
+        "smol-toml": "catalog:",
+        turbo: "catalog:",
+        "typescript-7": "catalog:",
+    };
+    return {
+        name: options.name,
+        private: true,
+        type: "module",
+        scripts,
+        devDependencies: developmentDependencies,
+        engines: { node: options.nodeDeclaration },
+        packageManager: options.packageManagerPin,
+    };
+}
+export function projectPreparedWorkspaceRoot(options) {
+    // 作者仓的发布时间豁免不作为生成仓的默认策略。
+    const { minimumReleaseAgeExclude: _minimumReleaseAgeExclude, ...installPolicy } = workspaceInstallPolicySnapshot;
+    const workspace = {
+        ...installPolicy,
+        packages: options.packageGlobs,
+        overrides: options.dependencyOverrides,
+        catalog: options.dependencyCatalog,
+    };
+    const rootTurbo = mapPackageNamesInJson(options.turboTemplate, options.referenceNames);
+    rootTurbo.globalDependencies = [
+        ...new Set([
+            ...(rootTurbo.globalDependencies ?? []),
+            ...(options.toolingConfigPackagePath === undefined
+                ? []
+                : [
+                    `${options.toolingConfigPackagePath}/oxfmt.config.ts`,
+                    `${options.toolingConfigPackagePath}/oxlint.config.ts`,
+                ]),
+        ]),
+    ];
+    rootTurbo.tasks = Object.fromEntries(Object.entries(rootTurbo.tasks).filter(([task]) => task.startsWith("//#") &&
+        Object.hasOwn((options.rootManifest.scripts ?? {}), task.slice(3))));
+    if (rootTurbo.boundaries !== undefined &&
+        options.turboBoundaryTags !== undefined) {
+        rootTurbo.boundaries.tags = Object.fromEntries(Object.entries(rootTurbo.boundaries.tags).filter(([tag]) => options.turboBoundaryTags?.includes(tag)));
+    }
+    const rootConfig = {
+        ...mapPackageNamesInJson(options.tsconfigConfigTemplate, options.referenceNames),
+        compilerOptions: {
+            ...(options.tsconfigConfigTemplate.compilerOptions ?? {}),
+            ...options.rootTsconfigCompilerOptions,
+            composite: false,
+            noEmit: true,
+            tsBuildInfoFile: "./node_modules/.tmp/tsconfig.config.tsbuildinfo",
+        },
+        include: options.rootTsconfigInclude.filter((entry) => !entry.startsWith("scripts/")),
+    };
+    return {
+        manifest: {
+            kind: "writeJson",
+            to: "package.json",
+            value: options.rootManifest,
+            keyOrder: packageManifestKeyOrder,
+            nestedKeyOrder: packageConditionKeyOrder,
+        },
+        workspace: {
+            kind: "writeText",
+            to: "pnpm-workspace.yaml",
+            text: stringifyYaml(workspace),
+        },
+        turbo: { kind: "writeJson", to: "turbo.json", value: rootTurbo },
+        tsconfig: {
+            kind: "writeJson",
+            to: "tsconfig.json",
+            value: {
+                files: [],
+                references: [
+                    { path: "./tsconfig.config.json" },
+                    { path: "./tsconfig.scripts.json" },
+                ],
+            },
+        },
+        tsconfigConfig: {
+            kind: "writeJson",
+            to: "tsconfig.config.json",
+            value: rootConfig,
+        },
+        tsconfigScripts: {
+            kind: "writeJson",
+            to: "tsconfig.scripts.json",
+            value: {
+                ...rootConfig,
+                compilerOptions: {
+                    ...rootConfig.compilerOptions,
+                    erasableSyntaxOnly: true,
+                    tsBuildInfoFile: "./node_modules/.tmp/tsconfig.scripts.tsbuildinfo",
+                },
+                include: ["scripts/**/*.ts"],
+            },
+        },
+    };
+}

package/node_modules/@ykdz/template-workspace/dist/rust-target-projection.d.ts

@@ -0,0 +1,35 @@
+import type { ContentIdentity, LoadedContentMember } from "@ykdz/template-core/content-identity";
+import type { RenderOperation } from "@ykdz/template-core/renderer";
+import type { GeneratorPackageState, GeneratorSelectionRoot } from "@ykdz/template-core/workspace-strategy";
+import type { GenerationContext } from "./generation-context.ts";
+import type { PackageContribution } from "./package-contribution.ts";
+type RustToolchain = NonNullable<PackageContribution["foundation"]["toolchains"]["rust"]> & {
+    readonly configurationText: string;
+};
+type RustContent = LoadedContentMember<{
+    readonly requiresRootRustToolchain?: true;
+}, "reference">;
+/** 默认策略从被选中的原生 Rust 内容初始化其根工具链版本。 */
+export declare function initialRustVersion(selection: readonly GeneratorSelectionRoot[], contentByIdentity: ReadonlyMap<string, RustContent>): string | undefined;
+/** 加包准备读取现有根声明一次，投影只消费声明快照。 */
+export declare function prepareRustTargetAddition(options: {
+    readonly targetRoot: string;
+    readonly packages: readonly GeneratorPackageState[];
+    readonly contentIdentity: ContentIdentity;
+    readonly contentByIdentity: ReadonlyMap<string, RustContent>;
+}): {
+    readonly rustVersion?: string;
+    readonly existingDeclaration?: string;
+};
+/** 默认策略纯投影 Rust 根声明，并在已有 Rust 仓库加包时保留原始字节。 */
+export declare function projectRustTarget(options: {
+    readonly context: GenerationContext & {
+        readonly existingRustDeclaration?: string;
+    };
+    readonly packages: readonly GeneratorPackageState[];
+    readonly contributions: readonly PackageContribution[];
+}): {
+    readonly toolchain: RustToolchain | undefined;
+    readonly operation: RenderOperation | undefined;
+};
+export {};

package/node_modules/@ykdz/template-workspace/dist/rust-target-projection.js

@@ -0,0 +1,74 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { contentIdentityKey, isContentIdentity, } from "@ykdz/template-core/content-identity";
+import { projectTomlStringValues } from "@ykdz/template-core/toml";
+import { releaseToolchainSnapshot } from "./release-toolchain-snapshot.js";
+import { readRootRustToolchainDeclaration, rootRustDeclarationFileName, } from "./rust-toolchain-facts.js";
+function isRustContent(content) {
+    return content?.definition.requiresRootRustToolchain === true;
+}
+/** 默认策略从被选中的原生 Rust 内容初始化其根工具链版本。 */
+export function initialRustVersion(selection, contentByIdentity) {
+    return selection.some((root) => isContentIdentity(root.contentIdentity) &&
+        isRustContent(contentByIdentity.get(contentIdentityKey(root.contentIdentity))))
+        ? releaseToolchainSnapshot.rustVersion
+        : undefined;
+}
+/** 加包准备读取现有根声明一次，投影只消费声明快照。 */
+export function prepareRustTargetAddition(options) {
+    const hasRustPackage = options.packages.some((record) => isRustContent(options.contentByIdentity.get(contentIdentityKey(record.contentIdentity))));
+    const addsRustPackage = isRustContent(options.contentByIdentity.get(contentIdentityKey(options.contentIdentity)));
+    if (!hasRustPackage && !addsRustPackage)
+        return {};
+    const declarationPath = path.join(options.targetRoot, rootRustDeclarationFileName);
+    if (hasRustPackage || existsSync(declarationPath)) {
+        const declaration = readRootRustToolchainDeclaration(options.targetRoot);
+        return {
+            rustVersion: declaration.channel,
+            existingDeclaration: declaration.declaration,
+        };
+    }
+    return { rustVersion: releaseToolchainSnapshot.rustVersion };
+}
+function rustToolchain(contributions) {
+    const declarations = contributions.flatMap((contribution) => {
+        const rust = contribution.foundation.toolchains.rust;
+        if (rust === undefined)
+            return [];
+        if (typeof rust.configurationText !== "string") {
+            throw new Error("Rust 工具链能力缺少 prepare 阶段配置文本");
+        }
+        return [{ ...rust, configurationText: rust.configurationText }];
+    });
+    const fingerprints = declarations.map((rust) => JSON.stringify({
+        toolchain: rust.toolchain,
+        components: [...new Set(rust.components)].toSorted(),
+        configurationText: rust.configurationText,
+    }));
+    if (new Set(fingerprints).size > 1) {
+        throw new Error("工作区要求所有 Rust 工具链声明相互兼容");
+    }
+    return declarations[0];
+}
+/** 默认策略纯投影 Rust 根声明，并在已有 Rust 仓库加包时保留原始字节。 */
+export function projectRustTarget(options) {
+    const toolchain = rustToolchain(options.contributions);
+    if (toolchain === undefined)
+        return { toolchain, operation: undefined };
+    const wasAddition = options.packages.some((record) => record.createdBy === "addition");
+    const existingDeclaration = wasAddition
+        ? options.context.existingRustDeclaration
+        : undefined;
+    const text = existingDeclaration ??
+        projectTomlStringValues(toolchain.configurationText, [
+            { path: ["toolchain", "channel"], value: toolchain.toolchain },
+        ]);
+    return {
+        toolchain,
+        operation: {
+            kind: "writeText",
+            to: rootRustDeclarationFileName,
+            text,
+        },
+    };
+}

package/node_modules/@ykdz/template-workspace/dist/rust-toolchain-facts.d.ts

@@ -0,0 +1,22 @@
+export declare const rootRustDeclarationFileName = "rust-toolchain.toml";
+export declare class RustToolchainDeclarationFailure extends Error {
+    readonly field = "[toolchain].channel";
+    readonly suggestion: string;
+    constructor(requirement: string, actualDeclaration: string, suggestion: string);
+}
+/** 已有 Rust 仓库的加包版本和待保留字节均由根声明拥有。 */
+export declare function readRootRustToolchainDeclaration(repositoryRoot: string): {
+    readonly channel: string;
+    readonly declaration: string;
+};
+/** 已有 Rust 仓库的加包版本由根 rust-toolchain.toml 当前 channel 拥有。 */
+export declare function readRootRustToolchainChannel(repositoryRoot: string): string;
+export type RustToolchainChannelReading = {
+    readonly channel: string;
+    readonly status: "explained";
+} | {
+    readonly reason: string;
+    readonly status: "unreadable";
+};
+/** 从模板投影的 Rust 声明结构化读取根 channel，供工具链镜像校验共用。 */
+export declare function readRustToolchainChannelFromToml(contents: string): RustToolchainChannelReading;

package/node_modules/@ykdz/template-workspace/dist/rust-toolchain-facts.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseToml } from "smol-toml";
+export const rootRustDeclarationFileName = "rust-toolchain.toml";
+const rootRustToolchainChannelField = "[toolchain].channel";
+export class RustToolchainDeclarationFailure extends Error {
+    field = rootRustToolchainChannelField;
+    suggestion;
+    constructor(requirement, actualDeclaration, suggestion) {
+        super(`加包需要目标仓库根 ${rootRustDeclarationFileName} 的 ${rootRustToolchainChannelField} ${requirement}，实际收到 ${actualDeclaration}。${suggestion}`);
+        this.suggestion = suggestion;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 已有 Rust 仓库的加包版本和待保留字节均由根声明拥有。 */
+export function readRootRustToolchainDeclaration(repositoryRoot) {
+    const filePath = path.join(repositoryRoot, rootRustDeclarationFileName);
+    if (!existsSync(filePath)) {
+        throw new RustToolchainDeclarationFailure("存在", "文件不存在", `请先创建根 ${rootRustDeclarationFileName}，在 [toolchain] 表内声明 channel 再加包。`);
+    }
+    let declarationText;
+    let declaration;
+    try {
+        declarationText = readFileSync(filePath, "utf8");
+        declaration = parseToml(declarationText);
+    }
+    catch (error) {
+        throw new RustToolchainDeclarationFailure("是有效 TOML 声明", `无法解析：${error instanceof Error ? error.message : String(error)}`, `请先修正根 ${rootRustDeclarationFileName} 的 TOML 语法，使 [toolchain] 表内声明 channel 再加包。`);
+    }
+    const toolchain = isRecord(declaration) ? declaration.toolchain : undefined;
+    const channel = isRecord(toolchain) ? toolchain.channel : undefined;
+    if (typeof channel !== "string" || channel.trim().length === 0) {
+        throw new RustToolchainDeclarationFailure("为非空字符串", JSON.stringify(channel ?? null), `请先在根 ${rootRustDeclarationFileName} 的 [toolchain] 表内写入 channel 再加包。`);
+    }
+    return { channel, declaration: declarationText };
+}
+/** 已有 Rust 仓库的加包版本由根 rust-toolchain.toml 当前 channel 拥有。 */
+export function readRootRustToolchainChannel(repositoryRoot) {
+    return readRootRustToolchainDeclaration(repositoryRoot).channel;
+}
+/** 从模板投影的 Rust 声明结构化读取根 channel，供工具链镜像校验共用。 */
+export function readRustToolchainChannelFromToml(contents) {
+    let declaration;
+    try {
+        declaration = parseToml(contents);
+    }
+    catch (error) {
+        return {
+            reason: `不是有效 TOML 声明：${error instanceof Error ? error.message : String(error)}`,
+            status: "unreadable",
+        };
+    }
+    const toolchain = isRecord(declaration) ? declaration.toolchain : undefined;
+    const channel = isRecord(toolchain) ? toolchain.channel : undefined;
+    if (typeof channel !== "string" || channel.trim().length === 0) {
+        return {
+            reason: `[toolchain].channel 必须是非空字符串，实际为 ${JSON.stringify(channel ?? null)}`,
+            status: "unreadable",
+        };
+    }
+    return { channel, status: "explained" };
+}

package/node_modules/@ykdz/template-workspace/dist/shared-root-files.d.ts

@@ -0,0 +1,99 @@
+import type { ProjectProjectionReconciliation } from "@ykdz/template-core/project-projection";
+import type { RenderOperation, WriteTextFromFragmentsOperation } from "@ykdz/template-core/renderer";
+import type { CiDiagnosticArtifactDeclaration } from "./ci-diagnostic-artifact.ts";
+import type { CheckEnvironmentNeed, DeploymentEnvironmentNeed } from "./environment-needs.ts";
+import type { DependencyMaintenancePolicy } from "./project-requirements.ts";
+export type RootResourceOperation = Extract<RenderOperation, {
+    readonly kind: "copyFile" | "writeText" | "writeJson" | "writeTextFromFragments";
+}>;
+/** 外层拥有者声明共享文件中的领域条目；不向参考包授予根写入权限。 */
+export type SharedRootContribution = {
+    readonly kind: "shared-root-files";
+    readonly source: string;
+    readonly manifest?: {
+        readonly scripts?: Readonly<Record<string, string>>;
+        readonly imports?: Readonly<Record<string, string>>;
+        readonly devDependencies?: Readonly<Record<string, string>>;
+    };
+    /** 同名任务作为完整声明比较，不递归合并任务内部的规则。 */
+    readonly turboTasks?: Readonly<Record<string, unknown>>;
+    readonly typescript?: {
+        readonly compilerOptions?: Readonly<Record<string, unknown>>;
+        readonly include?: readonly string[];
+    };
+    /** 按声明顺序连接，保留忽略规则及其反向规则的语义。 */
+    readonly gitignoreFragments?: WriteTextFromFragmentsOperation["fragments"];
+    /** 每个步骤必须有独占的 id；before 引用已存在的步骤。 */
+    readonly ciSteps?: readonly {
+        readonly before?: string;
+        readonly steps: readonly (Readonly<Record<string, unknown>> & {
+            readonly id: string;
+        })[];
+    }[];
+    /** 声明根检查作业的名称和超时；同一字段只允许等价来源。 */
+    readonly ciJob?: {
+        readonly name?: string;
+        readonly timeoutMinutes?: number;
+    };
+    /** 外层拥有者声明共享环境及依赖维护需求。 */
+    readonly environmentNeeds?: {
+        readonly check?: readonly CheckEnvironmentNeed[];
+        readonly deployment?: readonly DeploymentEnvironmentNeed[];
+    };
+    readonly dependencyMaintenance?: DependencyMaintenancePolicy;
+    /** 由所属内容声明的 CI 失败诊断制品。 */
+    readonly ciDiagnosticArtifacts?: readonly CiDiagnosticArtifactDeclaration[];
+    /** 外层拥有者的完整独占资源；禁止对共享文件或真实包范围打补丁。 */
+    readonly resources?: readonly {
+        readonly operation: RootResourceOperation;
+        readonly reconciliation?: ProjectProjectionReconciliation;
+        readonly executable?: boolean;
+    }[];
+};
+export declare function composeSharedRootFiles(options: {
+    readonly source: string;
+    readonly manifest: Readonly<Record<string, unknown>>;
+    readonly turboTasks: Readonly<Record<string, unknown>>;
+    readonly typescript: {
+        readonly compilerOptions: Readonly<Record<string, unknown>>;
+        readonly include: readonly string[];
+    };
+    readonly declarations: readonly SharedRootContribution[];
+    readonly packagePaths: readonly string[];
+}): {
+    manifest: {
+        [x: string]: unknown;
+    };
+    turboTasks: Record<string, unknown>;
+    typescript: {
+        compilerOptions: Record<string, unknown>;
+        include: string[];
+    };
+    gitignoreFragments: {
+        from: string;
+        source: import("@ykdz/template-core/renderer").TemplateSourceHandle;
+    }[];
+    ciSteps: {
+        before?: string;
+        steps: readonly (Readonly<Record<string, unknown>> & {
+            readonly id: string;
+        })[];
+        source: string;
+    }[];
+    ciJob: {
+        readonly name?: string;
+        readonly timeoutMinutes?: number;
+    };
+    environmentNeeds: {
+        check: CheckEnvironmentNeed[];
+        deployment: import("./environment-needs.ts").DockerEngineEnvironmentNeed[];
+    };
+    dependencyMaintenance: DependencyMaintenancePolicy[];
+    operations: RenderOperation[];
+    resourceOwners: Map<string, string>;
+    reconciliation: ProjectProjectionReconciliation[];
+};
+/** CI 步骤按锚点和来源顺序插入；步骤身份独占，不按内容去重或排序。 */
+export declare function composeCheckWorkflow(template: string, source: string, insertions: ReturnType<typeof composeSharedRootFiles>["ciSteps"]): string;
+/** 从实际基础输出检查独占资源，避免平行维护一份根文件清单。 */
+export declare function assertExclusiveRootResources(baseOperations: readonly RenderOperation[], source: string, owners: ReadonlyMap<string, string>): void;

package/node_modules/@ykdz/template-workspace/dist/shared-root-files.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { parseDocument } from "yaml";
+function pointer(value) {
+    return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function conflict(location, left, right) {
+    throw new Error(`共享根文件声明冲突：${location}；来源 ${left} 与 ${right}`);
+}
+/** 每个字典拥有自己的等价规则；只比较完整条目，不提供覆盖优先级。 */
+function composeEntries(location, declarations) {
+    const values = {};
+    const owners = new Map();
+    for (const declaration of declarations) {
+        for (const [key, value] of Object.entries(declaration.values)) {
+            const owner = owners.get(key);
+            if (owner !== undefined && !isDeepStrictEqual(values[key], value)) {
+                conflict(`${location}/${pointer(key)}`, owner, declaration.source);
+            }
+            if (owner === undefined) {
+                owners.set(key, declaration.source);
+                values[key] = value;
+            }
+        }
+    }
+    return values;
+}
+export function composeSharedRootFiles(options) {
+    const declarations = options.declarations;
+    const manifest = { ...options.manifest };
+    for (const field of ["scripts", "imports", "devDependencies"]) {
+        const values = composeEntries(`package.json#/${field}`, [
+            {
+                source: options.source,
+                values: (manifest[field] ?? {}),
+            },
+            ...declarations.map((declaration) => ({
+                source: declaration.source,
+                values: declaration.manifest?.[field] ?? {},
+            })),
+        ]);
+        if (Object.keys(values).length > 0)
+            manifest[field] = values;
+    }
+    const turboTasks = composeEntries("turbo.json#/tasks", [
+        { source: options.source, values: options.turboTasks },
+        ...declarations.map((declaration) => ({
+            source: declaration.source,
+            values: declaration.turboTasks ?? {},
+        })),
+    ]);
+    const compilerOptions = composeEntries("tsconfig.json#/compilerOptions", [
+        { source: options.source, values: options.typescript.compilerOptions },
+        ...declarations.map((declaration) => ({
+            source: declaration.source,
+            values: declaration.typescript?.compilerOptions ?? {},
+        })),
+    ]);
+    const include = [
+        ...new Set([
+            ...options.typescript.include,
+            ...declarations.flatMap((declaration) => declaration.typescript?.include ?? []),
+        ]),
+    ];
+    const ciJob = composeEntries(".github/workflows/check.yml#/jobs/check", declarations.map((declaration) => ({
+        source: declaration.source,
+        values: declaration.ciJob ?? {},
+    })));
+    const owners = new Map();
+    for (const declaration of declarations) {
+        for (const resource of declaration.resources ?? []) {
+            const file = resource.operation.to;
+            if (path.posix.normalize(file) !== file ||
+                file.startsWith("../") ||
+                path.posix.isAbsolute(file) ||
+                file.includes("\\") ||
+                options.packagePaths.some((packagePath) => file === packagePath || file.startsWith(`${packagePath}/`))) {
+                throw new Error(`${declaration.source} 的根资源不得写入真实包或无效路径：${file}`);
+            }
+            const owner = owners.get(file);
+            if (owner !== undefined)
+                conflict(file, owner, declaration.source);
+            owners.set(file, declaration.source);
+            if (resource.reconciliation !== undefined &&
+                resource.reconciliation.path !== file) {
+                throw new Error(`${declaration.source} 的资源协调路径必须匹配：${file}`);
+            }
+        }
+    }
+    return {
+        manifest,
+        turboTasks,
+        typescript: { compilerOptions, include },
+        gitignoreFragments: declarations.flatMap((declaration) => declaration.gitignoreFragments ?? []),
+        ciSteps: declarations.flatMap((declaration) => (declaration.ciSteps ?? []).map((insertion) => ({
+            ...insertion,
+            source: declaration.source,
+        }))),
+        ciJob,
+        environmentNeeds: {
+            check: declarations.flatMap((declaration) => declaration.environmentNeeds?.check ?? []),
+            deployment: declarations.flatMap((declaration) => declaration.environmentNeeds?.deployment ?? []),
+        },
+        dependencyMaintenance: declarations.flatMap((declaration) => declaration.dependencyMaintenance === undefined
+            ? []
+            : [declaration.dependencyMaintenance]),
+        operations: declarations.flatMap((declaration) => (declaration.resources ?? []).flatMap((resource) => [
+            resource.operation,
+            ...(resource.executable === undefined
+                ? []
+                : [
+                    {
+                        kind: "setExecutable",
+                        path: resource.operation.to,
+                        executable: resource.executable,
+                    },
+                ]),
+        ])),
+        resourceOwners: owners,
+        reconciliation: declarations.flatMap((declaration) => (declaration.resources ?? []).flatMap((resource) => resource.reconciliation === undefined ? [] : [resource.reconciliation])),
+    };
+}
+/** CI 步骤按锚点和来源顺序插入；步骤身份独占，不按内容去重或排序。 */
+export function composeCheckWorkflow(template, source, insertions) {
+    if (insertions.length === 0)
+        return template;
+    const workflow = parseDocument(template);
+    const steps = workflow.getIn(["jobs", "check", "steps"]);
+    const owners = new Map();
+    for (const step of steps.items) {
+        const id = step.get("id");
+        if (typeof id === "string")
+            owners.set(id, source);
+    }
+    for (const insertion of insertions) {
+        const index = insertion.before === undefined
+            ? steps.items.length
+            : steps.items.findIndex((step) => step.get("id") === insertion.before);
+        if (index === -1)
+            throw new Error(`${insertion.source} 的 CI 步骤锚点不存在：${insertion.before}`);
+        for (const step of insertion.steps) {
+            const owner = owners.get(step.id);
+            if (owner !== undefined)
+                conflict(`.github/workflows/check.yml#/jobs/check/steps/${pointer(step.id)}`, owner, insertion.source);
+            owners.set(step.id, insertion.source);
+        }
+        steps.items.splice(index, 0, ...insertion.steps.map((step) => workflow.createNode(step)));
+    }
+    return workflow.toString();
+}
+/** 从实际基础输出检查独占资源，避免平行维护一份根文件清单。 */
+export function assertExclusiveRootResources(baseOperations, source, owners) {
+    for (const operation of baseOperations) {
+        const file = "to" in operation ? operation.to : operation.path;
+        const owner = owners.get(file);
+        if (owner !== undefined)
+            conflict(file, source, owner);
+    }
+}

package/node_modules/@ykdz/template-workspace/dist/vue-policy.d.ts

@@ -0,0 +1,5 @@
+/** Vue 工具链的 peer 依赖覆盖属于工作区策略。 */
+export declare const vuePnpmDependencyOverrides: {
+    readonly "pinia>typescript": "-";
+    readonly "vue>typescript": "-";
+};

package/node_modules/@ykdz/template-workspace/dist/vue-policy.js

@@ -0,0 +1,5 @@
+/** Vue 工具链的 peer 依赖覆盖属于工作区策略。 */
+export const vuePnpmDependencyOverrides = {
+    "pinia>typescript": "-",
+    "vue>typescript": "-",
+};

package/node_modules/@ykdz/template-workspace/dist/workspace-policy-snapshot.d.ts

@@ -0,0 +1,20 @@
+export declare const dependencyCatalogSnapshot: Readonly<Record<string, string>>;
+export declare const workspaceInstallPolicySnapshot: {
+    nodeLinker: string;
+    preferSymlinkedExecutables: boolean;
+    shellEmulator: boolean;
+    autoInstallPeers: boolean;
+    injectWorkspacePackages: boolean;
+    dedupeInjectedDeps: boolean;
+    syncInjectedDepsAfterScripts: string[];
+    minimumReleaseAge: number;
+    minimumReleaseAgeStrict: boolean;
+    minimumReleaseAgeExclude: string[];
+    allowBuilds: {
+        esbuild: boolean;
+    };
+    overrides: {
+        "pinia>typescript": string;
+        "vue>typescript": string;
+    };
+};