/** * First-party plugin installer for SpecWeave. * * Installs plugins via Claude Code's native plugin system: * 1. Registers the specweave marketplace * 2. Runs `claude plugin install @specweave` * 3. Fixes hook permissions in the plugin cache * 4. Migrates legacy ~/.claude/commands// installations * * @since 1.0.279 (originally copy-based, migrated to native in 1.0.356) */ export interface CopyPluginOptions { /** Force reinstall even if hash matches lockfile */ force?: boolean; /** Override target skills directory (relative to projectRoot). Defaults to '.claude/skills'. */ targetSkillsDir?: string; } export interface CopyPluginResult { /** Existing native skills preserved before a changed installation. */ backups?: string[]; success: boolean; /** Content hash of source plugin directory */ sha: string; /** Where the plugin was installed to */ targetDir?: string; /** Error message if failed */ error?: string; /** True if skipped because hash unchanged */ skipped?: boolean; } interface LockfileSkillEntry { version: string; sha: string; tier: string; installedAt: string; source: string; } interface VskillLock { version: number; agents: string[]; skills: Record; createdAt: string; updatedAt: string; } /** Global bundled plugin hash cache filename */ export declare const GLOBAL_LOCKFILE_NAME = "plugins-lock.json"; /** * Check if the core SW plugin is installed and enabled natively in Claude Code. * * Runs `claude plugin list` and parses the output for `sw@specweave` with * enabled status. This is cross-platform and does not rely on internal file * formats that may change between Claude Code versions. * * @returns true if sw@specweave is present and enabled */ export declare function isSwPluginInstalledNatively(): boolean; /** * Compute SHA-256 content hash (first 12 hex chars) for a plugin directory. * Hashes filename + content for every readable file to detect any change. * Path separators are normalized to '/' for cross-platform consistency. */ export declare function computePluginHash(pluginDir: string): string; /** * Fix hook permissions: chmod 755 on all .sh files recursively. */ export declare function fixHookPermissions(targetDir: string): void; export interface SyncContentResult { /** Number of installPaths whose content was (re)copied. */ synced: number; /** The installPaths that were synced. */ paths: string[]; /** The manifest version the content was synced to (if resolvable). */ toVersion?: string; } /** * Force the installed plugin CONTENT to match the current package. * * Why: `claude plugin install` (which refresh-plugins wraps) records a fixed * installPath in installed_plugins.json and, on re-run after a version bump, * reports "active" WITHOUT re-copying content — so users keep stale hooks/skills. * This copies the plugin source into every recorded installPath (recreating a * wiped dir), fixes hook permissions, and refreshes the stale version label. * * Never throws — returns { synced: 0 } on any problem (missing/malformed * installed_plugins.json, plugin not in marketplace, absent source dir). * * @param pluginName Marketplace plugin name (e.g. "sw"). * @param specweaveRoot Marketplace root (contains .claude-plugin/marketplace.json + plugins/). * @param opts.homeOverride Override $HOME (for tests). */ export declare function syncNativePluginContent(pluginName: string, specweaveRoot: string, opts?: { homeOverride?: string; }): SyncContentResult; /** * Remove legacy ~/.claude/commands// installation. * * Prior to 1.0.356, SpecWeave installed plugins by manually copying files to * ~/.claude/commands// with custom flattening and filtering. This * bypassed Claude Code's native plugin system. Now that we use the native * system, the legacy directory must be removed to avoid duplicate commands. */ export declare function migrateLegacyCommandsDir(pluginName: string): boolean; /** * Read vskill.lock from a directory. */ export declare function readLockfile(dir: string): VskillLock | null; /** * Write vskill.lock to a directory. */ export declare function writeLockfile(lock: VskillLock, dir: string): void; /** * Ensure a lockfile exists, creating one if needed. */ export declare function ensureLockfile(dir: string): VskillLock; /** * Return the global lock directory (~/.specweave/), creating it if needed. * Accepts an optional homeDir override for testing. */ export declare function getGlobalLockDir(homeOverride?: string): string; /** * Read the global plugins-lock.json. */ export declare function readGlobalLockfile(homeOverride?: string): VskillLock | null; /** * Write the global plugins-lock.json. */ export declare function writeGlobalLockfile(lock: VskillLock, homeOverride?: string): void; /** * Ensure global lockfile exists, creating one if needed. */ export declare function ensureGlobalLockfile(homeOverride?: string): VskillLock; /** * Copy bundled plugin entries (source: 'local:specweave') from a project's * vskill.lock into the global ~/.specweave/plugins-lock.json. * * The project vskill.lock belongs to vskill and is usually committed, so it is * only read, never rewritten or deleted: 3.0.2 and earlier dropped entries and * fields from it. A bundled entry left there is harmless; the doctor reads * provenance from the entry, not from the file it sits in. * * - Preserves newer global entries (timestamp comparison) * - Idempotent: safe to run multiple times */ export declare function migrateBundledToGlobalLock(projectRoot: string, homeOverride?: string): { migratedCount: number; }; /** * Remove satellite plugin entries from the global lockfile. * * After consolidation, all satellite skills ship under the 'sw' plugin. * This function cleans up stale lockfile entries that reference the old * satellite plugin names. * * - Idempotent: safe to run multiple times * - Failure non-blocking: returns {migratedCount: 0} on any error * * @param _projectRoot - Unused: the project vskill.lock is vskill's file * @param homeOverride - Override home directory for testing */ export declare function migrateSatelliteToUnifiedLock(_projectRoot?: string, homeOverride?: string): { migratedCount: number; }; /** * Find the specweave package root from a start directory. * Walks up looking for package.json with name 'specweave' or '@specweave/core'. * Works for both development (source) and production (dist/) layouts. */ export declare function findSpecweaveRoot(startDir: string): string | null; /** * Install a first-party plugin via Claude Code's native plugin system. * * Steps: * 1. Compute content hash and check lockfile for changes * 2. Register the specweave marketplace with Claude CLI * 3. Install the plugin via `claude plugin install @specweave` * 4. Fix hook permissions in the native plugin cache * 5. Remove legacy ~/.claude/commands// if present * 6. Update lockfile */ export declare function installPlugin(pluginName: string, specweaveRoot: string, options?: CopyPluginOptions): CopyPluginResult; /** * @deprecated Use installPlugin() instead. Alias kept for backward compatibility. */ export declare const copyPlugin: typeof installPlugin; /** * Normalize SKILL.md frontmatter for non-Claude tools: * - Ensure `name:` field (derived from skill directory name) * - Ensure `description:` field (extracted from body if missing) * - Strip Claude-specific fields (user-invocable, allowed-tools, model, hooks, etc.) */ export declare function normalizeSkillFrontmatter(content: string, skillName: string): string; /** * Copy all skills from a specweave plugin directly into .claude/skills/. * * Instead of using `claude plugin install` (which writes to global cache), * this walks the plugin's skills/ directory and copies each SKILL.md to * the project-local `.claude/skills/{skillName}/SKILL.md`. * * @param pluginName - Name of the plugin in marketplace.json * @param specweaveRoot - Root of the specweave package * @param projectRoot - Root of the user's project (where .claude/ lives) * @param options - Installation options * @returns Installation result */ export declare function copyPluginSkillsToProject(pluginName: string, specweaveRoot: string, projectRoot: string, options?: CopyPluginOptions): CopyPluginResult; export {}; //# sourceMappingURL=plugin-copier.d.ts.map