@ykdz/template 0.0.42 → 0.1.0-experimental.0

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

@@ -0,0 +1,167 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertExactKeys(value, allowedKeys, context) {
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.includes(key)) {
+            throw new Error(`${context} 含有未知字段：${key}`);
+        }
+    }
+}
+function parseComponentOwner(value, context) {
+    if (!isRecord(value)) {
+        throw new Error(`${context} 必须是组件所有者`);
+    }
+    assertExactKeys(value, ["kind", "path"], context);
+    if (value.kind === "workspace-orchestration" && value.path === ".") {
+        return { kind: value.kind, path: value.path };
+    }
+    if (value.kind === "package-boundary" &&
+        typeof value.path === "string" &&
+        value.path.length > 0) {
+        return { kind: value.kind, path: value.path };
+    }
+    throw new Error(`${context} 不是受支持的组件所有者`);
+}
+function parseCheckEnvironmentNeed(value, context) {
+    if (!isRecord(value)) {
+        throw new Error(`${context} 必须是检查环境需求`);
+    }
+    switch (value.kind) {
+        case "playwright-browser-assets": {
+            assertExactKeys(value, ["kind", "browser", "owner"], context);
+            if (value.browser !== "chromium") {
+                throw new Error(`${context}.browser 必须是 chromium`);
+            }
+            return {
+                kind: value.kind,
+                browser: value.browser,
+                owner: parseComponentOwner(value.owner, `${context}.owner`),
+            };
+        }
+        case "shellcheck-command":
+            assertExactKeys(value, ["kind", "owner"], context);
+            return {
+                kind: value.kind,
+                owner: parseComponentOwner(value.owner, `${context}.owner`),
+            };
+        case "rust-toolchain": {
+            assertExactKeys(value, ["kind", "owner", "toolchain"], context);
+            if (value.toolchain !== "stable") {
+                throw new Error(`${context}.toolchain 必须是 stable`);
+            }
+            return {
+                kind: value.kind,
+                owner: parseComponentOwner(value.owner, `${context}.owner`),
+                toolchain: value.toolchain,
+            };
+        }
+        default:
+            throw new Error(`${context} 含有不支持的 kind：${String(value.kind)}`);
+    }
+}
+function parseDeploymentEnvironmentNeed(value, context) {
+    if (!isRecord(value)) {
+        throw new Error(`${context} 必须是部署环境需求`);
+    }
+    assertExactKeys(value, ["kind"], context);
+    if (value.kind !== "docker-engine") {
+        throw new Error(`${context} 含有不支持的 kind：${String(value.kind)}`);
+    }
+    return { kind: value.kind };
+}
+function componentOwnerIdentity(owner) {
+    return `${owner.kind}:${owner.path}`;
+}
+function checkEnvironmentNeedConflictKey(need) {
+    return `${need.kind}:${componentOwnerIdentity(need.owner)}`;
+}
+function checkEnvironmentNeedIdentity(need) {
+    switch (need.kind) {
+        case "playwright-browser-assets":
+            return `${checkEnvironmentNeedConflictKey(need)}:browser=${need.browser}`;
+        case "shellcheck-command":
+            return checkEnvironmentNeedConflictKey(need);
+        case "rust-toolchain":
+            return `${checkEnvironmentNeedConflictKey(need)}:toolchain=${need.toolchain}`;
+    }
+}
+function normalizeCheckEnvironmentNeeds(needs) {
+    const byIdentity = new Map();
+    const identityByConflictKey = new Map();
+    for (const [index, input] of needs.entries()) {
+        const need = parseCheckEnvironmentNeed(input, `check[${index}]`);
+        const identity = checkEnvironmentNeedIdentity(need);
+        const conflictKey = checkEnvironmentNeedConflictKey(need);
+        const previousIdentity = identityByConflictKey.get(conflictKey);
+        if (previousIdentity !== undefined && previousIdentity !== identity) {
+            throw new Error(`检查环境需求 ${conflictKey} 的语义参数冲突`);
+        }
+        identityByConflictKey.set(conflictKey, identity);
+        byIdentity.set(identity, need);
+    }
+    return [...byIdentity]
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([, need]) => need);
+}
+function normalizeDeploymentEnvironmentNeeds(needs) {
+    const byIdentity = new Map();
+    for (const [index, input] of needs.entries()) {
+        const need = parseDeploymentEnvironmentNeed(input, `deployment[${index}]`);
+        byIdentity.set(need.kind, need);
+    }
+    return [...byIdentity]
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([, need]) => need);
+}
+/** 校验、去重并按固定顺序排列持久化环境需求。 */
+export function normalizeEnvironmentNeeds(options) {
+    return {
+        schemaVersion: 1,
+        check: normalizeCheckEnvironmentNeeds(options.check),
+        deployment: normalizeDeploymentEnvironmentNeeds(options.deployment),
+    };
+}
+/** 严格解析加包流程消费的本地模板元数据。 */
+export function parseEnvironmentNeedsMetadata(value) {
+    if (!isRecord(value)) {
+        throw new Error("环境需求元数据必须是对象");
+    }
+    assertExactKeys(value, ["schemaVersion", "check", "deployment"], "$");
+    if (value.schemaVersion !== 1) {
+        throw new Error(`不支持环境需求元数据 schemaVersion ${String(value.schemaVersion)}；预期为 1`);
+    }
+    if (!Array.isArray(value.check)) {
+        throw new Error("$.check 必须是数组");
+    }
+    if (!Array.isArray(value.deployment)) {
+        throw new Error("$.deployment 必须是数组");
+    }
+    return normalizeEnvironmentNeeds({
+        check: value.check,
+        deployment: value.deployment,
+    });
+}
+export function rustToolchainEnvironmentNeed(owner) {
+    return {
+        kind: "rust-toolchain",
+        owner,
+        toolchain: "stable",
+    };
+}
+export function dockerEngineEnvironmentNeed() {
+    return { kind: "docker-engine" };
+}
+export function playwrightBrowserAssetsEnvironmentNeed(options) {
+    return {
+        kind: "playwright-browser-assets",
+        browser: options.browser,
+        owner: options.owner,
+    };
+}
+export function shellCheckEnvironmentNeed(owner) {
+    return {
+        kind: "shellcheck-command",
+        owner,
+    };
+}

