@birdie_moblie/open_spec 2.1.7 → 2.2.0

package/dist/config/preset-repo.d.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { type PresetBaseline } from './presets.js';
+import { type PresetReference, type ProjectConfig } from './schema.js';
+/** preset 仓库中每个 preset 占一个目录：`<id>/preset.yaml` 加它引用的模板文件。 */
+export declare const REPO_PRESET_FILE = "preset.yaml";
+export declare const RepoPresetSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"openspec.team-preset.v2">;
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodObject<{
+        openspec: 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>>>>;
+    plugins: z.ZodOptional<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<{
+        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>>>;
+        taskCategories: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+            notes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>>>;
+        schema: z.ZodOptional<z.ZodLiteral<"spec-product">>;
+        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>>>>;
+        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 RepoPreset = z.infer<typeof RepoPresetSchema>;
+declare const PresetLockSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    repo: z.ZodString;
+    ref: z.ZodString;
+    id: z.ZodString;
+    resolvedSha: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+export type PresetLock = z.infer<typeof PresetLockSchema>;
+export declare function presetCacheRoot(): string;
+/** 缓存按仓库与提交区分；目录名带仓库地址摘要，避免同名仓库互相覆盖。锁里不存本机路径，成员之间可共享。 */
+export declare function presetCacheDir(repo: string, resolvedSha: string): string;
+export declare function presetLockPath(projectRoot: string): string;
+export declare function readPresetLock(projectRoot: string): PresetLock | null;
+export declare function writePresetLock(projectRoot: string, lock: PresetLock): void;
+/** 拉取仓库在不可变 ref 上的快照；所有读取 preset 仓库的命令都经过这里，ref 在此统一校验。 */
+export declare function fetchPresetRepo(repo: string, ref: string): {
+    resolvedSha: string;
+    cachePath: string;
+    digest: string;
+};
+/** 读取快照中的一个 preset，并检查它要求的 OpenSpec 版本。 */
+export declare function readRepoPreset(root: string, id: string): RepoPreset;
+export declare function presetBaseline(preset: RepoPreset): PresetBaseline;
+/**
+ * 项目引用的 preset 快照目录：锁必须与配置引用一致，缓存必须存在且摘要与锁相同。
+ * 运行时只读缓存、不联网；缺失时提示用 init 补齐。
+ */
+export declare function presetRootForProject(projectRoot: string, reference: PresetReference): {
+    root: string;
+    lock: PresetLock;
+};
+/** loadConfig 使用的基线：未引用 preset 时为 undefined。 */
+export declare function loadPresetBaseline(projectRoot: string, layer: ProjectConfig): PresetBaseline | undefined;
+/**
+ * init 用：让缓存与锁对齐。锁与配置一致时，已缓存则不联网、按锁核对摘要（成员离线也能 init），
+ * 未缓存则按锁里的 SHA 补拉并核对，保证成员拿到同一份内容；没有锁或锁已过期时按配置 ref 重新解析并写锁。
+ */
+export declare function syncPresetCache(projectRoot: string, reference: PresetReference): PresetLock;
+/** doctor 用：不抛错，返回检查结果。 */
+export declare function inspectPreset(projectRoot: string, reference: PresetReference): {
+    id: string;
+    repo: string;
+    ref: string;
+    ok: boolean;
+    code?: string;
+    message?: string;
+    resolvedSha?: string;
+    digest?: string;
+};
+/** 列出快照中的全部 preset：每个含 preset.yaml 的顶层目录一项，按 id 排序。 */
+export declare function listRepoPresets(root: string): Array<{
+    id: string;
+    title: string;
+    description?: string;
+}>;
+export {};
+//# sourceMappingURL=preset-repo.d.ts.map

package/dist/config/preset-repo.js

@@ -0,0 +1,180 @@
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+import { exists, listDirs, readJson, readText, writeJson } from '../shared/fs.js';
+import { digestDirectory, sha256 } from '../shared/hash.js';
+import { AppError } from '../shared/errors.js';
+import { assertPathToken, resolveInside } from '../shared/paths.js';
+import { compareVersions, VERSION } from '../shared/version.js';
+import { openspecHome } from '../marketplace/adapters.js';
+import { isImmutableRef, snapshotGitRef } from '../shared/git-snapshot.js';
+import { ScaffoldEntrySchema } from './presets.js';
+import { PluginMinVersionSchema, ProjectConfigPatchSchema } from './schema.js';
+/** preset 仓库中每个 preset 占一个目录：`<id>/preset.yaml` 加它引用的模板文件。 */
+export const REPO_PRESET_FILE = 'preset.yaml';
+export const RepoPresetSchema = z.object({
+    schemaVersion: z.literal('openspec.team-preset.v2'),
+    id: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().optional(),
+    /** 需要的最低 OpenSpec 版本；版本号本身以仓库 tag 为准，preset 文件不再维护。 */
+    requires: z.object({ openspec: PluginMinVersionSchema }).strict().optional(),
+    marketplaces: ProjectConfigPatchSchema.shape.marketplaces,
+    plugins: ProjectConfigPatchSchema.shape.plugins,
+    configPatch: ProjectConfigPatchSchema.optional(),
+    scaffold: z.array(ScaffoldEntrySchema).optional(),
+    /** 引用时展示给项目维护者的说明与提醒 */
+    notes: z.array(z.string()).optional(),
+    warnings: z.array(z.string()).optional(),
+}).strict();
+const PresetLockSchema = z.object({
+    version: z.literal(1),
+    repo: z.string().min(1),
+    ref: z.string().min(1),
+    id: z.string().min(1),
+    resolvedSha: z.string().regex(/^[0-9a-f]{40}$/i),
+    digest: z.string().regex(/^[0-9a-f]{64}$/),
+}).strict();
+export function presetCacheRoot() {
+    return resolveInside(openspecHome(), 'presets', 'preset_cache_outside_home');
+}
+/** 缓存按仓库与提交区分；目录名带仓库地址摘要，避免同名仓库互相覆盖。锁里不存本机路径，成员之间可共享。 */
+export function presetCacheDir(repo, resolvedSha) {
+    const base = (repo.split(/[/:]/).pop() ?? 'preset').replace(/\.git$/, '') || 'preset';
+    const key = `${base}-${sha256(repo).slice(0, 12)}`;
+    assertPathToken(key, 'preset repo');
+    assertPathToken(resolvedSha, 'preset revision');
+    return resolveInside(presetCacheRoot(), path.join(key, resolvedSha), 'preset_cache_outside_home');
+}
+export function presetLockPath(projectRoot) {
+    return resolveInside(projectRoot, 'openspec/preset-lock.json', 'preset_lock_outside_project');
+}
+export function readPresetLock(projectRoot) {
+    const file = presetLockPath(projectRoot);
+    if (!exists(file))
+        return null;
+    const parsed = PresetLockSchema.safeParse(readJson(file));
+    if (!parsed.success)
+        throw new AppError('invalid_preset_lock', 'preset 锁不合法', parsed.error.issues);
+    return parsed.data;
+}
+export function writePresetLock(projectRoot, lock) {
+    writeJson(presetLockPath(projectRoot), PresetLockSchema.parse(lock));
+}
+/** 拉取仓库在不可变 ref 上的快照；所有读取 preset 仓库的命令都经过这里，ref 在此统一校验。 */
+export function fetchPresetRepo(repo, ref) {
+    if (!isImmutableRef(ref))
+        throw new AppError('mutable_preset_ref', `preset ref 必须是完整 Git SHA 或 refs/tags/<tag>: ${ref}`);
+    return snapshotGitRef({
+        repo, ref, label: 'preset', cacheRoot: presetCacheRoot(), cacheDir: (sha) => presetCacheDir(repo, sha),
+    });
+}
+/** 读取快照中的一个 preset，并检查它要求的 OpenSpec 版本。 */
+export function readRepoPreset(root, id) {
+    assertPathToken(id, 'preset id');
+    const file = resolveInside(root, path.posix.join(id, REPO_PRESET_FILE), 'preset_path_outside_repo');
+    if (!exists(file))
+        throw new AppError('preset_not_in_repo', `preset 仓库中没有 ${id}（缺少 ${id}/${REPO_PRESET_FILE}）`);
+    let raw;
+    try {
+        raw = parseYaml(readText(file));
+    }
+    catch (error) {
+        throw new AppError('invalid_preset', `preset ${id} 无法解析`, error instanceof Error ? error.message : String(error));
+    }
+    const parsed = RepoPresetSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new AppError('invalid_preset', `preset ${id} 不合法`, parsed.error.issues);
+    if (parsed.data.id !== id)
+        throw new AppError('invalid_preset', `preset 目录 ${id} 与声明的 id ${parsed.data.id} 不一致`);
+    const required = parsed.data.requires?.openspec;
+    if (required && (compareVersions(VERSION, required) ?? -1) < 0) {
+        throw new AppError('preset_requires_newer_openspec', `preset ${id} 需要 OpenSpec ${required} 或更高，当前 ${VERSION}`);
+    }
+    return parsed.data;
+}
+export function presetBaseline(preset) {
+    return {
+        id: preset.id,
+        patch: {
+            ...preset.configPatch,
+            ...(preset.marketplaces ? { marketplaces: preset.marketplaces } : {}),
+            ...(preset.plugins ? { plugins: preset.plugins } : {}),
+        },
+    };
+}
+/**
+ * 项目引用的 preset 快照目录：锁必须与配置引用一致，缓存必须存在且摘要与锁相同。
+ * 运行时只读缓存、不联网；缺失时提示用 init 补齐。
+ */
+export function presetRootForProject(projectRoot, reference) {
+    const lock = readPresetLock(projectRoot);
+    if (!lock) {
+        throw new AppError('preset_not_locked', `项目引用了 preset ${reference.id} 但没有 preset 锁；运行 openspec preset use ${reference.id} --repo <repo> --ref <ref>`);
+    }
+    if (lock.repo !== reference.repo || lock.ref !== reference.ref || lock.id !== reference.id) {
+        throw new AppError('preset_lock_mismatch', `config 引用的 preset 与 preset 锁不一致（锁为 ${lock.id}@${lock.ref}）；运行 openspec init 重新锁定`);
+    }
+    const root = presetCacheDir(lock.repo, lock.resolvedSha);
+    if (!exists(root)) {
+        throw new AppError('preset_cache_missing', `preset 缓存不存在: ${lock.id}@${lock.resolvedSha.slice(0, 12)}；运行 openspec init 拉取`);
+    }
+    if (digestDirectory(root) !== lock.digest) {
+        throw new AppError('preset_digest_mismatch', `preset 缓存内容与锁不一致: ${lock.id}@${lock.resolvedSha.slice(0, 12)}；删除该缓存后运行 openspec init 重新拉取`);
+    }
+    return { root, lock };
+}
+/** loadConfig 使用的基线：未引用 preset 时为 undefined。 */
+export function loadPresetBaseline(projectRoot, layer) {
+    if (!layer.preset)
+        return undefined;
+    const { root } = presetRootForProject(projectRoot, layer.preset);
+    return presetBaseline(readRepoPreset(root, layer.preset.id));
+}
+/**
+ * init 用：让缓存与锁对齐。锁与配置一致时，已缓存则不联网、按锁核对摘要（成员离线也能 init），
+ * 未缓存则按锁里的 SHA 补拉并核对，保证成员拿到同一份内容；没有锁或锁已过期时按配置 ref 重新解析并写锁。
+ */
+export function syncPresetCache(projectRoot, reference) {
+    const lock = readPresetLock(projectRoot);
+    if (lock && lock.repo === reference.repo && lock.ref === reference.ref && lock.id === reference.id) {
+        if (!exists(presetCacheDir(lock.repo, lock.resolvedSha))) {
+            const snapshot = fetchPresetRepo(lock.repo, lock.resolvedSha);
+            if (snapshot.digest !== lock.digest) {
+                throw new AppError('preset_digest_mismatch', `拉取到的 preset 内容与锁不一致: ${lock.id}@${lock.resolvedSha.slice(0, 12)}`);
+            }
+        }
+        readRepoPreset(presetRootForProject(projectRoot, reference).root, lock.id);
+        return lock;
+    }
+    const snapshot = fetchPresetRepo(reference.repo, reference.ref);
+    readRepoPreset(snapshot.cachePath, reference.id);
+    const next = { version: 1, ...reference, resolvedSha: snapshot.resolvedSha, digest: snapshot.digest };
+    writePresetLock(projectRoot, next);
+    return next;
+}
+/** doctor 用：不抛错，返回检查结果。 */
+export function inspectPreset(projectRoot, reference) {
+    const base = { id: reference.id, repo: reference.repo, ref: reference.ref };
+    try {
+        const { root, lock } = presetRootForProject(projectRoot, reference);
+        readRepoPreset(root, reference.id);
+        return { ...base, ok: true, resolvedSha: lock.resolvedSha, digest: lock.digest };
+    }
+    catch (error) {
+        if (!(error instanceof AppError))
+            throw error;
+        return { ...base, ok: false, code: error.code, message: error.message };
+    }
+}
+/** 列出快照中的全部 preset：每个含 preset.yaml 的顶层目录一项，按 id 排序。 */
+export function listRepoPresets(root) {
+    return listDirs(root)
+        .filter((id) => !id.startsWith('.') && exists(path.join(root, id, REPO_PRESET_FILE)))
+        .sort()
+        .map((id) => {
+        const preset = readRepoPreset(root, id);
+        return { id, title: preset.title, ...(preset.description ? { description: preset.description } : {}) };
+    });
+}
+//# sourceMappingURL=preset-repo.js.map

package/dist/config/preset-use.d.ts

@@ -0,0 +1,79 @@
+import { diffBaselines, type ScaffoldResult } from './presets.js';
+import { type ProjectConfig } from './schema.js';
+/**
+ * 让项目引用 preset 仓库中的一个 preset：拉取并锁定快照，写入引用，确认合成后的生效配置合法，再生成模板文件。
+ * 任何一步失败都按原字节还原 config 与锁。
+ */
+export declare function usePreset(input: {
+    projectRoot: string;
+    id: string;
+    repo: string;
+    ref: string;
+}): {
+    id: string;
+    repo: string;
+    ref: string;
+    resolvedSha: string;
+    digest: string;
+    scaffold: ScaffoldResult[];
+    notes: string[];
+    warnings: string[];
+};
+/**
+ * 把项目引用的 preset 升级到新 ref：列出基线的新增、修改与删除；按升级前后的生效配置，
+ * 生效值不变的条目即被项目层遮住（覆盖、禁用或更高的插件最低版本），单独列出。
+ * 只改 config 中的 ref 值并更新锁，确认生效配置合法后补齐新模板。任何一步失败都按原字节还原 config 与锁。
+ */
+export declare function upgradePreset(input: {
+    projectRoot: string;
+    ref: string;
+    allowActiveChanges?: boolean;
+}): {
+    id: string;
+    status: 'upgraded' | 'unchanged';
+    from: {
+        ref: string;
+        resolvedSha: string;
+    };
+    to: {
+        ref: string;
+        resolvedSha: string;
+    };
+    changes: ReturnType<typeof diffBaselines>;
+    shadowed: Array<{
+        section: string;
+        id: string;
+    }>;
+    scaffold: ScaffoldResult[];
+};
+/**
+ * 把拷贝式配置迁移为“引用 preset + 项目层”。迁移前后生效配置必须逐项一致（唯一例外：preset 提高的插件最低版本，
+ * 在结果中列出），否则中止且不写任何文件；
+ * 写入时替换 config（原注释不保留）、写新锁并删除旧的 preset-lock.yaml。dryRun 只返回结果。
+ */
+export declare function migratePreset(input: {
+    projectRoot: string;
+    id: string;
+    repo: string;
+    ref: string;
+    dryRun?: boolean;
+}): {
+    id: string;
+    ref: string;
+    resolvedSha: string;
+    written: boolean;
+    removedLegacyLock: boolean;
+    layer: ProjectConfig;
+    inherited: {
+        taskCategories: string[];
+        hooks: string[];
+        plugins: string[];
+        marketplaces: string[];
+    };
+    raisedMinVersions: Array<{
+        plugin: string;
+        from?: string;
+        to: string;
+    }>;
+};
+//# sourceMappingURL=preset-use.d.ts.map