@birdie_moblie/open_spec 2.1.7

package/dist/marketplace/adapters.d.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+declare const AdapterOperationSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    artifact: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    inputDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const AdapterContractSchema: z.ZodObject<{
+    id: z.ZodString;
+    capability: z.ZodString;
+    kind: z.ZodEnum<{
+        command: "command";
+        skill: "skill";
+        deferred: "deferred";
+    }>;
+    operations: z.ZodObject<{
+        collect: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            artifact: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            inputDescription: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        discovery: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            artifact: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            inputDescription: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        read: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            artifact: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            inputDescription: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        preview: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            artifact: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            inputDescription: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const HookEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"skill">;
+    stages: z.ZodArray<z.ZodEnum<{
+        parse: "parse";
+        tech: "tech";
+        plan: "plan";
+        execute: "execute";
+        verify: "verify";
+    }>>;
+    path: z.ZodString;
+    inputDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    inputDescription: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    type: z.ZodLiteral<"command">;
+    stages: z.ZodArray<z.ZodEnum<{
+        parse: "parse";
+        tech: "tech";
+        plan: "plan";
+        execute: "execute";
+        verify: "verify";
+    }>>;
+}, z.core.$strict>], "type">;
+export declare const PluginIdentitySchema: z.ZodObject<{
+    name: z.ZodString;
+    marketplace: z.ZodString;
+    resolvedSha: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+export type PluginIdentity = z.infer<typeof PluginIdentitySchema>;
+export type HookEntry = z.infer<typeof HookEntrySchema>;
+export interface ResolvedEntry<T> {
+    entry: T;
+    pluginRoot: string;
+    identity: PluginIdentity;
+}
+declare const PluginManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    extensions: z.ZodOptional<z.ZodObject<{
+        'org.openspec': z.ZodOptional<z.ZodObject<{
+            adapters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                capability: z.ZodString;
+                kind: z.ZodEnum<{
+                    command: "command";
+                    skill: "skill";
+                    deferred: "deferred";
+                }>;
+                operations: z.ZodObject<{
+                    collect: z.ZodOptional<z.ZodObject<{
+                        command: z.ZodString;
+                        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        artifact: z.ZodOptional<z.ZodString>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
+                        inputDescription: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                    discovery: z.ZodOptional<z.ZodObject<{
+                        command: z.ZodString;
+                        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        artifact: z.ZodOptional<z.ZodString>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
+                        inputDescription: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                    read: z.ZodOptional<z.ZodObject<{
+                        command: z.ZodString;
+                        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        artifact: z.ZodOptional<z.ZodString>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
+                        inputDescription: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                    preview: z.ZodOptional<z.ZodObject<{
+                        command: z.ZodString;
+                        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        artifact: z.ZodOptional<z.ZodString>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
+                        inputDescription: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>>;
+            hooks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodLiteral<"skill">;
+                stages: z.ZodArray<z.ZodEnum<{
+                    parse: "parse";
+                    tech: "tech";
+                    plan: "plan";
+                    execute: "execute";
+                    verify: "verify";
+                }>>;
+                path: z.ZodString;
+                inputDescription: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                command: z.ZodString;
+                args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                timeoutMs: z.ZodOptional<z.ZodNumber>;
+                inputDescription: z.ZodOptional<z.ZodString>;
+                id: z.ZodString;
+                type: z.ZodLiteral<"command">;
+                stages: z.ZodArray<z.ZodEnum<{
+                    parse: "parse";
+                    tech: "tech";
+                    plan: "plan";
+                    execute: "execute";
+                    verify: "verify";
+                }>>;
+            }, z.core.$strict>], "type">>>;
+        }, z.core.$strict>>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+}, z.core.$loose>;
+declare const MarketplaceLockSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    marketplaces: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodString;
+        resolvedSha: z.ZodString;
+        digest: z.ZodString;
+        cachePath: z.ZodString;
+    }, z.core.$strict>>;
+    plugins: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        marketplace: z.ZodString;
+        resolvedSha: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AdapterOperation = z.infer<typeof AdapterOperationSchema>;
+export type AdapterContract = z.infer<typeof AdapterContractSchema>;
+export type PluginManifest = z.infer<typeof PluginManifestSchema>;
+export type MarketplaceLock = z.infer<typeof MarketplaceLockSchema>;
+export declare function openspecHome(): string;
+export declare function marketplaceCacheRoot(): string;
+export declare function marketplaceCacheDir(name: string, resolvedSha?: string): string;
+export declare function marketplaceLockPath(projectRoot: string): string;
+export declare function readMarketplaceLock(projectRoot: string): MarketplaceLock;
+export declare function marketplaceRootForProject(projectRoot: string, name: string): string;
+export declare function resolveAdapter(projectRoot: string, selector: string): AdapterContract;
+export declare function resolveAdapterEntry(projectRoot: string, selector: string): ResolvedEntry<AdapterContract>;
+export declare function resolveHookEntry(projectRoot: string, selector: string): ResolvedEntry<HookEntry>;
+export declare function listCachedAdapters(projectRoot: string, marketplace: string): AdapterContract[];
+export declare function pluginExists(projectRoot: string, marketplace: string, pluginName: string): boolean;
+export declare function discoverPluginDirs(root: string): string[];
+export declare function readManifest(pluginDir: string): PluginManifest;
+export declare function parseSelector(selector: string): {
+    id: string;
+    marketplace: string;
+};
+export {};
+//# sourceMappingURL=adapters.d.ts.map

package/dist/marketplace/adapters.js

@@ -0,0 +1,203 @@
+import path from 'node:path';
+import os from 'node:os';
+import { z } from 'zod';
+import { exists, listDirs, readJson } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { assertPathToken, resolveInside } from '../shared/paths.js';
+import { HOOK_STAGES } from '../config/schema.js';
+import { digestDirectory } from '../shared/hash.js';
+const ArtifactPathSchema = z.string().min(1).refine((value) => {
+    const normalized = value.replace(/\\/g, '/');
+    return !normalized.startsWith('/') && !/^[A-Za-z]:\//.test(normalized) && !normalized.split('/').includes('..');
+}, 'adapter artifact 必须是 change 内相对路径');
+const AdapterOperationSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()).optional(),
+    artifact: ArtifactPathSchema.optional(),
+    timeoutMs: z.number().int().positive().max(3600000).optional(),
+    inputDescription: z.string().optional(),
+}).strict();
+const AdapterContractSchema = z.object({
+    id: z.string().min(1),
+    capability: z.string().min(1),
+    kind: z.enum(['command', 'skill', 'deferred']),
+    operations: z.object({
+        collect: AdapterOperationSchema.optional(),
+        discovery: AdapterOperationSchema.optional(),
+        read: AdapterOperationSchema.optional(),
+        preview: AdapterOperationSchema.optional(),
+    }).strict(),
+}).strict();
+const PluginStagesSchema = z.array(z.enum(HOOK_STAGES).exclude(['collect'])).min(1)
+    .refine((stages) => new Set(stages).size === stages.length, '插件 stages 不能重复');
+const PluginSkillPathSchema = ArtifactPathSchema.refine((value) => !/[\\\0]/.test(value) && value.endsWith('/SKILL.md'), '技能路径必须是插件内目录的 SKILL.md');
+const HookEntrySchema = z.discriminatedUnion('type', [
+    z.object({ id: z.string().min(1), type: z.literal('skill'), stages: PluginStagesSchema, path: PluginSkillPathSchema, inputDescription: z.string().optional() }).strict(),
+    AdapterOperationSchema.omit({ artifact: true }).extend({ id: z.string().min(1), type: z.literal('command'), stages: PluginStagesSchema }).strict(),
+]);
+export const PluginIdentitySchema = z.object({
+    name: z.string(), marketplace: z.string(), resolvedSha: z.string(), digest: z.string(),
+}).strict();
+const PluginManifestSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    extensions: z.object({
+        'org.openspec': z.object({ adapters: z.array(AdapterContractSchema).optional(), hooks: z.array(HookEntrySchema).optional() }).strict().optional(),
+    }).catchall(z.unknown()).optional(),
+}).passthrough();
+const MarketplaceLockSchema = z.object({
+    version: z.literal(1),
+    marketplaces: z.array(z.object({
+        name: z.string(),
+        repo: z.string().optional(),
+        ref: z.string(),
+        resolvedSha: z.string(),
+        digest: z.string(),
+        cachePath: z.string(),
+    }).strict()),
+    plugins: z.array(z.object({
+        name: z.string(),
+        marketplace: z.string(),
+        resolvedSha: z.string(),
+        digest: z.string(),
+    }).strict()),
+}).strict().superRefine((lock, ctx) => {
+    const marketplaces = new Set();
+    for (const [index, item] of lock.marketplaces.entries()) {
+        if (marketplaces.has(item.name))
+            ctx.addIssue({ code: 'custom', path: ['marketplaces', index, 'name'], message: `重复 marketplace: ${item.name}` });
+        marketplaces.add(item.name);
+    }
+    const plugins = new Set();
+    for (const [index, item] of lock.plugins.entries()) {
+        const selector = `${item.name}@${item.marketplace}`;
+        if (plugins.has(selector))
+            ctx.addIssue({ code: 'custom', path: ['plugins', index], message: `重复 plugin: ${selector}` });
+        plugins.add(selector);
+    }
+});
+export function openspecHome() {
+    const configured = process.env.OPENSPEC_HOME;
+    return configured ? path.resolve(configured) : path.join(os.homedir(), '.openspec', 'v2');
+}
+export function marketplaceCacheRoot() {
+    return resolveInside(openspecHome(), 'marketplaces', 'marketplace_cache_outside_home');
+}
+export function marketplaceCacheDir(name, resolvedSha) {
+    assertPathToken(name, 'marketplace name');
+    const root = resolveInside(marketplaceCacheRoot(), name, 'marketplace_cache_outside_home');
+    return resolvedSha ? resolveInside(root, resolvedSha, 'marketplace_cache_path_invalid') : root;
+}
+export function marketplaceLockPath(projectRoot) {
+    return resolveInside(projectRoot, 'openspec/marketplace-lock.json', 'marketplace_lock_outside_project');
+}
+export function readMarketplaceLock(projectRoot) {
+    const file = marketplaceLockPath(projectRoot);
+    if (!exists(file))
+        return { version: 1, marketplaces: [], plugins: [] };
+    const parsed = MarketplaceLockSchema.safeParse(readJson(file));
+    if (!parsed.success)
+        throw new AppError('invalid_marketplace_lock', 'marketplace lock 不合法', parsed.error.issues);
+    return parsed.data;
+}
+export function marketplaceRootForProject(projectRoot, name) {
+    const record = readMarketplaceLock(projectRoot).marketplaces.find((item) => item.name === name);
+    if (!record)
+        throw new AppError('marketplace_not_locked', `项目未锁定 marketplace: ${name}`);
+    const expected = marketplaceCacheDir(name, record.resolvedSha);
+    if (path.resolve(record.cachePath) !== path.resolve(expected)) {
+        throw new AppError('marketplace_lock_path_mismatch', `marketplace lock 路径不匹配: ${name}`);
+    }
+    if (!exists(expected))
+        throw new AppError('marketplace_cache_missing', `marketplace cache 不存在: ${name}@${record.resolvedSha}`);
+    if (digestDirectory(expected) !== record.digest) {
+        throw new AppError('marketplace_digest_mismatch', `marketplace cache digest 不匹配: ${name}@${record.resolvedSha}`);
+    }
+    return expected;
+}
+export function resolveAdapter(projectRoot, selector) {
+    return resolveAdapterEntry(projectRoot, selector).entry;
+}
+export function resolveAdapterEntry(projectRoot, selector) {
+    return resolveEntry(projectRoot, selector, 'adapters');
+}
+export function resolveHookEntry(projectRoot, selector) {
+    return resolveEntry(projectRoot, selector, 'hooks');
+}
+function resolveEntry(projectRoot, selector, kind) {
+    const { id, marketplace } = parseSelector(selector);
+    const root = marketplaceRootForProject(projectRoot, marketplace);
+    const lock = readMarketplaceLock(projectRoot);
+    const market = lock.marketplaces.find((item) => item.name === marketplace);
+    const matches = [];
+    for (const pluginRoot of discoverPluginDirs(root)) {
+        const manifest = readManifest(pluginRoot);
+        for (const entry of manifest.extensions?.['org.openspec']?.[kind] ?? []) {
+            if (entry.id !== id)
+                continue;
+            const digest = digestDirectory(pluginRoot);
+            const record = lock.plugins.find((item) => item.name === manifest.name && item.marketplace === marketplace);
+            if (record && (record.resolvedSha !== market.resolvedSha || record.digest !== digest)) {
+                throw new AppError('plugin_identity_mismatch', `plugin lock 与文件不匹配: ${manifest.name}@${marketplace}`);
+            }
+            matches.push({ entry, pluginRoot, identity: { name: manifest.name, marketplace, resolvedSha: market.resolvedSha, digest } });
+        }
+    }
+    const label = kind === 'adapters' ? 'adapter' : 'hook';
+    if (matches.length > 1)
+        throw new AppError(`${label}_conflict`, `${label} 重复: ${selector}`);
+    if (!matches[0])
+        throw new AppError(`${label}_not_installed`, `未找到 ${label} ${selector}（项目锁定 ref=${market.ref}，resolvedSha=${market.resolvedSha}）`);
+    return matches[0];
+}
+export function listCachedAdapters(projectRoot, marketplace) {
+    const root = marketplaceRootForProject(projectRoot, marketplace);
+    const adapters = [];
+    const ids = new Set();
+    for (const plugin of discoverPluginDirs(root)) {
+        for (const adapter of readManifest(plugin).extensions?.['org.openspec']?.adapters ?? []) {
+            if (ids.has(adapter.id))
+                throw new AppError('adapter_conflict', `marketplace 中存在重复 adapter: ${adapter.id}`);
+            ids.add(adapter.id);
+            adapters.push(adapter);
+        }
+    }
+    return adapters;
+}
+export function pluginExists(projectRoot, marketplace, pluginName) {
+    const root = marketplaceRootForProject(projectRoot, marketplace);
+    return discoverPluginDirs(root).some((dir) => path.basename(dir) === pluginName || readManifest(dir).name === pluginName);
+}
+export function discoverPluginDirs(root) {
+    if (!exists(root))
+        return [];
+    const pluginsRoot = exists(path.join(root, 'plugins')) ? resolveInside(root, 'plugins') : root;
+    const dirs = listDirs(pluginsRoot).map((name) => resolveInside(pluginsRoot, name, 'plugin_path_outside_marketplace'));
+    if (exists(path.join(root, 'plugin.json')))
+        dirs.unshift(root);
+    return dirs.filter((dir) => exists(path.join(dir, 'plugin.json')));
+}
+export function readManifest(pluginDir) {
+    const parsed = PluginManifestSchema.safeParse(readJson(path.join(pluginDir, 'plugin.json')));
+    if (!parsed.success)
+        throw new AppError('invalid_plugin_manifest', `plugin manifest 不合法: ${pluginDir}`, parsed.error.issues);
+    const extension = parsed.data.extensions?.['org.openspec'];
+    const ids = new Set();
+    for (const entry of [...(extension?.adapters ?? []), ...(extension?.hooks ?? [])]) {
+        if (ids.has(entry.id))
+            throw new AppError('plugin_entry_conflict', `插件重复入口: ${entry.id}`);
+        ids.add(entry.id);
+    }
+    return parsed.data;
+}
+export function parseSelector(selector) {
+    const separator = selector.lastIndexOf('@');
+    const id = separator > 0 ? selector.slice(0, separator) : '';
+    const marketplace = separator > 0 ? selector.slice(separator + 1) : '';
+    if (!id || !marketplace) {
+        throw new AppError('invalid_adapter_selector', `adapter 选择器必须是 id@marketplace，收到: ${selector}`);
+    }
+    return { id, marketplace };
+}
+//# sourceMappingURL=adapters.js.map