package/node_modules/@ykdz/template-workspace/dist/generation-context.d.ts

@@ -0,0 +1,14 @@
+/** 工具链事实解析后提供的稳定工作区输入。 */
+export type GenerationContext = {
+    readonly targetDir: string;
+    readonly repositoryName: string;
+    readonly defaultPackageScope: string;
+    readonly toolchain: {
+        readonly nodeLtsMajor: string;
+        readonly packageManagerPin: string;
+        /** 精确三段 Node 版本；不可由大版本伪造，也不是回退值。 */
+        readonly nodeVersion?: string;
+        /** 已知 Rust channel；不是版本回退值，也不进入持久生成记录。 */
+        readonly rustVersion?: string;
+    };
+};

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

@@ -0,0 +1,21 @@
+export declare class WorkspacePackageAdditionFailure extends Error {
+    readonly suggestion: string;
+    constructor(message: string, suggestion: string);
+}
+export type PackageAdditionVersionFacts = {
+    readonly toolchain: {
+        readonly nodeLtsMajor: string;
+        readonly nodeVersion?: string;
+        readonly packageManagerPin: string;
+    };
+    readonly rootNodeDeclaration: string;
+};
+/** 加包按目标根当前的合法 Node 与 pnpm 声明解释版本，不回退初始化快照。 */
+export declare function readPackageAdditionVersionFacts(repositoryRoot: string): PackageAdditionVersionFacts;
+/** 核对已有依赖包仍提供原生声明的公开接口，并允许其指向本地定制文件。 */
+export declare function assertReusablePackageExposure(options: {
+    readonly repositoryRoot: string;
+    readonly packagePath: string;
+    readonly expectedExports: Readonly<Record<string, unknown>>;
+    readonly actualManifest?: Readonly<Record<string, unknown>>;
+}): void;

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

