@hashicorp/kits 0.1.0

package/dist/adapters/file-operations.d.ts

@@ -0,0 +1,164 @@
+/**
+ * File operation utilities for adapter implementations.
+ *
+ * This module provides atomic file operations with rollback support
+ * for installing primitives into AI agent harnesses.
+ */
+import type { FileOperationResult, FileOperation } from "./types.js";
+/**
+ * A completed operation that can be rolled back.
+ */
+export interface CompletedOperation {
+    type: "file" | "directory" | "backup";
+    path: string;
+    previousContent?: string;
+    createdNew: boolean;
+}
+/**
+ * Result of an atomic file operation batch.
+ */
+export interface AtomicOperationResult {
+    success: boolean;
+    results: FileOperationResult[];
+    completedOps: CompletedOperation[];
+    error?: string;
+}
+/**
+ * Expand ~ to the user's home directory.
+ *
+ * @param filePath - Path that may contain ~
+ */
+export declare function expandPath(filePath: string): string;
+/**
+ * Check if a path exists.
+ *
+ * @param filePath - Path to check (supports ~)
+ */
+export declare function pathExists(filePath: string): boolean;
+/**
+ * Check if a path is a directory.
+ *
+ * @param filePath - Path to check
+ */
+export declare function isDirectory(filePath: string): Promise<boolean>;
+/**
+ * Check if a path is a file.
+ *
+ * @param filePath - Path to check
+ */
+export declare function isFile(filePath: string): Promise<boolean>;
+/**
+ * Ensure a directory exists, creating it if necessary.
+ *
+ * @param dirPath - Directory path to ensure (supports ~)
+ * @returns true if directory was created, false if it already existed
+ */
+export declare function ensureDirectory(dirPath: string): Promise<boolean>;
+/**
+ * Copy a single file.
+ *
+ * @param source - Source file path
+ * @param destination - Destination file path (supports ~)
+ * @param overwrite - Whether to overwrite existing files (default: true)
+ */
+export declare function copyFile(source: string, destination: string, overwrite?: boolean): Promise<void>;
+/**
+ * Copy a directory recursively.
+ *
+ * Used for skills which are directories containing SKILL.md and assets.
+ *
+ * @param source - Source directory path
+ * @param destination - Destination directory path (supports ~)
+ * @param overwrite - Whether to overwrite existing files (default: true)
+ */
+export declare function copyDirectory(source: string, destination: string, overwrite?: boolean): Promise<void>;
+/**
+ * Write transformed content to a file.
+ *
+ * @param destination - Destination file path (supports ~)
+ * @param content - Content to write
+ * @param encoding - File encoding (default: utf-8)
+ */
+export declare function writeTransformed(destination: string, content: string, encoding?: BufferEncoding): Promise<void>;
+/**
+ * Read file content.
+ *
+ * @param filePath - File path to read (supports ~)
+ * @param encoding - File encoding (default: utf-8)
+ */
+export declare function readFile(filePath: string, encoding?: BufferEncoding): Promise<string>;
+/**
+ * Create a timestamped backup of a file.
+ *
+ * @param filePath - File to backup (supports ~)
+ * @returns The backup file path, or undefined if file didn't exist
+ */
+export declare function backupFile(filePath: string): Promise<string | undefined>;
+/**
+ * Create a simple backup (with .backup extension).
+ *
+ * @param filePath - File to backup (supports ~)
+ * @returns The backup file path, or undefined if file didn't exist
+ */
+export declare function createSimpleBackup(filePath: string): Promise<string | undefined>;
+/**
+ * Restore a file from backup.
+ *
+ * @param backupPath - Path to backup file
+ * @param originalPath - Original file path to restore to
+ */
+export declare function restoreFromBackup(backupPath: string, originalPath: string): Promise<void>;
+/**
+ * Remove a file or directory.
+ *
+ * @param filePath - Path to remove (supports ~)
+ */
+export declare function remove(filePath: string): Promise<void>;
+/**
+ * Remove a directory if it's empty.
+ *
+ * @param dirPath - Directory path (supports ~)
+ * @returns true if directory was removed, false if not empty or didn't exist
+ */
+export declare function removeIfEmpty(dirPath: string): Promise<boolean>;
+/**
+ * Rollback a list of completed operations.
+ *
+ * Operations are rolled back in reverse order.
+ *
+ * @param completedOps - Operations to roll back
+ */
+export declare function rollbackOperations(completedOps: CompletedOperation[]): Promise<void>;
+/**
+ * Execute a list of file operations atomically.
+ *
+ * All operations succeed or all are rolled back.
+ *
+ * @param operations - Operations to execute
+ * @param options - Execution options
+ */
+export declare function executeFileOperations(operations: FileOperation[], options?: {
+    createDirs?: boolean;
+    backup?: boolean;
+}): Promise<AtomicOperationResult>;
+/**
+ * Deep merge two objects.
+ *
+ * @param target - Target object
+ * @param source - Source object to merge in
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;
+/**
+ * Get the size of a file or directory in bytes.
+ *
+ * @param filePath - Path to measure (supports ~)
+ */
+export declare function getSize(filePath: string): Promise<number>;
+/**
+ * List all files in a directory recursively.
+ *
+ * @param dirPath - Directory to list (supports ~)
+ * @param pattern - Optional glob pattern to filter files
+ */
+export declare function listFiles(dirPath: string): Promise<string[]>;
+//# sourceMappingURL=file-operations.d.ts.map

