@hashicorp/kits 0.1.0

package/dist/adapters/base-adapter.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Base adapter class providing common functionality for harness adapters.
+ *
+ * This abstract class implements shared logic that all harness-specific adapters
+ * can use, reducing code duplication and ensuring consistent behavior across
+ * different AI agent harnesses.
+ */
+import type { PrimitiveType, KitManifest, ResolvedPrimitive, InstallationScope, ResolvedEnvVar, ResolvedHeader, EnvVarOutput, HeaderOutput, EnvVarResolutionResult } from "../core/types.js";
+import type { KitAdapter, InstallationPaths, ConfigLocations, DetectionResult, CompatibilityResult, InstallOptions, InstallResult, UninstallOptions, UninstallResult, InstalledKitInfo, TransformResult, HookInstallation, HookInstallationInput, ValidationResult, ToolMapping, ModelMapping, TemplateProcessingResult, FileOperationResult } from "./types.js";
+import type { CommandMetadata, SkillMetadata, SubagentMetadata, McpServerConfig } from "../core/types.js";
+import { type CompletedOperation } from "./file-operations.js";
+/**
+ * Namespace separator for primitive names.
+ */
+export declare const NAMESPACE_SEPARATOR = ".";
+/**
+ * Abstract base class for kit adapters.
+ *
+ * Subclasses must implement abstract methods for harness-specific behavior
+ * while inheriting common functionality from this base class.
+ */
+export declare abstract class BaseAdapter implements KitAdapter {
+    /**
+     * Adapter name (e.g., "claude-code").
+     */
+    abstract readonly name: string;
+    /**
+     * Human-readable display name (e.g., "Claude Code").
+     */
+    abstract readonly displayName: string;
+    /**
+     * Adapter implementation version.
+     */
+    abstract readonly version: string;
+    /**
+     * Supported harness version range (semver).
+     */
+    abstract readonly supportedHarnessVersions: string;
+    /**
+     * Get the installation scopes supported by this harness.
+     *
+     * Most harnesses support both global and project scopes.
+     */
+    abstract getSupportedScopes(): InstallationScope[];
+    /**
+     * Get the primitive types supported by this harness.
+     *
+     * @param scope - Installation scope (defaults to "global")
+     */
+    abstract getSupportedPrimitives(scope?: InstallationScope): PrimitiveType[];
+    /**
+     * Get the installation paths for file-based primitives.
+     *
+     * @param scope - Installation scope (defaults to "global")
+     */
+    abstract getInstallationPaths(scope?: InstallationScope): InstallationPaths;
+    /**
+     * Get the configuration file locations.
+     *
+     * @param scope - Installation scope (defaults to "global")
+     */
+    abstract getConfigLocations(scope?: InstallationScope): ConfigLocations;
+    /**
+     * Get the tool mapping for this harness.
+     */
+    abstract getToolMapping(): ToolMapping;
+    /**
+     * Get the model mapping for this harness.
+     */
+    abstract getModelMapping(): ModelMapping;
+    /**
+     * Filter subagent frontmatter for this harness.
+     */
+    protected filterSubagentFrontmatter(frontmatter: Record<string, unknown>, _metadata: SubagentMetadata): Record<string, unknown>;
+    /**
+     * Resolve canonical subagent hook bindings to harness-specific format.
+     */
+    protected mapSubagentHooks(frontmatter: Record<string, unknown>, _resolvedPrimitives: ResolvedPrimitive[], _kitName: string, _paths: InstallationPaths, _scope: InstallationScope, _projectRoot?: string): Record<string, unknown>;
+    /**
+     * Detect if the harness is installed on the system.
+     */
+    abstract detect(): Promise<DetectionResult>;
+    /**
+     * Transform a command for this harness.
+     */
+    abstract transformCommand(content: string, metadata: CommandMetadata): TransformResult;
+    /**
+     * Transform a skill for this harness.
+     */
+    abstract transformSkill(skillDir: string, metadata: SkillMetadata): TransformResult;
+    /**
+     * Transform a subagent for this harness.
+     */
+    abstract transformSubagent(content: string, metadata: SubagentMetadata): TransformResult;
+    /**
+     * Transform an MCP server configuration for this harness.
+     */
+    abstract transformMcpServer(config: McpServerConfig): Record<string, unknown>;
+    /**
+     * Transform a hook for this harness.
+     */
+    abstract transformHook(hook: HookInstallationInput): HookInstallation;
+    /**
+     * Transform resolved environment variables to harness-native format.
+     *
+     * Called during MCP server installation. Each harness has specific
+     * syntax for passthrough (runtime resolution) vs direct values.
+     *
+     * See PRD-001 FR-20 for harness-specific transformation rules.
+     */
+    abstract transformEnvVars(resolved: ResolvedEnvVar[]): EnvVarOutput;
+    /**
+     * Transform resolved HTTP headers to harness-native format.
+     *
+     * Called during HTTP transport MCP server installation. Each harness
+     * has specific handling for authentication headers vs other headers.
+     *
+     * See PRD-001 FR-21 for harness-specific transformation rules.
+     */
+    abstract transformHeaders(resolved: ResolvedHeader[]): HeaderOutput;
+    /**
+     * Filter skill frontmatter for this harness.
+     *
+     * Default behavior preserves all fields.
+     */
+    protected filterSkillFrontmatter(frontmatter: Record<string, unknown>, _metadata: SkillMetadata): Record<string, unknown>;
+    /**
+     * Resolve canonical skill hook bindings to harness-specific format.
+     */
+    protected mapSkillHooks(frontmatter: Record<string, unknown>, _resolvedPrimitives: ResolvedPrimitive[], _kitName: string, _paths: InstallationPaths, _scope: InstallationScope, _projectRoot?: string): Record<string, unknown>;
+    /**
+     * Check if a kit is compatible with this harness at the given scope.
+     *
+     * @param kit - Kit manifest to check
+     * @param scope - Installation scope (defaults to "global")
+     */
+    checkCompatibility(kit: KitManifest, scope?: InstallationScope): CompatibilityResult;
+    /**
+     * Get a namespaced primitive name.
+     *
+     * Format: {kitName}.{primitiveName}
+     */
+    getNamespacedName(kitName: string, primitiveName: string): string;
+    /**
+     * Parse a namespaced name into kit and primitive components.
+     */
+    parseNamespacedName(namespacedName: string): {
+        kitName: string;
+        primitiveName: string;
+    };
+    /**
+     * Process tool templates in content.
+     */
+    processToolTemplates(content: string): TemplateProcessingResult;
+    /**
+     * Validate a kit against this harness's requirements.
+     */
+    validate(kit: KitManifest): ValidationResult;
+    /**
+     * Install a kit to this harness.
+     */
+    install(kit: KitManifest, resolvedPrimitives: ResolvedPrimitive[], options: InstallOptions): Promise<InstallResult>;
+    /**
+     * Install a single primitive.
+     *
+     * Subclasses may override for harness-specific behavior.
+     *
+     * @param kitName - Name of the kit being installed
+     * @param primitive - Resolved primitive to install
+     * @param resolvedPrimitives - All resolved primitives for the kit
+     * @param paths - Installation paths for the scope
+     * @param dryRun - If true, don't actually write files
+     * @param completedOps - Array to track completed operations for rollback
+     * @param scope - Installation scope
+     * @param projectRoot - Project root for project scope
+     */
+    protected installPrimitive(kitName: string, primitive: ResolvedPrimitive, resolvedPrimitives: ResolvedPrimitive[], paths: InstallationPaths, dryRun: boolean, completedOps: CompletedOperation[], scope?: InstallationScope, projectRoot?: string): Promise<{
+        destination: string;
+        existed: boolean;
+        operations: FileOperationResult[];
+    }>;
+    /**
+     * Update harness configuration (MCP servers, hooks config).
+     *
+     * Subclasses should override for harness-specific config handling.
+     *
+     * @param kit - Kit manifest
+     * @param resolvedPrimitives - Resolved primitives to install
+     * @param dryRun - If true, don't actually write files
+     * @param completedOps - Array to track completed operations for rollback
+     * @param scope - Installation scope
+     * @param projectRoot - Project root for project scope
+     */
+    protected updateConfiguration(_kit: KitManifest, _resolvedPrimitives: ResolvedPrimitive[], _dryRun: boolean, _completedOps: CompletedOperation[], _scope?: InstallationScope, _projectRoot?: string, _envResolutions?: EnvVarResolutionResult[]): Promise<{
+        operations: FileOperationResult[];
+    }>;
+    /**
+     * Uninstall a kit from this harness.
+     *
+     * @param kitName - Name of the kit to uninstall
+     * @param options - Uninstall options including scope
+     */
+    uninstall(kitName: string, options: UninstallOptions): Promise<UninstallResult>;
+    /**
+     * List installed kits.
+     *
+     * Subclasses should implement this based on how they track installations.
+     * The default implementation scans installation directories for namespaced files.
+     *
+     * @param scope - Installation scope (defaults to "global")
+     */
+    list(scope?: InstallationScope): Promise<InstalledKitInfo[]>;
+    /**
+     * Scan a directory for primitives and add to kit map.
+     */
+    private scanDirectoryForPrimitives;
+    /**
+     * Get the file extension for a primitive type.
+     */
+    protected getFileExtension(primitiveType: PrimitiveType): string;
+    /**
+     * Get the destination path for a primitive.
+     *
+     * @param primitiveType - Type of primitive
+     * @param namespacedName - Namespaced name of the primitive
+     * @param scope - Installation scope (defaults to "global")
+     * @param projectRoot - Project root for project scope
+     */
+    protected getDestinationPath(primitiveType: PrimitiveType, namespacedName: string, scope?: InstallationScope, projectRoot?: string): string;
+}
+//# sourceMappingURL=base-adapter.d.ts.map

package/dist/adapters/base-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/base-adapter.ts"],"names":[],"mappings":"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"}