@birdie_moblie/open_spec 2.1.7 → 2.2.0

package/dist/config/preset-use.js

@@ -0,0 +1,282 @@
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { isMap, isScalar, parseDocument, stringify as stringifyYaml } from 'yaml';
+import { exists, readText, removePath, writeText, writeTextAtomic } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { compareVersions } from '../shared/version.js';
+import { configPathOf, loadConfig, loadProjectConfig } from './load.js';
+import { listChangeNames } from '../core/change.js';
+import { diffBaselines, resolveEffectiveConfig, scaffoldFrom } from './presets.js';
+import { fetchPresetRepo, presetBaseline, presetLockPath, presetRootForProject, readRepoPreset, writePresetLock } from './preset-repo.js';
+import { effectiveTaskCategories, HOOK_STAGES } from './schema.js';
+import { resolveInside } from '../shared/paths.js';
+/** 在已有 config.yaml 中写入 preset 引用；保留其余内容与注释，新键放在 schema 之后。 */
+function writePresetReference(configFile, original, reference) {
+    const document = parseDocument(original);
+    if (document.has('preset'))
+        document.set('preset', reference);
+    else if (isMap(document.contents)) {
+        const map = document.contents;
+        const schemaIndex = map.items.findIndex((pair) => isScalar(pair.key) && pair.key.value === 'schema');
+        map.items.splice(schemaIndex + 1, 0, document.createPair('preset', reference));
+    }
+    else {
+        document.set('preset', reference);
+    }
+    writeText(configFile, document.toString());
+}
+/**
+ * 执行会改 config 与锁的步骤（参数为 config 原文）；任何一步失败都按原字节还原两者再抛出。
+ * 锁是 JSON，按规范用同目录临时文件加 rename 写回。
+ */
+function withRollback(configFile, lockFile, action) {
+    const original = { config: readText(configFile), lock: exists(lockFile) ? readText(lockFile) : undefined };
+    try {
+        return action(original.config);
+    }
+    catch (error) {
+        writeText(configFile, original.config);
+        if (original.lock === undefined)
+            removePath(lockFile);
+        else
+            writeTextAtomic(lockFile, original.lock);
+        throw error;
+    }
+}
+/**
+ * 让项目引用 preset 仓库中的一个 preset：拉取并锁定快照，写入引用，确认合成后的生效配置合法，再生成模板文件。
+ * 任何一步失败都按原字节还原 config 与锁。
+ */
+export function usePreset(input) {
+    const { projectRoot, id, repo, ref } = input;
+    const configFile = configPathOf(projectRoot);
+    if (!configFile)
+        throw new AppError('project_uninitialized', '缺少 openspec/config.yaml，请先运行 openspec init');
+    const snapshot = fetchPresetRepo(repo, ref);
+    const preset = readRepoPreset(snapshot.cachePath, id);
+    const scaffold = withRollback(configFile, presetLockPath(projectRoot), (original) => {
+        writePresetLock(projectRoot, { version: 1, repo, ref, id, resolvedSha: snapshot.resolvedSha, digest: snapshot.digest });
+        writePresetReference(configFile, original, { repo, ref, id });
+        loadConfig(projectRoot);
+        return scaffoldFrom(projectRoot, path.join(snapshot.cachePath, id), id, preset.scaffold ?? []);
+    });
+    return {
+        id, repo, ref, resolvedSha: snapshot.resolvedSha, digest: snapshot.digest, scaffold,
+        notes: preset.notes ?? [], warnings: preset.warnings ?? [],
+    };
+}
+/** 生效配置中 diffBaselines 所指的一项；分类取含默认分类与删除语义后的结果。 */
+function effectiveItem(config, section, id) {
+    switch (section) {
+        case 'taskCategories': return effectiveTaskCategories(config)[id];
+        case 'hooks': return config.hooks?.find((hook) => hook.id === id);
+        case 'plugins': return config.plugins?.find((item) => `${item.name}@${item.marketplace}` === id);
+        case 'marketplaces': return config.marketplaces?.find((item) => item.name === id);
+        case 'verify': {
+            const [group = '', field = ''] = id.split('.');
+            return config.verify?.[group]?.[field];
+        }
+        default: return undefined;
+    }
+}
+/**
+ * 把项目引用的 preset 升级到新 ref：列出基线的新增、修改与删除；按升级前后的生效配置，
+ * 生效值不变的条目即被项目层遮住（覆盖、禁用或更高的插件最低版本），单独列出。
+ * 只改 config 中的 ref 值并更新锁，确认生效配置合法后补齐新模板。任何一步失败都按原字节还原 config 与锁。
+ */
+export function upgradePreset(input) {
+    const { projectRoot, ref } = input;
+    const configFile = configPathOf(projectRoot);
+    const layer = loadProjectConfig(projectRoot);
+    if (!configFile || !layer.preset)
+        throw new AppError('preset_not_configured', '项目没有引用 preset；先运行 openspec preset use');
+    const active = listChangeNames(projectRoot);
+    if (active.length > 0 && !input.allowActiveChanges) {
+        throw new AppError('active_changes_present', `存在进行中的 change：${active.join(', ')}。它们按旧规则生成计划与回执，升级后需要重新确认；确认后加 --allow-active-changes`);
+    }
+    const reference = layer.preset;
+    const current = presetRootForProject(projectRoot, reference);
+    const previous = presetBaseline(readRepoPreset(current.root, reference.id));
+    const snapshot = fetchPresetRepo(reference.repo, ref);
+    const preset = readRepoPreset(snapshot.cachePath, reference.id);
+    const next = presetBaseline(preset);
+    const changes = diffBaselines(previous.patch, next.patch);
+    const before = resolveEffectiveConfig(layer, previous);
+    const after = resolveEffectiveConfig(layer, next);
+    const shadowed = Object.entries(changes).flatMap(([section, diff]) => [...diff.added, ...diff.changed, ...diff.removed]
+        .filter((id) => same(effectiveItem(before, section, id), effectiveItem(after, section, id)))
+        .map((id) => ({ section, id })));
+    const from = { ref: reference.ref, resolvedSha: current.lock.resolvedSha };
+    const to = { ref, resolvedSha: snapshot.resolvedSha };
+    if (ref === reference.ref && snapshot.resolvedSha === current.lock.resolvedSha) {
+        return { id: reference.id, status: 'unchanged', from, to, changes, shadowed, scaffold: [] };
+    }
+    const scaffold = withRollback(configFile, presetLockPath(projectRoot), (original) => {
+        writePresetLock(projectRoot, { version: 1, ...reference, ref, resolvedSha: snapshot.resolvedSha, digest: snapshot.digest });
+        const document = parseDocument(original);
+        // 改原 Scalar 的值而不是替换节点，保留写在 ref 行上的注释。
+        const node = document.getIn(['preset', 'ref'], true);
+        if (isScalar(node))
+            node.value = ref;
+        else
+            document.setIn(['preset', 'ref'], ref);
+        writeText(configFile, document.toString());
+        loadConfig(projectRoot);
+        return scaffoldFrom(projectRoot, path.join(snapshot.cachePath, reference.id), reference.id, preset.scaffold ?? []);
+    });
+    return { id: reference.id, status: 'upgraded', from, to, changes, shadowed, scaffold };
+}
+const same = (a, b) => isDeepStrictEqual(a, b);
+/**
+ * 生效配置的等价比较：hook 按阶段分组比较组内顺序（同阶段的注入顺序有语义，跨阶段无关），
+ * 插件（不含最低版本，另行比较）与 marketplace 按集合比较，分类按键比较，验收设置忽略空对象。
+ */
+function comparable(config) {
+    const bySelector = (items = []) => [...items].sort((a, b) => `${a.name}@${a.marketplace ?? ''}`.localeCompare(`${b.name}@${b.marketplace ?? ''}`));
+    return {
+        taskCategories: effectiveTaskCategories(config),
+        hooks: Object.fromEntries(HOOK_STAGES.map((stage) => [stage, (config.hooks ?? []).filter((hook) => hook.stage === stage)])),
+        verify: nonEmptyVerify(config.verify) ?? {},
+        plugins: bySelector((config.plugins ?? []).map(({ name, marketplace }) => ({ name, marketplace }))),
+        marketplaces: bySelector(config.marketplaces),
+        tools: config.tools ?? [],
+    };
+}
+/** 去掉验收设置里的空对象；全空时视为未设置。 */
+function nonEmptyVerify(verify) {
+    const entries = Object.entries(verify ?? {}).filter(([, value]) => value && Object.keys(value).length > 0);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/**
+ * preset 的 minVersion 只能提高、不能被项目层调低，迁移后插件最低版本可能变严。
+ * 返回提高了的插件；出现变宽松（理论上不会发生）时返回 null，按不等价处理。
+ */
+function raisedMinVersions(before, after) {
+    const raised = [];
+    for (const plugin of after.plugins ?? []) {
+        const previous = (before.plugins ?? []).find((item) => item.name === plugin.name && item.marketplace === plugin.marketplace);
+        if (previous?.minVersion === plugin.minVersion)
+            continue;
+        if (!plugin.minVersion)
+            return null;
+        if (previous?.minVersion && (compareVersions(plugin.minVersion, previous.minVersion) ?? -1) < 0)
+            return null;
+        raised.push({ plugin: `${plugin.name}@${plugin.marketplace}`, ...(previous?.minVersion ? { from: previous.minVersion } : {}), to: plugin.minVersion });
+    }
+    return raised;
+}
+/** 验收设置按字段合成，迁移同样按字段只保留与基线不同的值。 */
+function verifyOverrides(current, base) {
+    const baseFields = (base ?? {});
+    const groups = Object.entries((current ?? {}))
+        .map(([group, fields]) => [group, Object.fromEntries(Object.entries(fields ?? {})
+            .filter(([field, value]) => !same(value, baseFields[group]?.[field])))])
+        .filter(([, fields]) => Object.keys(fields).length > 0);
+    return groups.length > 0 ? Object.fromEntries(groups) : undefined;
+}
+/** 分层后各阶段 hook 顺序与原配置不同时，用 hookOrder 固定为原顺序。 */
+function preserveHookOrder(layer, baseline, current) {
+    const merged = resolveEffectiveConfig(layer, baseline);
+    const stageIds = (config, stage) => (config.hooks ?? []).filter((hook) => hook.stage === stage).map((hook) => hook.id);
+    const hookOrder = Object.fromEntries(HOOK_STAGES
+        .filter((stage) => !same(stageIds(merged, stage), stageIds(current, stage)))
+        .map((stage) => [stage, stageIds(current, stage)]));
+    return Object.keys(hookOrder).length > 0 ? { ...layer, hookOrder } : layer;
+}
+/** 从拷贝式配置中提取项目层：与基线相同的条目改为继承，不同的保留为覆盖，基线多出的 hook 写入 disableHooks。 */
+function extractProjectLayer(current, base, reference) {
+    const baseCategories = base.taskCategories ?? {};
+    const ownCategories = current.taskCategories ?? {};
+    const effectiveCurrent = effectiveTaskCategories(current);
+    const taskCategories = {};
+    for (const [id, value] of Object.entries(ownCategories)) {
+        if (!same(value, baseCategories[id]))
+            taskCategories[id] = value;
+    }
+    for (const id of Object.keys(baseCategories)) {
+        if (Object.hasOwn(ownCategories, id))
+            continue;
+        // 基线定义了项目原本没有写的分类：保留项目原来的生效值（默认分类）或删除它。
+        taskCategories[id] = effectiveCurrent[id] ? { notes: effectiveCurrent[id].notes } : null;
+    }
+    const baseHooks = new Map((base.hooks ?? []).map((hook) => [hook.id, hook]));
+    const ownHookIds = new Set((current.hooks ?? []).map((hook) => hook.id));
+    const hooks = (current.hooks ?? []).filter((hook) => !same(hook, baseHooks.get(hook.id)));
+    const disableHooks = [...baseHooks.keys()].filter((id) => !ownHookIds.has(id));
+    const basePlugins = base.plugins ?? [];
+    // 同一插件的最低版本合成时取较高值：项目的最低版本不高于基线时，继承基线即可。
+    const plugins = (current.plugins ?? []).filter((item) => {
+        const base = basePlugins.find((candidate) => candidate.name === item.name && candidate.marketplace === item.marketplace);
+        if (!base)
+            return true;
+        if (!item.minVersion)
+            return false;
+        return !base.minVersion || (compareVersions(item.minVersion, base.minVersion) ?? 1) > 0;
+    });
+    const baseMarkets = base.marketplaces ?? [];
+    const marketplaces = (current.marketplaces ?? []).filter((item) => !baseMarkets.some((candidate) => same(candidate, item)));
+    const verify = verifyOverrides(current.verify, base.verify);
+    return {
+        schema: 'spec-product',
+        preset: reference,
+        ...(Object.keys(taskCategories).length > 0 ? { taskCategories } : {}),
+        ...(hooks.length > 0 ? { hooks } : {}),
+        ...(disableHooks.length > 0 ? { disableHooks } : {}),
+        ...(verify ? { verify } : {}),
+        ...(plugins.length > 0 ? { plugins } : {}),
+        ...(marketplaces.length > 0 ? { marketplaces } : {}),
+        ...(current.tools ? { tools: current.tools } : {}),
+    };
+}
+/**
+ * 把拷贝式配置迁移为“引用 preset + 项目层”。迁移前后生效配置必须逐项一致（唯一例外：preset 提高的插件最低版本，
+ * 在结果中列出），否则中止且不写任何文件；
+ * 写入时替换 config（原注释不保留）、写新锁并删除旧的 preset-lock.yaml。dryRun 只返回结果。
+ */
+export function migratePreset(input) {
+    const { projectRoot, id, repo, ref } = input;
+    const configFile = configPathOf(projectRoot);
+    const current = loadProjectConfig(projectRoot);
+    if (!configFile)
+        throw new AppError('project_uninitialized', '缺少 openspec/config.yaml，请先运行 openspec init');
+    if (current.preset)
+        throw new AppError('preset_already_referenced', `项目已引用 preset ${current.preset.id}；升级请用 openspec preset upgrade`);
+    const snapshot = fetchPresetRepo(repo, ref);
+    const baseline = presetBaseline(readRepoPreset(snapshot.cachePath, id));
+    const reference = { repo, ref, id };
+    const before = resolveEffectiveConfig(current);
+    const layer = preserveHookOrder(extractProjectLayer(current, baseline.patch, reference), baseline, before);
+    const after = resolveEffectiveConfig(layer, baseline);
+    const raised = raisedMinVersions(before, after);
+    const sections = Object.keys(comparable(before)).filter((key) => !same(comparable(before)[key], comparable(after)[key]));
+    if (!raised)
+        sections.push('plugins.minVersion');
+    if (sections.length > 0) {
+        throw new AppError('preset_migration_not_equivalent', `迁移后生效配置与迁移前不一致，未写入：${sections.join(', ')}`, { sections });
+    }
+    const inherited = {
+        taskCategories: Object.keys(baseline.patch.taskCategories ?? {}).filter((key) => !Object.hasOwn(layer.taskCategories ?? {}, key)),
+        hooks: (baseline.patch.hooks ?? []).map((hook) => hook.id)
+            .filter((hookId) => !(layer.hooks ?? []).some((hook) => hook.id === hookId) && !(layer.disableHooks ?? []).includes(hookId)),
+        plugins: (baseline.patch.plugins ?? []).map((item) => `${item.name}@${item.marketplace}`)
+            .filter((selector) => !(layer.plugins ?? []).some((item) => `${item.name}@${item.marketplace}` === selector)),
+        marketplaces: (baseline.patch.marketplaces ?? []).map((item) => item.name)
+            .filter((name) => !(layer.marketplaces ?? []).some((item) => item.name === name)),
+    };
+    const legacyLock = resolveInside(projectRoot, 'openspec/preset-lock.yaml', 'preset_lock_outside_project');
+    const result = { id, ref, resolvedSha: snapshot.resolvedSha, removedLegacyLock: exists(legacyLock), layer, inherited, raisedMinVersions: raised ?? [] };
+    if (input.dryRun)
+        return { ...result, written: false };
+    withRollback(configFile, presetLockPath(projectRoot), () => {
+        writePresetLock(projectRoot, { version: 1, ...reference, resolvedSha: snapshot.resolvedSha, digest: snapshot.digest });
+        writeText(configFile, stringifyYaml(layer, { lineWidth: 0 }));
+        const written = loadConfig(projectRoot);
+        if (!same(comparable(written), comparable(before)) || !raisedMinVersions(before, written)) {
+            throw new AppError('preset_migration_not_equivalent', '写入后生效配置与迁移前不一致');
+        }
+    });
+    if (result.removedLegacyLock)
+        removePath(legacyLock);
+    return { ...result, written: true };
+}
+//# sourceMappingURL=preset-use.js.map

package/dist/config/presets.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type ProjectConfig } from './schema.js';
-declare const ScaffoldEntrySchema: z.ZodObject<{
+import { ProjectConfigPatchSchema, type ProjectConfig } from './schema.js';
+export declare const ScaffoldEntrySchema: z.ZodObject<{
     path: z.ZodString;
     template: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -11,119 +11,44 @@ export type ScaffoldResult = {
     status: 'created' | 'exists';
     description?: string;
 };
-export declare const TeamPresetSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<"openspec.team-preset.v1">;
-    id: z.ZodString;
-    version: z.ZodString;
-    title: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    marketplaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        repo: z.ZodString;
-        ref: z.ZodString;
-    }, z.core.$strict>>>;
-    plugins: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        marketplace: z.ZodString;
-        minVersion: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    configPatch: z.ZodOptional<z.ZodObject<{
-        schema: z.ZodOptional<z.ZodLiteral<"spec-product">>;
-        taskCategories: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
-            notes: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>>>;
-        hooks: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            stage: z.ZodEnum<{
-                collect: "collect";
-                parse: "parse";
-                tech: "tech";
-                plan: "plan";
-                execute: "execute";
-                verify: "verify";
-            }>;
-            type: z.ZodOptional<z.ZodEnum<{
-                command: "command";
-                skill: "skill";
-                notes: "notes";
-                file: "file";
-                check: "check";
-            }>>;
-            capability: z.ZodOptional<z.ZodEnum<{
-                requirements: "requirements";
-                interfaces: "interfaces";
-                design: "design";
-            }>>;
-            use: z.ZodOptional<z.ZodString>;
-            operation: z.ZodOptional<z.ZodLiteral<"preview">>;
-            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            name: z.ZodOptional<z.ZodString>;
-            notes: z.ZodOptional<z.ZodString>;
-            taskCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            command: z.ZodOptional<z.ZodString>;
-            target: z.ZodOptional<z.ZodEnum<{
-                project: "project";
-                inScopeChangedFiles: "inScopeChangedFiles";
-            }>>;
-            include: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            allowEmpty: z.ZodOptional<z.ZodBoolean>;
-            required: z.ZodOptional<z.ZodBoolean>;
-            purpose: z.ZodOptional<z.ZodString>;
-            path: z.ZodOptional<z.ZodString>;
-            category: z.ZodOptional<z.ZodString>;
-            description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>>;
-        verify: z.ZodOptional<z.ZodOptional<z.ZodObject<{
-            reviewScope: z.ZodOptional<z.ZodObject<{
-                includeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                excludeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-            failurePolicy: z.ZodOptional<z.ZodObject<{
-                failOnHookFailure: z.ZodOptional<z.ZodBoolean>;
-                failOnRequiredCommandFailure: z.ZodOptional<z.ZodBoolean>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>>>;
-        plugins: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            marketplace: z.ZodString;
-            minVersion: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>>;
-        marketplaces: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            repo: z.ZodString;
-            ref: z.ZodString;
-        }, z.core.$strict>>>>;
-        tools: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEnum<{
-            claude: "claude";
-            codex: "codex";
-            cursor: "cursor";
-        }>>>>;
-    }, z.core.$strict>>;
-    scaffold: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        template: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
-export type TeamPreset = z.infer<typeof TeamPresetSchema>;
-export declare function presetsDir(): string;
-export declare function listPresets(): TeamPreset[];
-export declare function loadPreset(id: string): TeamPreset;
-export declare function mergePreset(base: ProjectConfig, preset: TeamPreset): ProjectConfig;
+export type PresetBaseline = {
+    id: string;
+    patch: z.infer<typeof ProjectConfigPatchSchema>;
+};
+/**
+ * 生效配置 = preset 基线 + 项目层，项目层优先：分类按名覆盖（null 删除）；hook 同 ID 整条替换并保留基线位置，
+ * disableHooks 按 ID 去掉基线 hook，项目新增 hook 追加在后；验收设置按字段覆盖；插件取较高 minVersion；
+ * marketplace 以项目声明为准，基线只补缺；tools 只来自项目层。没有基线时项目层原样即生效配置。
+ */
+export declare function resolveEffectiveConfig(layer: ProjectConfig, baseline?: PresetBaseline): ProjectConfig;
+/** 生效配置中一项的来源：preset 原样、项目覆盖了 preset 的同名项、项目独有、项目删除或禁用了 preset 的项。 */
+export type ConfigOrigin = 'preset' | 'override' | 'project' | 'removed';
+export interface ConfigOrigins {
+    taskCategories: Record<string, ConfigOrigin>;
+    hooks: Record<string, ConfigOrigin>;
+    plugins: Record<string, ConfigOrigin>;
+    marketplaces: Record<string, ConfigOrigin>;
+    /** 按字段，键为 `<分组>.<字段>`（如 reviewScope.excludeDirs），与 diffBaselines 一致 */
+    verify: Record<string, ConfigOrigin>;
+}
+/** 逐项标注生效配置的来源，供查看生效配置、升级提示遮蔽与迁移使用。 */
+export declare function describeOrigins(layer: ProjectConfig, baseline?: PresetBaseline): ConfigOrigins;
+export interface BaselineChanges {
+    added: string[];
+    changed: string[];
+    removed: string[];
+}
+type BaselineSection = 'taskCategories' | 'hooks' | 'plugins' | 'marketplaces' | 'verify';
+/**
+ * 按条目比较两个基线：分类按名、hook 按 ID、插件按 selector、marketplace 按名；
+ * 验收设置与合成一样按字段，条目为 `<分组>.<字段>`（如 reviewScope.excludeDirs）。
+ */
+export declare function diffBaselines(previous: PresetBaseline['patch'], next: PresetBaseline['patch']): Record<BaselineSection, BaselineChanges>;
 /**
  * 把 preset 声明的模板文件放到项目里。已存在的文件一律不动——
- * 团队填写后的内容不能被重复 init 覆盖；模板本身带 openspec:fill-me 标记，未填写时 file hook 不会放行。
+ * 团队填写后的内容不能被重复引用或升级覆盖；模板本身带 openspec:fill-me 标记，未填写时 file hook 不会放行。
+ * 先核对全部模板与目标路径再写入，缺模板时不留下部分生成的文件。
  */
-export declare function scaffoldPreset(projectRoot: string, preset: TeamPreset): ScaffoldResult[];
-/** 合并时保留了宿主 ref、且与 preset 基线不同的 marketplace，供 init / preset apply 提示。 */
-export declare function keptMarketplaceRefs(base: ProjectConfig, preset: TeamPreset): Array<{
-    name: string;
-    ref: string;
-    presetRef: string;
-}>;
+export declare function scaffoldFrom(projectRoot: string, templateRoot: string, presetId: string, entries: ScaffoldEntry[]): ScaffoldResult[];
 export {};
 //# sourceMappingURL=presets.d.ts.map