package/dist/adapters/file-operations.d.ts.map

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

package/dist/adapters/file-operations.js

@@ -0,0 +1,526 @@
+/**
+ * File operation utilities for adapter implementations.
+ *
+ * This module provides atomic file operations with rollback support
+ * for installing primitives into AI agent harnesses.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+/**
+ * Expand ~ to the user's home directory.
+ *
+ * @param filePath - Path that may contain ~
+ */
+export function expandPath(filePath) {
+    if (!filePath)
+        return filePath;
+    if (filePath === "~") {
+        return os.homedir();
+    }
+    if (filePath.startsWith("~/")) {
+        return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
+}
+/**
+ * Check if a path exists.
+ *
+ * @param filePath - Path to check (supports ~)
+ */
+export function pathExists(filePath) {
+    return existsSync(expandPath(filePath));
+}
+/**
+ * Check if a path is a directory.
+ *
+ * @param filePath - Path to check
+ */
+export async function isDirectory(filePath) {
+    try {
+        const stats = await fs.stat(expandPath(filePath));
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a path is a file.
+ *
+ * @param filePath - Path to check
+ */
+export async function isFile(filePath) {
+    try {
+        const stats = await fs.stat(expandPath(filePath));
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure a directory exists, creating it if necessary.
+ *
+ * @param dirPath - Directory path to ensure (supports ~)
+ * @returns true if directory was created, false if it already existed
+ */
+export async function ensureDirectory(dirPath) {
+    const expanded = expandPath(dirPath);
+    const existed = existsSync(expanded);
+    if (!existed) {
+        await fs.mkdir(expanded, { recursive: true });
+        return true;
+    }
+    return false;
+}
+/**
+ * Copy a single file.
+ *
+ * @param source - Source file path
+ * @param destination - Destination file path (supports ~)
+ * @param overwrite - Whether to overwrite existing files (default: true)
+ */
+export async function copyFile(source, destination, overwrite = true) {
+    const expandedDest = expandPath(destination);
+    // Ensure destination directory exists
+    await ensureDirectory(path.dirname(expandedDest));
+    // Check if destination exists and overwrite is false
+    if (!overwrite && existsSync(expandedDest)) {
+        throw new Error(`destination already exists; path=${expandedDest}`);
+    }
+    await fs.copyFile(source, expandedDest);
+}
+/**
+ * Copy a directory recursively.
+ *
+ * Used for skills which are directories containing SKILL.md and assets.
+ *
+ * @param source - Source directory path
+ * @param destination - Destination directory path (supports ~)
+ * @param overwrite - Whether to overwrite existing files (default: true)
+ */
+export async function copyDirectory(source, destination, overwrite = true) {
+    const expandedDest = expandPath(destination);
+    // Ensure destination directory exists
+    await ensureDirectory(expandedDest);
+    // Get all entries in source directory
+    const entries = await fs.readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(source, entry.name);
+        const destPath = path.join(expandedDest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(srcPath, destPath, overwrite);
+        }
+        else {
+            if (!overwrite && existsSync(destPath)) {
+                continue; // Skip existing files if not overwriting
+            }
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Write transformed content to a file.
+ *
+ * @param destination - Destination file path (supports ~)
+ * @param content - Content to write
+ * @param encoding - File encoding (default: utf-8)
+ */
+export async function writeTransformed(destination, content, encoding = "utf-8") {
+    const expandedDest = expandPath(destination);
+    // Ensure destination directory exists
+    await ensureDirectory(path.dirname(expandedDest));
+    await fs.writeFile(expandedDest, content, { encoding });
+}
+/**
+ * Read file content.
+ *
+ * @param filePath - File path to read (supports ~)
+ * @param encoding - File encoding (default: utf-8)
+ */
+export async function readFile(filePath, encoding = "utf-8") {
+    const expanded = expandPath(filePath);
+    return fs.readFile(expanded, { encoding });
+}
+/**
+ * Create a timestamped backup of a file.
+ *
+ * @param filePath - File to backup (supports ~)
+ * @returns The backup file path, or undefined if file didn't exist
+ */
+export async function backupFile(filePath) {
+    const expanded = expandPath(filePath);
+    if (!existsSync(expanded)) {
+        return undefined;
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = `${expanded}.backup.${timestamp}`;
+    await fs.copyFile(expanded, backupPath);
+    return backupPath;
+}
+/**
+ * Create a simple backup (with .backup extension).
+ *
+ * @param filePath - File to backup (supports ~)
+ * @returns The backup file path, or undefined if file didn't exist
+ */
+export async function createSimpleBackup(filePath) {
+    const expanded = expandPath(filePath);
+    if (!existsSync(expanded)) {
+        return undefined;
+    }
+    const backupPath = `${expanded}.backup`;
+    // If backup already exists, remove it
+    if (existsSync(backupPath)) {
+        await fs.rm(backupPath, { recursive: true, force: true });
+    }
+    const stats = await fs.stat(expanded);
+    if (stats.isDirectory()) {
+        await copyDirectory(expanded, backupPath);
+    }
+    else {
+        await fs.copyFile(expanded, backupPath);
+    }
+    return backupPath;
+}
+/**
+ * Restore a file from backup.
+ *
+ * @param backupPath - Path to backup file
+ * @param originalPath - Original file path to restore to
+ */
+export async function restoreFromBackup(backupPath, originalPath) {
+    const expandedBackup = expandPath(backupPath);
+    const expandedOriginal = expandPath(originalPath);
+    if (!existsSync(expandedBackup)) {
+        throw new Error(`backup not found; path=${expandedBackup}`);
+    }
+    const stats = await fs.stat(expandedBackup);
+    if (stats.isDirectory()) {
+        // Remove original directory if exists
+        if (existsSync(expandedOriginal)) {
+            await fs.rm(expandedOriginal, { recursive: true, force: true });
+        }
+        await copyDirectory(expandedBackup, expandedOriginal);
+    }
+    else {
+        await fs.copyFile(expandedBackup, expandedOriginal);
+    }
+}
+/**
+ * Remove a file or directory.
+ *
+ * @param filePath - Path to remove (supports ~)
+ */
+export async function remove(filePath) {
+    const expanded = expandPath(filePath);
+    if (!existsSync(expanded)) {
+        return; // Already doesn't exist
+    }
+    await fs.rm(expanded, { recursive: true, force: true });
+}
+/**
+ * Remove a directory if it's empty.
+ *
+ * @param dirPath - Directory path (supports ~)
+ * @returns true if directory was removed, false if not empty or didn't exist
+ */
+export async function removeIfEmpty(dirPath) {
+    const expanded = expandPath(dirPath);
+    if (!existsSync(expanded)) {
+        return false;
+    }
+    try {
+        const entries = await fs.readdir(expanded);
+        if (entries.length === 0) {
+            await fs.rmdir(expanded);
+            return true;
+        }
+    }
+    catch {
+        // Ignore errors (e.g., not a directory)
+    }
+    return false;
+}
+/**
+ * Rollback a list of completed operations.
+ *
+ * Operations are rolled back in reverse order.
+ *
+ * @param completedOps - Operations to roll back
+ */
+export async function rollbackOperations(completedOps) {
+    // Rollback in reverse order
+    for (const op of completedOps.reverse()) {
+        try {
+            switch (op.type) {
+                case "file":
+                    if (op.createdNew) {
+                        // File was newly created - remove it
+                        await remove(op.path);
+                    }
+                    else if (op.previousContent !== undefined) {
+                        // File was modified - restore previous content
+                        await writeTransformed(op.path, op.previousContent);
+                    }
+                    break;
+                case "directory":
+                    if (op.createdNew) {
+                        // Directory was newly created - remove if empty
+                        await removeIfEmpty(op.path);
+                    }
+                    break;
+                case "backup":
+                    {
+                        // Restore from backup
+                        const originalPath = op.path.replace(/\.backup(\.[^.]+)?$/, "");
+                        await restoreFromBackup(op.path, originalPath);
+                    }
+                    break;
+            }
+        }
+        catch (error) {
+            // Log but continue rollback
+            console.error(`rollback failed for ${op.path}; error=${error}`);
+        }
+    }
+}
+/**
+ * Execute a list of file operations atomically.
+ *
+ * All operations succeed or all are rolled back.
+ *
+ * @param operations - Operations to execute
+ * @param options - Execution options
+ */
+export async function executeFileOperations(operations, options = {}) {
+    const { createDirs = true, backup = true } = options;
+    const results = [];
+    const completedOps = [];
+    try {
+        for (const op of operations) {
+            const expandedDest = expandPath(op.destination);
+            // Create parent directories if needed
+            if (createDirs && op.type !== "mkdir") {
+                const dirPath = path.dirname(expandedDest);
+                const created = await ensureDirectory(dirPath);
+                if (created) {
+                    completedOps.push({
+                        type: "directory",
+                        path: dirPath,
+                        createdNew: true,
+                    });
+                }
+            }
+            switch (op.type) {
+                case "copy": {
+                    if (!op.source) {
+                        throw new Error("copy operation requires source");
+                    }
+                    // Backup existing file if needed
+                    const fileExisted = existsSync(expandedDest);
+                    let previousContent;
+                    if (backup && fileExisted) {
+                        previousContent = await readFile(expandedDest);
+                    }
+                    await copyFile(op.source, expandedDest);
+                    const completedOp = {
+                        type: "file",
+                        path: expandedDest,
+                        createdNew: !fileExisted,
+                    };
+                    if (previousContent !== undefined) {
+                        completedOp.previousContent = previousContent;
+                    }
+                    completedOps.push(completedOp);
+                    results.push({
+                        operation: "copy",
+                        source: op.source,
+                        destination: expandedDest,
+                        success: true,
+                    });
+                    break;
+                }
+                case "transform": {
+                    if (!op.source || !op.transform) {
+                        throw new Error("transform operation requires source and transform function");
+                    }
+                    // Backup existing file if needed
+                    const fileExisted = existsSync(expandedDest);
+                    let previousContent;
+                    if (backup && fileExisted) {
+                        previousContent = await readFile(expandedDest);
+                    }
+                    // Read source, transform, and write
+                    const sourceContent = await readFile(op.source);
+                    const transformedContent = op.transform(sourceContent);
+                    await writeTransformed(expandedDest, transformedContent);
+                    const completedOp = {
+                        type: "file",
+                        path: expandedDest,
+                        createdNew: !fileExisted,
+                    };
+                    if (previousContent !== undefined) {
+                        completedOp.previousContent = previousContent;
+                    }
+                    completedOps.push(completedOp);
+                    results.push({
+                        operation: "transform",
+                        source: op.source,
+                        destination: expandedDest,
+                        success: true,
+                    });
+                    break;
+                }
+                case "mkdir": {
+                    const created = await ensureDirectory(expandedDest);
+                    completedOps.push({
+                        type: "directory",
+                        path: expandedDest,
+                        createdNew: created,
+                    });
+                    results.push({
+                        operation: "mkdir",
+                        destination: expandedDest,
+                        success: true,
+                    });
+                    break;
+                }
+                case "merge": {
+                    // Merge operations are typically handled by config merging
+                    // For now, treat as a copy with merge strategy
+                    if (!op.source) {
+                        throw new Error("merge operation requires source");
+                    }
+                    const fileExisted = existsSync(expandedDest);
+                    let previousContent;
+                    if (fileExisted) {
+                        previousContent = await readFile(expandedDest);
+                        if (op.mergeStrategy === "deep-merge") {
+                            // Deep merge JSON/YAML files
+                            const existingContent = JSON.parse(previousContent);
+                            const newContent = JSON.parse(await readFile(op.source));
+                            const merged = deepMerge(existingContent, newContent);
+                            await writeTransformed(expandedDest, JSON.stringify(merged, null, 2));
+                        }
+                        else {
+                            // Replace strategy - just copy
+                            await copyFile(op.source, expandedDest);
+                        }
+                    }
+                    else {
+                        await copyFile(op.source, expandedDest);
+                    }
+                    const completedOp = {
+                        type: "file",
+                        path: expandedDest,
+                        createdNew: !fileExisted,
+                    };
+                    if (previousContent !== undefined) {
+                        completedOp.previousContent = previousContent;
+                    }
+                    completedOps.push(completedOp);
+                    results.push({
+                        operation: "merge",
+                        source: op.source,
+                        destination: expandedDest,
+                        success: true,
+                    });
+                    break;
+                }
+            }
+        }
+        return {
+            success: true,
+            results,
+            completedOps,
+        };
+    }
+    catch (error) {
+        // Rollback all completed operations
+        await rollbackOperations(completedOps);
+        return {
+            success: false,
+            results,
+            completedOps: [],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Deep merge two objects.
+ *
+ * @param target - Target object
+ * @param source - Source object to merge in
+ */
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sourceValue = source[key];
+        const targetValue = result[key];
+        if (sourceValue &&
+            typeof sourceValue === "object" &&
+            !Array.isArray(sourceValue) &&
+            targetValue &&
+            typeof targetValue === "object" &&
+            !Array.isArray(targetValue)) {
+            // Recursively merge objects
+            result[key] = deepMerge(targetValue, sourceValue);
+        }
+        else {
+            // Override with source value
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}
+/**
+ * Get the size of a file or directory in bytes.
+ *
+ * @param filePath - Path to measure (supports ~)
+ */
+export async function getSize(filePath) {
+    const expanded = expandPath(filePath);
+    const stats = await fs.stat(expanded);
+    if (stats.isFile()) {
+        return stats.size;
+    }
+    if (stats.isDirectory()) {
+        let totalSize = 0;
+        const entries = await fs.readdir(expanded, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(expanded, entry.name);
+            totalSize += await getSize(entryPath);
+        }
+        return totalSize;
+    }
+    return 0;
+}
+/**
+ * List all files in a directory recursively.
+ *
+ * @param dirPath - Directory to list (supports ~)
+ * @param pattern - Optional glob pattern to filter files
+ */
+export async function listFiles(dirPath) {
+    const expanded = expandPath(dirPath);
+    const files = [];
+    if (!existsSync(expanded)) {
+        return files;
+    }
+    const entries = await fs.readdir(expanded, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path.join(expanded, entry.name);
+        if (entry.isDirectory()) {
+            const subFiles = await listFiles(entryPath);
+            files.push(...subFiles);
+        }
+        else {
+            files.push(entryPath);
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=file-operations.js.map