package/dist/marketplace/builtin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 内置 marketplace 只提供默认名称与源地址，不声明版本：ref 由宿主 config 或显式 --ref 决定，
+ * 核心代码不替宿主钉插件版本（插件发版不需要 OpenSpec 跟版）。
+ */
+export declare const BUILTIN_MARKETPLACE: {
+    readonly name: "mobile-marketplace";
+    readonly repo: "git@gitlab.bitrue.com:flutter_app/mobile_marketplace.git";
+};
+//# sourceMappingURL=builtin.d.ts.map

package/dist/marketplace/builtin.js

@@ -0,0 +1,9 @@
+/**
+ * 内置 marketplace 只提供默认名称与源地址，不声明版本：ref 由宿主 config 或显式 --ref 决定，
+ * 核心代码不替宿主钉插件版本（插件发版不需要 OpenSpec 跟版）。
+ */
+export const BUILTIN_MARKETPLACE = {
+    name: 'mobile-marketplace',
+    repo: 'git@gitlab.bitrue.com:flutter_app/mobile_marketplace.git',
+};
+//# sourceMappingURL=builtin.js.map

package/dist/marketplace/install.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export type HostId = 'claude' | 'codex' | 'cursor';
+export type InstallStatus = 'installed' | 'pending_user_action' | 'skipped_by_user' | 'failed';
+declare const InstallResultSchema: z.ZodObject<{
+    plugin: z.ZodString;
+    marketplace: z.ZodString;
+    host: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+    }>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        installed: "installed";
+        pending_user_action: "pending_user_action";
+        skipped_by_user: "skipped_by_user";
+    }>;
+    method: z.ZodEnum<{
+        ui: "ui";
+        native: "native";
+    }>;
+    digest: z.ZodString;
+    resolvedSha: z.ZodString;
+    target: z.ZodString;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type InstallResult = z.infer<typeof InstallResultSchema>;
+export declare function installPlugin(input: {
+    plugin: string;
+    marketplace: string;
+    host: HostId;
+    projectRoot: string;
+}): InstallResult;
+export declare function writeInstallReceipt(projectRoot: string, results: InstallResult[]): void;
+export declare function readInstallReceipt(projectRoot: string): InstallResult[];
+export declare function pluginFileCount(pluginDir: string): number;
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/marketplace/install.js

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { exists, listFilesRecursive, readJson, writeJson } from '../shared/fs.js';
+import { digestDirectory } from '../shared/hash.js';
+import { AppError } from '../shared/errors.js';
+import { execFile } from '../shared/exec.js';
+import { installClaudePlugin } from '../delivery/claude-install.js';
+import { assertPathToken, resolveInside } from '../shared/paths.js';
+import { discoverPluginDirs, marketplaceRootForProject, readManifest, readMarketplaceLock, } from './adapters.js';
+const InstallResultSchema = z.object({
+    plugin: z.string(),
+    marketplace: z.string(),
+    host: z.enum(['claude', 'codex', 'cursor']),
+    status: z.enum(['installed', 'pending_user_action', 'skipped_by_user', 'failed']),
+    method: z.enum(['native', 'ui']),
+    digest: z.string(),
+    resolvedSha: z.string(),
+    target: z.string(),
+    error: z.string().optional(),
+}).strict();
+const InstallReceiptSchema = z.object({
+    installedAt: z.string(),
+    results: z.array(InstallResultSchema),
+}).strict();
+export function installPlugin(input) {
+    assertPathToken(input.plugin, 'plugin name');
+    assertPathToken(input.marketplace, 'marketplace name');
+    const marketplaceRoot = marketplaceRootForProject(input.projectRoot, input.marketplace);
+    const pluginDir = findPluginDir(marketplaceRoot, input.plugin);
+    if (!pluginDir)
+        throw new AppError('plugin_not_found', `找不到插件 ${input.plugin}@${input.marketplace}`);
+    const digest = digestDirectory(pluginDir);
+    const projectLock = readMarketplaceLock(input.projectRoot);
+    const lock = projectLock.marketplaces.find((item) => item.name === input.marketplace);
+    if (!lock)
+        throw new AppError('marketplace_not_locked', `项目未锁定 marketplace: ${input.marketplace}`);
+    const pluginLock = projectLock.plugins.find((item) => item.name === input.plugin && item.marketplace === input.marketplace);
+    if (!pluginLock)
+        throw new AppError('plugin_not_locked', `插件尚未写入项目 lock: ${input.plugin}@${input.marketplace}`);
+    if (pluginLock.resolvedSha !== lock.resolvedSha || pluginLock.digest !== digest) {
+        throw new AppError('plugin_digest_mismatch', `插件与项目 lock 不匹配: ${input.plugin}@${input.marketplace}`);
+    }
+    const selector = `${input.plugin}@${input.marketplace}`;
+    if (input.host === 'cursor') {
+        return InstallResultSchema.parse({
+            plugin: input.plugin,
+            marketplace: input.marketplace,
+            host: input.host,
+            status: 'pending_user_action',
+            method: 'ui',
+            digest,
+            resolvedSha: lock.resolvedSha,
+            target: `Cursor Customize → Plugins → ${selector}`,
+        });
+    }
+    // Claude 用 local scope（.claude/settings.local.json，不入库）：marketplace 缓存路径是本机绝对路径
+    const add = input.host === 'claude'
+        ? execFile('claude', ['plugin', 'marketplace', 'add', marketplaceRoot, '--scope', 'local'], { cwd: input.projectRoot })
+        : execFile('codex', ['plugin', 'marketplace', 'add', marketplaceRoot, '--json'], { cwd: input.projectRoot });
+    if (!add.ok)
+        return failedResult(input, digest, lock.resolvedSha, selector, add.stderr || add.stdout);
+    const install = input.host === 'claude'
+        ? installClaudePlugin(input.projectRoot, selector, pluginDir)
+        : execFile('codex', ['plugin', 'add', selector, '--json'], { cwd: input.projectRoot });
+    if (!install.ok)
+        return failedResult(input, digest, lock.resolvedSha, selector, install.stderr || install.stdout);
+    return InstallResultSchema.parse({
+        plugin: input.plugin,
+        marketplace: input.marketplace,
+        host: input.host,
+        status: 'installed',
+        method: 'native',
+        digest,
+        resolvedSha: lock.resolvedSha,
+        target: selector,
+    });
+}
+function failedResult(input, digest, resolvedSha, target, error) {
+    return InstallResultSchema.parse({
+        ...input,
+        status: 'failed',
+        method: 'native',
+        digest,
+        resolvedSha,
+        target,
+        error,
+    });
+}
+function findPluginDir(root, plugin) {
+    return discoverPluginDirs(root).find((dir) => path.basename(dir) === plugin || readManifest(dir).name === plugin) ?? null;
+}
+export function writeInstallReceipt(projectRoot, results) {
+    const file = resolveInside(projectRoot, 'openspec/.runtime/plugin-installs.json', 'plugin_receipt_outside_project');
+    writeJson(file, InstallReceiptSchema.parse({ installedAt: new Date().toISOString(), results }));
+}
+export function readInstallReceipt(projectRoot) {
+    const file = resolveInside(projectRoot, 'openspec/.runtime/plugin-installs.json', 'plugin_receipt_outside_project');
+    if (!exists(file))
+        return [];
+    const parsed = InstallReceiptSchema.safeParse(readJson(file));
+    if (!parsed.success)
+        throw new AppError('invalid_plugin_install_receipt', '插件安装记录不合法', parsed.error.issues);
+    return parsed.data.results;
+}
+export function pluginFileCount(pluginDir) {
+    return listFilesRecursive(pluginDir).length;
+}
+//# sourceMappingURL=install.js.map

