@ykdz/template 0.0.41 → 0.1.0-experimental.0

package/node_modules/@ykdz/template-core/dist/renderer.js

@@ -1,6 +1,7 @@
 import { constants } from "node:fs";
-import { chmod, cp, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, stat, symlink, writeFile, } from "node:fs/promises";
+import { chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, stat, writeFile, } from "node:fs/promises";
 import path from "node:path";
+import { generatedJsonPrintWidth } from "./renderer-policy-snapshot.js";
 /**
  * An opaque, owned Template Source reference.  A renderer operation carries
  * this directly instead of selecting a root from a string-keyed side map.
@@ -51,16 +52,17 @@ function isRecord(value) {
 function isScalarJsonValue(value) {
     return (value === null || ["boolean", "number", "string"].includes(typeof value));
 }
-function serializeJsonValue(value, indentation, pathSegments, multilineArrays, rootKeyOrder, nestedKeyOrder) {
+function serializeJsonValue(value, indentation, pathSegments, multilineArrays, rootKeyOrder, nestedKeyOrder, currentColumn = indentation, trailingComma = false) {
     if (Array.isArray(value)) {
         const compact = `[${value.map((item) => JSON.stringify(item)).join(", ")}]`;
         const shouldCompact = value.every(isScalarJsonValue) &&
             !multilineArrays.has(pathSegments.join(".")) &&
-            indentation + compact.length <= 100;
+            currentColumn + compact.length + (trailingComma ? 1 : 0) <=
+                generatedJsonPrintWidth;
         if (shouldCompact) {
             return compact;
         }
-        const items = value.map((item, index) => `${" ".repeat(indentation + 2)}${serializeJsonValue(item, indentation + 2, [...pathSegments, String(index)], multilineArrays, rootKeyOrder, nestedKeyOrder)}`);
+        const items = value.map((item, index) => `${" ".repeat(indentation + 2)}${serializeJsonValue(item, indentation + 2, [...pathSegments, String(index)], multilineArrays, rootKeyOrder, nestedKeyOrder, indentation + 2, index < value.length - 1)}`);
         return `[\n${items.join(",\n")}\n${" ".repeat(indentation)}]`;
     }
     if (!isRecord(value)) {
@@ -72,7 +74,7 @@ function serializeJsonValue(value, indentation, pathSegments, multilineArrays, r
     }
     return ("{\n" +
         entries
-            .map(([key, entryValue]) => `${" ".repeat(indentation + 2)}${JSON.stringify(key)}: ${serializeJsonValue(entryValue, indentation + 2, [...pathSegments, key], multilineArrays, rootKeyOrder, nestedKeyOrder)}`)
+            .map(([key, entryValue], index) => `${" ".repeat(indentation + 2)}${JSON.stringify(key)}: ${serializeJsonValue(entryValue, indentation + 2, [...pathSegments, key], multilineArrays, rootKeyOrder, nestedKeyOrder, indentation + 2 + JSON.stringify(key).length + 2, index < entries.length - 1)}`)
             .join(",\n") +
         `\n${" ".repeat(indentation)}}`);
 }
@@ -124,13 +126,17 @@ async function renderMergeJson(operation, options) {
 }
 async function renderMergeJsonTemplate(operation, options) {
     const sourcePath = resolveTemplateSource(operation.source, operation.from);
+    const sourceText = await readFile(sourcePath, "utf8");
     let patch;
     try {
-        patch = JSON.parse(await readFile(sourcePath, "utf8"));
+        patch = JSON.parse(sourceText);
     }
     catch (error) {
         throw new Error(`Invalid JSON Template Source ${operation.from}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
+    if (operation.replacements !== undefined) {
+        patch = replaceJsonTemplateVariables(patch, operation.replacements);
+    }
     await mergeJsonIntoFile({
         options,
         patch,
@@ -140,6 +146,40 @@ async function renderMergeJsonTemplate(operation, options) {
         nestedKeyOrder: operation.nestedKeyOrder,
     });
 }
+function replaceJsonTemplateVariables(value, replacements) {
+    const used = new Set();
+    const replaceString = (source) => source.replaceAll(/\{\{([A-Za-z][A-Za-z0-9_]*)\}\}/g, (_placeholder, name) => {
+        const replacement = replacements[name];
+        if (replacement === undefined) {
+            throw new Error(`JSON 模板缺少变量：${name}`);
+        }
+        used.add(name);
+        return replacement;
+    });
+    const visit = (current) => {
+        if (typeof current === "string") {
+            return replaceString(current);
+        }
+        if (Array.isArray(current)) {
+            return current.map(visit);
+        }
+        if (typeof current === "object" && current !== null) {
+            const entries = Object.entries(current).map(([key, nestedValue]) => [replaceString(key), visit(nestedValue)]);
+            if (new Set(entries.map(([key]) => key)).size !== entries.length) {
+                throw new Error("JSON 模板变量替换后产生重复对象键");
+            }
+            return Object.fromEntries(entries);
+        }
+        return current;
+    };
+    const rendered = visit(value);
+    for (const name of Object.keys(replacements)) {
+        if (!used.has(name)) {
+            throw new Error(`JSON 模板替换项未被使用：${name}`);
+        }
+    }
+    return rendered;
+}
 async function mergeJsonIntoFile(options) {
     const to = resolveContainedPath(options.options.targetRoot, options.toPath);
     let existing = {};
@@ -156,7 +196,10 @@ async function mergeJsonIntoFile(options) {
 async function renderWriteText(operation, options) {
     const to = resolveContainedPath(options.targetRoot, operation.to);
     await mkdir(path.dirname(to), { recursive: true });
-    await writeGeneratedFile(to, operation.text);
+    await writeGeneratedFile(to, operation.text, operation.overwrite ?? false);
+    if (operation.mode !== undefined) {
+        await chmod(to, operation.mode & 0o777);
+    }
 }
 async function loadTextFragments(operation) {
     return Promise.all(operation.fragments.map(async (fragment) => {
@@ -164,45 +207,9 @@ async function loadTextFragments(operation) {
         return { from: fragment.from, text: await readFile(from, "utf8") };
     }));
 }
-async function validateDevelopmentContainerDockerfileOperation(operation, fragments) {
-    if (operation.validation !== "development-container-dockerfile") {
-        return;
-    }
-    const [baseFragment, ...optionalFragments] = fragments;
-    if (baseFragment === undefined) {
-        throw new Error("Development Container Dockerfile requires a base fragment.");
-    }
-    const { validateDevelopmentContainerDockerfileFragments } = await import("./development-container-tool-layer.js");
-    validateDevelopmentContainerDockerfileFragments({
-        baseFragment: {
-            identity: baseFragment.from,
-            from: baseFragment.from,
-            text: baseFragment.text,
-        },
-        fragments: optionalFragments.map((fragment) => ({
-            identity: fragment.from,
-            from: fragment.from,
-            text: fragment.text,
-        })),
-    });
-}
-async function preflightDevelopmentContainerDockerfiles(options) {
-    const loadedFragments = new Map();
-    for (const operation of options.operations) {
-        if (operation.kind !== "writeTextFromFragments" ||
-            operation.validation !== "development-container-dockerfile") {
-            continue;
-        }
-        const fragments = await loadTextFragments(operation);
-        await validateDevelopmentContainerDockerfileOperation(operation, fragments);
-        loadedFragments.set(operation, fragments);
-    }
-    return loadedFragments;
-}
-async function renderWriteTextFromFragments(operation, options, preloadedFragments) {
+async function renderWriteTextFromFragments(operation, options) {
     const to = resolveContainedPath(options.targetRoot, operation.to);
-    const fragments = preloadedFragments ?? (await loadTextFragments(operation));
-    await validateDevelopmentContainerDockerfileOperation(operation, fragments);
+    const fragments = await loadTextFragments(operation);
     await mkdir(path.dirname(to), { recursive: true });
     await writeGeneratedFile(to, fragments.map(({ text }) => text.trimEnd()).join("\n\n") + "\n", operation.overwrite ?? false);
 }
@@ -239,74 +246,6 @@ async function renderSetExecutable(operation, options) {
         : currentMode & ~executeBits;
     await chmod(filePath, mode & 0o777);
 }
-function parseAnchorComment(commentText) {
-    const singleLine = commentText.match(/^\/\/\s*@template-anchor\s+([A-Za-z][A-Za-z0-9_-]*)\s*$/);
-    if (singleLine) {
-        return singleLine[1];
-    }
-    const multiline = commentText.match(/^\/\*\s*@template-anchor\s+([A-Za-z][A-Za-z0-9_-]*)\s*\*\/$/);
-    return multiline?.[1];
-}
-async function findTypeScriptAnchorRanges(sourceText) {
-    const ts = await import("typescript");
-    const sourceFile = ts.createSourceFile("template-anchor.ts", sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-    const anchors = [];
-    const seenRanges = new Set();
-    if ((sourceFile.parseDiagnostics ?? []).length > 0) {
-        throw new Error("Checked Transform Anchor requires valid TypeScript source");
-    }
-    function collectNodeAnchors(node) {
-        if (node.kind === ts.SyntaxKind.EndOfFileToken) {
-            return;
-        }
-        const comments = ts.getLeadingCommentRanges(sourceText, node.getFullStart()) ?? [];
-        for (const comment of comments) {
-            const name = parseAnchorComment(sourceText.slice(comment.pos, comment.end));
-            const rangeKey = `${comment.pos}:${comment.end}`;
-            if (name === undefined || seenRanges.has(rangeKey)) {
-                continue;
-            }
-            seenRanges.add(rangeKey);
-            anchors.push({
-                name,
-                start: comment.pos,
-                end: comment.end,
-            });
-        }
-        ts.forEachChild(node, collectNodeAnchors);
-    }
-    ts.forEachChild(sourceFile, collectNodeAnchors);
-    return anchors;
-}
-function replaceRanges(sourceText, ranges, replacements) {
-    let nextText = sourceText;
-    for (const range of ranges.toSorted((a, b) => b.start - a.start)) {
-        const replacement = replacements[range.name];
-        if (replacement === undefined) {
-            continue;
-        }
-        nextText = `${nextText.slice(0, range.start)}${replacement}${nextText.slice(range.end)}`;
-    }
-    return nextText;
-}
-async function renderReplaceAnchors(operation, options) {
-    if (operation.language !== "typescript") {
-        throw new Error("Checked Transform Anchor only supports TypeScript");
-    }
-    const filePath = resolveContainedPath(options.targetRoot, operation.path);
-    const sourceText = await readFile(filePath, "utf8");
-    const ranges = await findTypeScriptAnchorRanges(sourceText);
-    for (const anchorName of Object.keys(operation.replacements)) {
-        const matches = ranges.filter((range) => range.name === anchorName);
-        if (matches.length === 0) {
-            throw new Error(`Missing Checked Transform Anchor: ${anchorName}`);
-        }
-        if (matches.length > 1) {
-            throw new Error(`Duplicate Checked Transform Anchor: ${anchorName}`);
-        }
-    }
-    await writeFile(filePath, replaceRanges(sourceText, ranges, operation.replacements), "utf8");
-}
 function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }
@@ -359,7 +298,6 @@ async function writeGeneratedFile(to, text, overwrite = false) {
     }
 }
 export async function renderProject(options) {
-    const preloadedDevelopmentContainerDockerfiles = await preflightDevelopmentContainerDockerfiles(options);
     for (const operation of options.operations) {
         if (operation.kind === "copyFile") {
             await renderCopyFile(operation, options);
@@ -382,7 +320,7 @@ export async function renderProject(options) {
             continue;
         }
         if (operation.kind === "writeTextFromFragments") {
-            await renderWriteTextFromFragments(operation, options, preloadedDevelopmentContainerDockerfiles.get(operation));
+            await renderWriteTextFromFragments(operation, options);
             continue;
         }
         if (operation.kind === "writeTextTemplate") {
@@ -393,147 +331,9 @@ export async function renderProject(options) {
             await renderSetExecutable(operation, options);
             continue;
         }
-        if (operation.kind === "replaceAnchors") {
-            await renderReplaceAnchors(operation, options);
-            continue;
-        }
         throw new Error(`Unsupported renderer operation: ${operation.kind}`);
     }
 }
-/**
- * Creates a renderer that applies a follow-up plan in a sibling staging
- * directory. Metadata updates cannot become visible when a later source
- * operation fails.
- */
-export function createAtomicProjectRenderer(dependencies = {}) {
-    const commitPath = dependencies.commitPath ??
-        (async (options) => options.commit());
-    return async (options) => {
-        const targetRoot = path.resolve(options.targetRoot);
-        await stat(targetRoot);
-        const parent = path.dirname(targetRoot);
-        const stagingRoot = await mkdtemp(path.join(parent, `.${path.basename(targetRoot)}.template-update-`));
-        const backupRoot = await mkdtemp(path.join(parent, `.${path.basename(targetRoot)}.template-backup-`));
-        const changedPaths = changedOutputPaths(options.operations);
-        let committed = false;
-        try {
-            await stageInstalledWorkspace(targetRoot, stagingRoot);
-            await renderProject({ ...options, targetRoot: stagingRoot });
-            // Commit only the files changed by the staged plan.  In particular, do
-            // not rename the target directory: callers commonly run `template add`
-            // from that directory, and renaming it leaves their shell on a deleted
-            // inode.  Each path has a rollback copy before it is made visible.
-            for (const changedPath of changedPaths) {
-                const current = path.join(targetRoot, changedPath);
-                try {
-                    const backup = path.join(backupRoot, changedPath);
-                    await mkdir(path.dirname(backup), { recursive: true });
-                    await cp(current, backup, {
-                        recursive: true,
-                        filter: createGeneratedDependencyTreeCopyFilter(current),
-                    });
-                }
-                catch (error) {
-                    if (!isNodeError(error) || error.code !== "ENOENT")
-                        throw error;
-                }
-            }
-            try {
-                for (const changedPath of changedPaths) {
-                    const target = path.join(targetRoot, changedPath);
-                    const staged = path.join(stagingRoot, changedPath);
-                    await mkdir(path.dirname(target), { recursive: true });
-                    await commitPath({
-                        relativePath: changedPath,
-                        stagingRoot,
-                        targetRoot,
-                        commit: async () => cp(staged, target, {
-                            recursive: true,
-                            force: true,
-                            filter: createGeneratedDependencyTreeCopyFilter(staged),
-                        }),
-                    });
-                }
-                committed = true;
-            }
-            catch (error) {
-                await rollbackStagedPaths({ targetRoot, backupRoot, changedPaths });
-                throw error;
-            }
-        }
-        finally {
-            if (!committed)
-                await rm(stagingRoot, { recursive: true, force: true });
-            await rm(backupRoot, { recursive: true, force: true });
-            if (committed)
-                await rm(stagingRoot, { recursive: true, force: true });
-        }
-    };
-}
-export const renderProjectAtomically = createAtomicProjectRenderer();
-function changedOutputPaths(operations) {
-    const changedPaths = new Set();
-    for (const operation of operations) {
-        const outputPath = operation.kind === "setExecutable" || operation.kind === "replaceAnchors"
-            ? operation.path
-            : operation.to;
-        if (outputPath.length > 0)
-            changedPaths.add(path.normalize(outputPath));
-    }
-    return [...changedPaths];
-}
-const stagedDependencyTreeDirectoryNames = new Set([
-    ".pnpm-store",
-    "node_modules",
-]);
-function createGeneratedDependencyTreeCopyFilter(sourceRoot) {
-    const resolvedSourceRoot = path.resolve(sourceRoot);
-    return (source) => !path
-        .relative(resolvedSourceRoot, source)
-        .split(path.sep)
-        .some((part) => stagedDependencyTreeDirectoryNames.has(part));
-}
-async function stageInstalledWorkspace(targetRoot, stagingRoot) {
-    await cp(targetRoot, stagingRoot, {
-        recursive: true,
-        filter: createGeneratedDependencyTreeCopyFilter(targetRoot),
-    });
-    await linkInstalledDependencyTrees(targetRoot, stagingRoot);
-}
-async function linkInstalledDependencyTrees(sourceDirectory, stagingDirectory) {
-    for (const entry of await readdir(sourceDirectory, { withFileTypes: true })) {
-        const source = path.join(sourceDirectory, entry.name);
-        const staged = path.join(stagingDirectory, entry.name);
-        if (entry.name === ".pnpm-store") {
-            continue;
-        }
-        if (entry.name === "node_modules") {
-            await symlink(source, staged, process.platform === "win32" ? "junction" : "dir");
-            continue;
-        }
-        if (entry.isDirectory()) {
-            await linkInstalledDependencyTrees(source, staged);
-        }
-    }
-}
-async function rollbackStagedPaths(options) {
-    for (const changedPath of options.changedPaths) {
-        const target = path.join(options.targetRoot, changedPath);
-        const backup = path.join(options.backupRoot, changedPath);
-        await rm(target, { recursive: true, force: true });
-        try {
-            await mkdir(path.dirname(target), { recursive: true });
-            await cp(backup, target, {
-                recursive: true,
-                filter: createGeneratedDependencyTreeCopyFilter(backup),
-            });
-        }
-        catch (error) {
-            if (!isNodeError(error) || error.code !== "ENOENT")
-                throw error;
-        }
-    }
-}
 async function commitStagedProject(stagingRoot, targetRoot) {
     const targetStatus = await targetDirectoryStatus(targetRoot);
     if (targetStatus === "empty") {

package/node_modules/@ykdz/template-core/dist/toml.d.ts

@@ -0,0 +1,6 @@
+export type TomlStringProjection = {
+    readonly path: readonly (string | number)[];
+    readonly value: string;
+};
+/** 只投影已存在的 TOML 字符串值，保留注释及其余原生格式。 */
+export declare function projectTomlStringValues(source: string, projections: readonly TomlStringProjection[]): string;

package/node_modules/@ykdz/template-core/dist/toml.js

@@ -0,0 +1,31 @@
+import { parseTOML } from "toml-eslint-parser";
+/** 只投影已存在的 TOML 字符串值，保留注释及其余原生格式。 */
+export function projectTomlStringValues(source, projections) {
+    const values = new Map();
+    for (const entry of parseTOML(source, { tomlVersion: "1.0" }).body[0].body) {
+        const prefix = entry.type === "TOMLTable" ? entry.resolvedKey : [];
+        const properties = entry.type === "TOMLTable" ? entry.body : [entry];
+        for (const property of properties) {
+            const keys = property.key.keys.map((key) => key.type === "TOMLBare" ? key.name : key.value);
+            values.set(JSON.stringify([...prefix, ...keys]), property);
+        }
+    }
+    const replacements = projections.flatMap((projection) => {
+        const property = values.get(JSON.stringify(projection.path));
+        const node = property?.value;
+        if (node?.type !== "TOMLValue" || node.kind !== "string") {
+            throw new Error(`TOML 投影要求已有字符串字段 ${JSON.stringify(projection.path)}`);
+        }
+        if (node.value === projection.value)
+            return [];
+        return [{ range: node.range, text: JSON.stringify(projection.value) }];
+    });
+    let result = source;
+    for (const replacement of replacements.toSorted((left, right) => right.range[0] - left.range[0])) {
+        result =
+            result.slice(0, replacement.range[0]) +
+                replacement.text +
+                result.slice(replacement.range[1]);
+    }
+    return result;
+}

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

@@ -0,0 +1,188 @@
+import type { ContentIdentity, ContentSelector, LoadedContentMember } from "./content-identity.ts";
+import type { PackageContribution } from "./package-contribution.ts";
+import type { PackageDefinition, PackageDefinitionId, PersistedPackageDefinition, ProjectBlueprint } from "./project-blueprint.ts";
+import type { ProjectProjectionReconciliation } from "./project-projection.ts";
+import type { RenderOperation } from "./renderer.ts";
+export { generationRecordSchema, parseGenerationRecordStructure, } from "./generation-record.ts";
+/** 生成器显式接收的一项内容定义。 */
+export type PackageCreationInput<Variant = unknown> = {
+    /** 可由工作区策略解释的有限包布局输入。 */
+    readonly leafName?: string;
+    readonly packagePath?: string;
+    /** 内容拥有的有限选择，生成器只保存并透传。 */
+    readonly variant?: Variant;
+};
+export type GeneratorSelectionRoot<CreationInput = PackageCreationInput, NodeLayout = unknown> = {
+    /** 在本次组合中稳定的节点身份，用于把策略计算连到持久包实例。 */
+    readonly nodeIdentity: string;
+    readonly contentIdentity: ContentSelector;
+    readonly creationInput?: CreationInput;
+    readonly configuration?: unknown;
+    /** 仅由拥有策略解释；通用生成器不解析布局内容。 */
+    readonly layout?: NodeLayout;
+};
+export type GeneratorPackageCreatedBy = "initialization" | "addition" | "shared-dependency";
+export type GeneratorContentDefinition<Context, Contribution extends PackageContribution, CreationInput = PackageCreationInput> = {
+    readonly alias: string;
+    readonly instance: "shared" | "independent";
+    readonly defaultLeafName: string;
+    readonly defaultPath: string;
+    readonly role: PackageDefinition["role"];
+    /** 所属内容准备自身声明的资源事实；通用生成器只管理调用时机。 */
+    prepare?(): unknown;
+    /** 所属内容规范化现行配置；通用机制不解释配置字段。 */
+    normalizeConfiguration?(input: unknown): unknown;
+    contribute(options: {
+        readonly context: Context;
+        readonly configuration: unknown;
+        readonly definition: PackageDefinition;
+        readonly bindings?: ReadonlyMap<string, PackageDefinition>;
+        /** 创建该包实例时持久化的原始操作。 */
+        readonly createdBy: GeneratorPackageCreatedBy;
+        readonly creationInput?: CreationInput;
+        /** 按稳定节点身份解析、供项目行为使用的实例。 */
+        readonly nodeInstances: GeneratorNodeInstances;
+        /** 同一所属内容prepare返回的事实，由生成器原样传递。 */
+        readonly preparation?: unknown;
+    }): Contribution;
+};
+/** 本次实际公开入口装载的参考包；definition保留拥有者原对象。 */
+export type GeneratorContent<Context, Contribution extends PackageContribution, CreationInput = PackageCreationInput> = LoadedContentMember<GeneratorContentDefinition<Context, Contribution, CreationInput>, "reference">;
+export type GeneratorPackageRecord<CreationInput = PackageCreationInput> = {
+    readonly contentIdentity: ContentIdentity;
+    readonly createdBy: GeneratorPackageCreatedBy;
+    /** 与蓝图中的完整 Package Definition 通过此 ID 关联。 */
+    readonly packageDefinitionId: PackageDefinitionId;
+    /** 内容拥有者解释原始输入；null 明确表示本次没有显式输入。 */
+    readonly creationInput: CreationInput | null;
+    /** 所属内容解释的唯一现行配置，与创建来源和布局分开。 */
+    readonly configuration: unknown;
+    /** 以内容身份为键，记录已选包实例的持久化标识。 */
+    readonly bindings: Readonly<Record<string, string>>;
+};
+/**
+ * 生成操作内将记录按 packageDefinitionId 与蓝图 join 后的视图。
+ * 仅供策略和贡献消费，不作为持久记录或公开结果返回。
+ */
+export type GeneratorPackageState<CreationInput = PackageCreationInput> = GeneratorPackageRecord<CreationInput> & {
+    readonly definition: PersistedPackageDefinition;
+};
+/** 当前记录合同的实际公开形状；持久化格式为 schema4。 */
+export type GenerationRecord<CreationInput = PackageCreationInput> = {
+    readonly schemaVersion: 4;
+    readonly strategyIdentity: string;
+    readonly strategyState: unknown;
+    readonly packages: readonly GeneratorPackageRecord<CreationInput>[];
+    readonly nodeInstances: GeneratorNodeInstanceIds;
+    /** 本仓库中实际选用过的规范预设身份。 */
+    readonly presetSelections: readonly ContentIdentity[];
+};
+/** 持久化节点表仅引用蓝图已有的包实例身份。 */
+export type GeneratorNodeInstanceIds = Readonly<Record<string, PackageDefinitionId>>;
+/** 策略计算看到的节点实例是解析后的真实 Definition。 */
+export type GeneratorNodeInstances = ReadonlyMap<string, PackageDefinition>;
+export type WorkspaceProjection<OwnerFacts = unknown> = {
+    /** 策略拥有并封闭管理、并入当前蓝图的项目关系。 */
+    readonly blueprint?: ProjectBlueprint;
+    readonly operations: readonly RenderOperation[];
+    readonly reconciliation: readonly ProjectProjectionReconciliation[];
+    /** 所属策略为本次消费者提供的有限检查事实；生成器只原样透传。 */
+    readonly ownerFacts?: OwnerFacts;
+};
+/** 所属 workspace owner 通过既有 generator 结果返回的用户输入诊断。 */
+export type WorkspaceStrategyInputIssue = {
+    readonly code: string;
+};
+export type WorkspaceStrategyValidationResult = {
+    readonly status: "input-invalid";
+    readonly issues: readonly WorkspaceStrategyInputIssue[];
+} | {
+    readonly status: "conflict";
+    /** Owner 自有的冲突代码与事实由调用方原样解释。 */
+    readonly conflict: {
+        readonly code: string;
+        readonly facts: unknown;
+    };
+} | void;
+/** 策略为自身失败附带、供命令层原样显示的结构化诊断。 */
+export type WorkspaceStrategyFailureDiagnostic = {
+    readonly message: string;
+    readonly suggestion: string;
+};
+/**
+ * 工作区策略拥有自身持久事实、上下文解释和根投影。生成器不解释策略状态，
+ * 只负责包实例、绑定、记录演化以及 Before/After 组合。
+ */
+export type WorkspaceStrategy<Context, Input, StrategyState, Contribution extends PackageContribution, CreationInput extends PackageCreationInput = PackageCreationInput, Content extends GeneratorContent<Context, Contribution, CreationInput> = GeneratorContent<Context, Contribution, CreationInput>, NodeLayout = unknown, PresetProjectContribution = unknown, OwnerFacts = unknown> = {
+    readonly identity: string;
+    initialize(options: {
+        readonly targetRoot: string;
+        readonly input: Input;
+        readonly selection: readonly GeneratorSelectionRoot<CreationInput, NodeLayout>[];
+        /** 实际登记且已解析的参考内容，键为规范三元组编码。 */
+        readonly contentByIdentity: ReadonlyMap<string, Content>;
+    }): {
+        readonly context: Context;
+        readonly state: StrategyState;
+    };
+    prepareUpdate(options: {
+        readonly targetRoot: string;
+        readonly state: StrategyState;
+        readonly content: Content;
+        readonly contentByIdentity: ReadonlyMap<string, Content>;
+        readonly configuration: unknown;
+        readonly packages: readonly GeneratorPackageState<CreationInput>[];
+        readonly nodeInstances: GeneratorNodeInstances;
+        /** 原始创建输入由策略解释；配置操作沿用实例事实。 */
+        readonly creationInput?: CreationInput;
+    }): Context | Promise<Context>;
+    /**
+     * 上下文和当前贡献准备完成后，策略可校验仍生效的当前工作区事实。
+     * 生成器只透传内容与预设计算，不解释所属策略的校验规则。
+     */
+    validateAddition?(options: {
+        readonly targetRoot: string;
+        readonly blueprint: ProjectBlueprint;
+        readonly content: Content;
+        readonly definition: PackageDefinition;
+        readonly creationInput?: CreationInput;
+        readonly packages: readonly GeneratorPackageState<CreationInput>[];
+        readonly contributions: readonly Contribution[];
+        /** 按需构造同次加包贡献，正式投影复用该结果。 */
+        readonly getAdditionContributions: () => readonly Contribution[];
+        readonly nodeInstances: GeneratorNodeInstances;
+        readonly presetProjectContributions: readonly PresetProjectContribution[];
+    }): WorkspaceStrategyValidationResult | Promise<WorkspaceStrategyValidationResult>;
+    /** 策略可将自身已知的错误转成面向调用方的诊断；生成器不解释其语义。 */
+    diagnoseFailure?(error: unknown): WorkspaceStrategyFailureDiagnostic | undefined;
+    parseState(value: unknown): StrategyState;
+    /** 策略把原生依赖声明映射为显式内容身份。 */
+    dependencies(options: {
+        readonly content: Content;
+        readonly contentByIdentity: ReadonlyMap<string, Content>;
+        readonly configuration: unknown;
+        readonly creationInput?: CreationInput;
+    }): readonly ContentIdentity[];
+    /** 策略把已选依赖实例映射为内容原生的绑定键。 */
+    bindings(options: {
+        readonly content: Content;
+        readonly contentByIdentity: ReadonlyMap<string, Content>;
+        readonly providers: ReadonlyMap<string, PackageDefinition>;
+    }): ReadonlyMap<string, PackageDefinition>;
+    createDefinition(options: {
+        readonly context: Context;
+        readonly content: Content;
+        readonly creationInput?: CreationInput;
+        readonly layout?: NodeLayout;
+    }): PackageDefinition;
+    project(options: {
+        readonly context: Context;
+        readonly state: StrategyState;
+        readonly blueprint: ProjectBlueprint;
+        readonly packages: readonly GeneratorPackageState<CreationInput>[];
+        readonly contributions: readonly Contribution[];
+        readonly nodeInstances: GeneratorNodeInstances;
+        /** 各已选预设计算的封闭项目贡献由策略解释。 */
+        readonly presetProjectContributions: readonly PresetProjectContribution[];
+    }): WorkspaceProjection<OwnerFacts>;
+};

package/node_modules/@ykdz/template-core/dist/workspace-strategy.js

@@ -0,0 +1 @@
+export { generationRecordSchema, parseGenerationRecordStructure, } from "./generation-record.js";