@@ -0,0 +1,90 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+const nodeMajorOrExactVersionPattern = /^([0-9]+)(?:\.([0-9]+)\.([0-9]+))?$/u;
+const exactPnpmPinPattern = /^pnpm@[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/u;
+export class WorkspacePackageAdditionFailure extends Error {
+    suggestion;
+    constructor(message, suggestion) {
+        super(message);
+        this.suggestion = suggestion;
+    }
+}
+const sharedPackageContractSuggestion = "请先显式修正或迁移生成记录及共同包接口；新增操作不会推测身份或覆盖已有定制。";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 加包按目标根当前的合法 Node 与 pnpm 声明解释版本，不回退初始化快照。 */
+export function readPackageAdditionVersionFacts(repositoryRoot) {
+    const manifestPath = path.join(repositoryRoot, "package.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Package Addition requires root Manifest in package.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("Package Addition requires root Manifest in package.json to be an object");
+    }
+    const nodeDeclaration = isRecord(parsed.engines)
+        ? parsed.engines.node
+        : undefined;
+    const nodeDeclarationMatch = typeof nodeDeclaration === "string"
+        ? nodeMajorOrExactVersionPattern.exec(nodeDeclaration)
+        : undefined;
+    const nodeLtsMajor = nodeDeclarationMatch?.[1];
+    if (nodeLtsMajor === undefined || typeof nodeDeclaration !== "string") {
+        throw new WorkspacePackageAdditionFailure(`加包需要目标仓库根 package.json 的 engines.node 声明单个 Node 大版本（"24"）或精确 Node 版本（"24.16.0"），实际收到 ${JSON.stringify(nodeDeclaration ?? null)}。请先修改根 package.json 的 engines.node 声明再加包。`, "请先修改根 package.json 的 engines.node 声明再加包。");
+    }
+    const packageManagerDeclaration = parsed.packageManager;
+    if (typeof packageManagerDeclaration !== "string" ||
+        !exactPnpmPinPattern.test(packageManagerDeclaration)) {
+        throw new WorkspacePackageAdditionFailure(`加包需要目标仓库根 package.json 的 packageManager 声明精确 pnpm 版本（"pnpm@11.21.0"），实际收到 ${JSON.stringify(packageManagerDeclaration ?? null)}。请先修改根 package.json 的 packageManager 声明再加包。`, "请先修改根 package.json 的 packageManager 声明再加包。");
+    }
+    return {
+        toolchain: {
+            nodeLtsMajor,
+            packageManagerPin: packageManagerDeclaration,
+            ...(nodeDeclarationMatch?.[2] === undefined
+                ? {}
+                : { nodeVersion: nodeDeclaration }),
+        },
+        rootNodeDeclaration: nodeDeclaration,
+    };
+}
+/** 核对已有依赖包仍提供原生声明的公开接口，并允许其指向本地定制文件。 */
+export function assertReusablePackageExposure(options) {
+    let actualManifest = options.actualManifest;
+    if (actualManifest === undefined) {
+        try {
+            const parsed = JSON.parse(readFileSync(path.join(options.repositoryRoot, options.packagePath, "package.json"), "utf8"));
+            if (!isRecord(parsed))
+                throw new Error("manifest 必须是对象");
+            actualManifest = parsed;
+        }
+        catch {
+            throw new WorkspacePackageAdditionFailure(`共同包 ${options.packagePath} 缺少有效 manifest，不能复用。`, sharedPackageContractSuggestion);
+        }
+    }
+    for (const exportName of Object.keys(options.expectedExports)) {
+        const target = isRecord(actualManifest.exports)
+            ? actualManifest.exports[exportName]
+            : undefined;
+        // 条件与回退数组由 Node 解释；这里只拦截明确不可用的接口声明。
+        if (typeof target !== "string" &&
+            !isRecord(target) &&
+            !Array.isArray(target)) {
+            throw new WorkspacePackageAdditionFailure(`共同包 ${options.packagePath} 缺少可用的公开接口 ${exportName}。`, sharedPackageContractSuggestion);
+        }
+        if (typeof target === "string") {
+            try {
+                if (!target.startsWith("./"))
+                    throw new Error("公开资源必须属于该包");
+                readFileSync(path.join(options.repositoryRoot, options.packagePath, target));
+            }
+            catch {
+                throw new WorkspacePackageAdditionFailure(`共同包 ${options.packagePath} 的公开接口 ${exportName} 不可读取。`, sharedPackageContractSuggestion);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,64 @@
+import { type PackageContribution as PackageContributionSkeleton } from "@ykdz/template-core/package-contribution";
+import type { PackageDefinition } from "@ykdz/template-core/project-blueprint";
+import type { RenderOperation, TemplateSourceHandle } from "@ykdz/template-core/renderer";
+import type { DevelopmentContainerToolLayer } from "@ykdz/template-environment/development-container-tool-layer";
+import { type CiDiagnosticArtifactDeclaration } from "./ci-diagnostic-artifact.ts";
+import type { EditorCustomizationCapability } from "./editor-customization.ts";
+import type { CheckEnvironmentNeed } from "./environment-needs.ts";
+import type { DependencyMaintenancePolicy, ProjectRequirement } from "./project-requirements.ts";
+export type FoundationContribution = {
+    /** 由实际选中的配置包拥有的根 TypeScript 配置身份。 */
+    readonly workspaceConfiguration?: {
+        readonly kind: "typescript-workspace-configuration";
+    };
+    /** Foundation 必须安装并投影到协同根文件中的工具链。 */
+    readonly toolchains: {
+        readonly rust?: {
+            readonly toolchain: string;
+            readonly components: readonly ("rustfmt" | "clippy")[];
+            readonly configurationText?: string;
+        };
+    };
+    /** Foundation 必须投影到协同编辑器文件中的编辑器能力。 */
+    readonly editorCapabilities: readonly EditorCustomizationCapability[];
+    /** 由协同根策略维护的生态系统与路径。 */
+    readonly dependencyMaintenance: DependencyMaintenancePolicy;
+    /** 包边界提供的工作区成员匹配模式。 */
+    readonly workspacePackageGlobs?: readonly string[];
+    /** 包自有清单所需的依赖目录条目。 */
+    readonly dependencyCatalog?: Readonly<Record<string, string>>;
+    /** 由 Foundation 协同并由源码提供的开发容器能力。 */
+    readonly developmentContainerToolLayers?: readonly DevelopmentContainerToolLayer[] | undefined;
+};
+export type FoundationTemplateAssetSource = {
+    readonly source: TemplateSourceHandle;
+    readonly from: string;
+};
+/** 生成仓库计划中与预设无关的包级片段。 */
+export type PackageContribution = PackageContributionSkeleton & {
+    /** 原生来源身份及已选择的目标实例；原生依赖仍由来源 manifest 拥有。 */
+    readonly referenceSource?: string;
+    readonly referenceBindings?: Readonly<Record<string, PackageDefinition>>;
+    readonly definition: PackageDefinition;
+    readonly manifest: Readonly<Record<string, unknown>>;
+    readonly exposure: {
+        readonly exports: Readonly<Record<string, unknown>>;
+        readonly imports: Readonly<Record<string, unknown>>;
+    };
+    readonly operations: readonly RenderOperation[];
+    /** 由 Foundation 消费并投影为协同根输出的类型化需求。 */
+    readonly foundation: FoundationContribution;
+    readonly environmentNeeds: readonly CheckEnvironmentNeed[];
+    /** 只声明由策略解释的闭合项目协作，不授予内容根级写入权限。 */
+    readonly projectRequirements?: readonly ProjectRequirement[];
+    /** 由此包边界持有的封闭式原生 CI 证据。 */
+    readonly ciDiagnosticArtifacts?: readonly CiDiagnosticArtifactDeclaration[];
+};
+/** 校验 CLI 命令名的格式及工作区内是否重名。 */
+export declare function validateCliCommandName(commandName: string, occupiedCommandNames?: readonly string[]): string;
+/** 校验完整生成计划中的命令名格式和唯一性。 */
+export declare function assertPackageContributionCommandNames(contributions: readonly PackageContribution[]): readonly PackageContribution[];
+export declare function assertPackageContribution(contribution: PackageContribution, provenance?: {
+    readonly definitionName?: string;
+    readonly planner?: string;
+}): PackageContribution;

package/node_modules/@ykdz/template-workspace/dist/package-contribution.js

@@ -0,0 +1,65 @@
+import { assertPackageContribution as assertPackageContributionPaths, } from "@ykdz/template-core/package-contribution";
+import { assertCiDiagnosticArtifactDeclaration, } from "./ci-diagnostic-artifact.js";
+/** 校验 CLI 命令名的格式及工作区内是否重名。 */
+export function validateCliCommandName(commandName, occupiedCommandNames = []) {
+    if (/[/\\]/u.test(commandName)) {
+        throw new Error(`CLI command name must not be a path; received ${JSON.stringify(commandName)}`);
+    }
+    if (/\p{White_Space}/u.test(commandName)) {
+        throw new Error(`CLI command name must not contain whitespace; received ${JSON.stringify(commandName)}`);
+    }
+    if (/\p{Control}/u.test(commandName)) {
+        throw new Error(`CLI command name must not contain a control character; received ${JSON.stringify(commandName)}`);
+    }
+    if (commandName.startsWith("-")) {
+        throw new Error(`CLI command name must not have a leading hyphen; received ${JSON.stringify(commandName)}`);
+    }
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(commandName)) {
+        throw new Error(`CLI command name must use lowercase ASCII letters, digits, and single hyphens; received ${JSON.stringify(commandName)}`);
+    }
+    if (occupiedCommandNames.includes(commandName)) {
+        throw new Error(`CLI command name is already used by another workspace package; received ${JSON.stringify(commandName)}`);
+    }
+    return commandName;
+}
+function manifestBinEntries(contribution) {
+    const bin = contribution.manifest.bin;
+    if (typeof bin !== "object" || bin === null || Array.isArray(bin)) {
+        return [];
+    }
+    return Object.entries(bin);
+}
+/** 校验完整生成计划中的命令名格式和唯一性。 */
+export function assertPackageContributionCommandNames(contributions) {
+    const commandOwner = new Map();
+    for (const contribution of contributions) {
+        const entries = manifestBinEntries(contribution);
+        for (const [commandName] of entries) {
+            const existingOwner = commandOwner.get(commandName);
+            try {
+                validateCliCommandName(commandName, [...commandOwner.keys()]);
+            }
+            catch (error) {
+                if (existingOwner !== undefined) {
+                    throw new Error(`CLI command name ${JSON.stringify(commandName)} from ${contribution.definition.name} is already used by ${existingOwner}`, { cause: error });
+                }
+                throw error;
+            }
+            commandOwner.set(commandName, contribution.definition.name);
+        }
+    }
+    return contributions;
+}
+export function assertPackageContribution(contribution, provenance = {}) {
+    if (contribution.definition.name !== contribution.manifest.name) {
+        throw new Error("Package Contribution manifest name must match its Package Definition");
+    }
+    for (const artifact of contribution.ciDiagnosticArtifacts ?? []) {
+        const declaration = assertCiDiagnosticArtifactDeclaration(artifact);
+        if (declaration.owner.path !== contribution.definition.path) {
+            throw new Error(`CI 诊断制品所有者必须与包贡献路径一致：${contribution.definition.path}`);
+        }
+    }
+    assertPackageContributionPaths(contribution, provenance);
+    return contribution;
+}

package/node_modules/@ykdz/template-workspace/dist/project-github.d.ts

@@ -0,0 +1,24 @@
+import type { DependencyMaintenancePolicy } from "./project-requirements.ts";
+export type ProjectCheckWorkflowDiagnosticOptions = {
+    readonly packagePaths: readonly string[];
+    readonly diagnosticArtifacts?: readonly unknown[] | undefined;
+    readonly job?: {
+        readonly name?: string;
+        readonly timeoutMinutes?: number;
+    };
+};
+export type PreparedProjectGithubTemplates = {
+    readonly checkWorkflow: string;
+    readonly dependabot: string;
+    readonly nextSteps: string;
+};
+/** GitHub 与下一步文档的原生模板由工作区 owner 在准备阶段读取。 */
+export declare function prepareProjectGithubTemplates(): PreparedProjectGithubTemplates;
+/** 完整原生工作流拥有任务和工具设置；投影只选择已声明的能力。 */
+export declare function projectCheckWorkflow(options: ProjectCheckWorkflowDiagnosticOptions, template: string): string;
+/** 版本维护政策保留在原生 YAML，描述只提供生态、目录与频率。 */
+export declare function projectDependabotConfig(policy: DependencyMaintenancePolicy, template: string): string;
+/** 文档正文是自然 Markdown，动态命令由已有正式计划提供。 */
+export declare function projectNextStepsDocument(instructions: readonly {
+    readonly display: string;
+}[], template: string): string;

package/node_modules/@ykdz/template-workspace/dist/project-github.js

@@ -0,0 +1,98 @@
+import { readFileSync } from "node:fs";
+import { parseDocument } from "yaml";
+import { composeCiDiagnosticArtifacts } from "./ci-diagnostic-artifact.js";
+/** GitHub 与下一步文档的原生模板由工作区 owner 在准备阶段读取。 */
+export function prepareProjectGithubTemplates() {
+    const read = (file) => {
+        try {
+            return readFileSync(new URL(`../assets/${file}`, import.meta.url), "utf8");
+        }
+        catch (cause) {
+            throw new Error(`工作区资源 @ykdz/template-workspace#./project-github prepare 阶段无法读取 ${file}`, { cause });
+        }
+    };
+    return {
+        checkWorkflow: read("github/check.yml"),
+        dependabot: read("github/dependabot.yml"),
+        nextSteps: read("next-steps.md"),
+    };
+}
+/** 完整原生工作流拥有任务和工具设置；投影只选择已声明的能力。 */
+export function projectCheckWorkflow(options, template) {
+    const diagnostics = composeCiDiagnosticArtifacts({
+        packagePaths: options.packagePaths,
+        declarations: options.diagnosticArtifacts ?? [],
+    });
+    const workflow = parseDocument(template);
+    workflow.setIn(["jobs", "check", "name"], "Root Check");
+    workflow.setIn(["jobs", "check", "timeout-minutes"], 30);
+    const steps = workflow.getIn(["jobs", "check", "steps"]);
+    steps.items = steps.items.filter((step) => {
+        const identity = step.get("id");
+        if (identity === "stage-diagnostics" || identity === "upload-diagnostics")
+            return diagnostics.length > 0;
+        return true;
+    });
+    if (options.job === undefined) {
+        for (const step of steps.items) {
+            if (step.get("id") === "stage-diagnostics")
+                step.set("name", "Stage Root Check diagnostics");
+            if (step.get("id") === "upload-diagnostics") {
+                step.set("name", "Upload Root Check diagnostics");
+                step.setIn(["with", "name"], "root-check-diagnostics");
+            }
+        }
+    }
+    else {
+        if (options.job.name !== undefined) {
+            workflow.setIn(["jobs", "check", "name"], options.job.name);
+        }
+        if (options.job.timeoutMinutes !== undefined) {
+            workflow.setIn(["jobs", "check", "timeout-minutes"], options.job.timeoutMinutes);
+        }
+    }
+    const staging = steps.items.find((step) => step.get("id") === "stage-diagnostics");
+    if (staging !== undefined) {
+        const owners = (kind) => diagnostics
+            .filter((declaration) => declaration.kind === kind)
+            .map((declaration) => declaration.owner.path)
+            .toSorted()
+            .join("\n");
+        staging.setIn(["env", "PLAYWRIGHT_DIAGNOSTIC_OWNER_PATHS"], owners("playwright"));
+        staging.setIn(["env", "VITEST_BROWSER_DIAGNOSTIC_OWNER_PATHS"], owners("vitest-browser"));
+    }
+    return workflow.toString({ lineWidth: 0 });
+}
+/** 版本维护政策保留在原生 YAML，描述只提供生态、目录与频率。 */
+export function projectDependabotConfig(policy, template) {
+    const document = parseDocument(template);
+    const declarations = document.toJS()
+        .updates;
+    const updates = policy.ecosystems.flatMap((ecosystem) => {
+        const candidates = declarations.filter((update) => update["package-ecosystem"] === ecosystem);
+        const defaultUpdate = candidates[0];
+        if (defaultUpdate === undefined)
+            throw new Error(`原生 Dependabot 配置未声明生态：${ecosystem}`);
+        return [
+            policy.directories?.[ecosystem] ?? defaultUpdate.directory,
+            ...(policy.extraDirectories?.[ecosystem] ?? []),
+        ].map((directory) => {
+            const declaration = candidates.find((candidate) => candidate.directory === directory) ??
+                candidates.find((candidate) => candidate.directory === "/") ??
+                defaultUpdate;
+            return {
+                ...declaration,
+                directory,
+                schedule: { ...declaration.schedule, interval: policy.interval },
+            };
+        });
+    });
+    document.set("updates", updates);
+    return document.toString({ lineWidth: 0 });
+}
+/** 文档正文是自然 Markdown，动态命令由已有正式计划提供。 */
+export function projectNextStepsDocument(instructions, template) {
+    const introduction = template.trimEnd();
+    const steps = instructions.map((instruction, index) => `${index + 1}. \`${instruction.display}\``);
+    return `${introduction}\n\n${steps.join("\n")}\n`;
+}

package/node_modules/@ykdz/template-workspace/dist/project-linking.d.ts

@@ -0,0 +1,48 @@
+import { type ProjectBlueprint } from "@ykdz/template-core/project-blueprint";
+import type { PackageContribution } from "./package-contribution.ts";
+type PackageManifest = Readonly<Record<string, unknown>>;
+export type ExplicitProjectLinkPlan = {
+    readonly manifestPatchesByPackagePath: ReadonlyMap<string, {
+        readonly dependencies: Readonly<Record<string, "workspace:*">>;
+        readonly dependenciesMeta?: Readonly<Record<string, {
+            readonly injected: true;
+        }>>;
+    }>;
+    /**
+     * Build ordering follows the same explicit package relationships as manifest
+     * dependencies. Turbo resolves ^build through the derived workspace
+     * dependency rather than through Preset or framework vocabulary.
+     */
+    readonly hasBuildOrdering: boolean;
+};
+export declare function canConsumeNodePackageNameImport(contribution: PackageContribution, manifest?: PackageManifest): boolean;
+/** 用已公开的 Package Role 与真实 manifest 判断是否能消费包名导入。 */
+export declare function canConsumeNodePackageNameImportForRole(role: string, manifest: PackageManifest): boolean;
+export declare function canLinkNodePackageRoles(consumerRole: string, providerRole: string): boolean;
+export declare function canProvideSourceConditionPackageNameImport(contribution: PackageContribution, manifest?: PackageManifest): boolean;
+/** 用内容拥有的公开角色与 manifest 判断是否能提供 source 条件导入。 */
+export declare function canProvideSourceConditionPackageNameImportForRole(role: string, manifest: PackageManifest): boolean;
+/** 读取显式连接端点已有的当前 package manifest，供正式连接计划复核。 */
+export declare function readProjectLinkManifestTruth(options: {
+    readonly repositoryRoot: string;
+    readonly packagePaths: readonly string[];
+}): ReadonlyMap<string, PackageManifest>;
+/**
+ * Resolves durable Link Intents from Package Contributions, optionally using
+ * Current Manifest Truth for a follow-up decision. No Preset identity or
+ * string resource protocol is involved.
+ */
+export declare function planExplicitProjectLinks(options: {
+    readonly blueprint: ProjectBlueprint;
+    readonly contributions: readonly PackageContribution[];
+    readonly manifestTruthByPackagePath?: ReadonlyMap<string, PackageManifest>;
+}): ExplicitProjectLinkPlan;
+type RuntimePromotedContribution<Contribution extends PackageContribution> = Omit<Contribution, "manifest"> & {
+    readonly manifest: PackageContribution["manifest"];
+};
+/** 被注入的参考包将其绑定的 TypeScript 配置作为运行时依赖携带。 */
+export declare function promoteInjectedProviderRuntimeDependencies<Contribution extends PackageContribution>(options: {
+    readonly contributions: readonly Contribution[];
+    readonly linkPlan: ExplicitProjectLinkPlan;
+}): readonly RuntimePromotedContribution<Contribution>[];
+export {};