package/dist/marketplace/registry.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+declare const RecordSchema: z.ZodObject<{
+    name: z.ZodString;
+    repo: z.ZodOptional<z.ZodString>;
+    ref: z.ZodString;
+    resolvedSha: z.ZodString;
+    digest: z.ZodString;
+    cachePath: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+declare const StateSchema: z.ZodObject<{
+    marketplaces: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodString;
+        resolvedSha: z.ZodString;
+        digest: z.ZodString;
+        cachePath: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type MarketplaceRecord = z.infer<typeof RecordSchema>;
+export type MarketplaceState = z.infer<typeof StateSchema>;
+export interface DependencyCheck {
+    kind: 'marketplace' | 'plugin';
+    id: string;
+    ok: boolean;
+    code?: string;
+    digest?: string;
+    resolvedSha?: string;
+    /** 插件 manifest 声明的版本与宿主要求的最低版本；仅在配置了 minVersion 时出现 */
+    version?: string;
+    minVersion?: string;
+}
+/**
+ * 用户级缓存索引只是派生数据（项目 lock 才是权威入口）。
+ * 旧格式或损坏的索引不能阻塞 init：保留仍合法的记录，其余丢弃，原文件备份为 state.json.invalid-<时间戳>。
+ */
+export declare function loadMarketplaceState(): MarketplaceState;
+export declare function addMarketplace(input: {
+    projectRoot?: string;
+    name?: string;
+    repo?: string;
+    ref?: string;
+    dir?: string;
+}): MarketplaceRecord;
+export declare function listMarketplaces(projectRoot?: string): MarketplaceRecord[];
+export declare function ensurePresetMarketplaces(projectRoot: string, marketplaces: Array<{
+    name: string;
+    repo: string;
+    ref: string;
+}>): MarketplaceRecord[];
+/** 插件版本不低于宿主声明的 minVersion；manifest 缺版本或无法解析时视为不满足。 */
+export declare function pluginVersionSatisfies(version: string | undefined, minVersion: string | undefined): boolean;
+export declare function assertPluginsPresent(projectRoot: string, plugins: Array<{
+    name: string;
+    marketplace: string;
+    minVersion?: string;
+}>): string[];
+export declare function inspectMarketplaceDependencies(projectRoot: string, marketplaces: Array<{
+    name: string;
+    repo: string;
+    ref: string;
+}>, plugins: Array<{
+    name: string;
+    marketplace: string;
+    minVersion?: string;
+}>): DependencyCheck[];
+export declare function isImmutableRef(ref: string): boolean;
+export {};
+//# sourceMappingURL=registry.d.ts.map