@stoneforge/quarry 1.12.0 → 1.14.0

package/dist/external-sync/providers/folder/folder-document-adapter.js

@@ -0,0 +1,261 @@
+/**
+ * Folder Document Sync Adapter
+ *
+ * Implements the DocumentSyncAdapter interface for local folder-based
+ * document synchronization. Maps between Stoneforge documents and
+ * markdown files with YAML frontmatter in a local directory tree.
+ *
+ * Uses folder-fs.ts for all filesystem operations (read, write, list).
+ *
+ * Conventions:
+ * - project = absolute folder path (base directory)
+ * - externalId = relative file path within the folder (e.g., 'notes/meeting.md')
+ * - URL format: file:///absolute/path/to/file.md
+ * - Filenames are generated from titles using slugification
+ */
+import * as path from 'node:path';
+import { readFile, writeFile, listFiles, fileExists, } from './folder-fs.js';
+// ============================================================================
+// Slugify Utility
+// ============================================================================
+/**
+ * Converts a title string into a filename-safe slug.
+ *
+ * - Lowercases the string
+ * - Replaces non-alphanumeric characters (except hyphens) with hyphens
+ * - Collapses consecutive hyphens
+ * - Trims leading/trailing hyphens
+ * - Falls back to 'untitled' for empty results
+ *
+ * @param title - The document title to slugify
+ * @returns A filename-safe slug string (without extension)
+ */
+export function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return slug || 'untitled';
+}
+// ============================================================================
+// URL Helpers
+// ============================================================================
+/**
+ * Builds a file:// URL from a base path and relative file path.
+ *
+ * @param basePath - Absolute base directory path
+ * @param relativePath - Relative file path within the base directory
+ * @returns A file:// URL string
+ */
+function buildFileUrl(basePath, relativePath) {
+    const absolutePath = path.resolve(basePath, relativePath);
+    return `file://${absolutePath}`;
+}
+// ============================================================================
+// Folder Document Adapter
+// ============================================================================
+/**
+ * DocumentSyncAdapter implementation for local folder-based sync.
+ *
+ * Maps between Stoneforge ExternalDocument and markdown files with YAML
+ * frontmatter on the local filesystem.
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new FolderDocumentAdapter();
+ * const doc = await adapter.getPage('/path/to/docs', 'notes/meeting.md');
+ * ```
+ */
+export class FolderDocumentAdapter {
+    /**
+     * Fetch a single document by its relative file path.
+     *
+     * @param project - Absolute path to the base directory
+     * @param externalId - Relative file path (e.g., 'notes/meeting.md')
+     * @returns The document as an ExternalDocument, or null if not found
+     */
+    async getPage(project, externalId) {
+        try {
+            const result = await readFile(project, externalId);
+            return {
+                externalId,
+                url: buildFileUrl(project, externalId),
+                provider: 'folder',
+                project,
+                title: extractTitle(externalId, result.content, result.frontmatter),
+                content: result.content,
+                contentType: 'markdown',
+                updatedAt: new Date(result.mtime).toISOString(),
+                raw: { frontmatter: result.frontmatter },
+            };
+        }
+        catch (err) {
+            // Return null for missing files (ENOENT)
+            if (err &&
+                typeof err === 'object' &&
+                'code' in err &&
+                err.code === 'ENOENT') {
+                return null;
+            }
+            // Re-throw other errors (permission issues, etc.)
+            throw err;
+        }
+    }
+    /**
+     * List documents modified since a given timestamp.
+     *
+     * Reads each file to extract title and content, returning full
+     * ExternalDocument objects.
+     *
+     * @param project - Absolute path to the base directory
+     * @param since - ISO 8601 timestamp; only files modified after this are returned
+     * @returns Array of ExternalDocument objects for modified files
+     */
+    async listPagesSince(project, since) {
+        const sinceMs = new Date(since).getTime();
+        const entries = await listFiles(project, { since: sinceMs });
+        const documents = [];
+        for (const entry of entries) {
+            const result = await readFile(project, entry.path);
+            documents.push({
+                externalId: entry.path,
+                url: buildFileUrl(project, entry.path),
+                provider: 'folder',
+                project,
+                title: extractTitle(entry.path, result.content, result.frontmatter),
+                content: result.content,
+                contentType: 'markdown',
+                updatedAt: new Date(entry.mtime).toISOString(),
+                raw: { frontmatter: result.frontmatter },
+            });
+        }
+        return documents;
+    }
+    /**
+     * Create a new document file in the folder.
+     *
+     * Generates a filename from the title using slugification, writes
+     * the content with frontmatter, and returns the created document.
+     *
+     * If the page has a `libraryPath`, the file is placed in the
+     * corresponding subdirectory. For example, a libraryPath of
+     * 'documentation/api' results in the file being created at
+     * 'documentation/api/my-doc.md'.
+     *
+     * @param project - Absolute path to the base directory
+     * @param page - Document input with title, content, and optional contentType
+     * @returns The created ExternalDocument
+     */
+    async createPage(project, page) {
+        const baseSlug = slugify(page.title);
+        // Determine the directory prefix from library path
+        const dirPrefix = page.libraryPath ? `${page.libraryPath}/` : '';
+        let relativePath = `${dirPrefix}${baseSlug}.md`;
+        // Check for existing file and add numeric suffix if needed
+        let counter = 2;
+        while (await fileExists(project, relativePath)) {
+            relativePath = `${dirPrefix}${baseSlug}-${counter}.md`;
+            counter++;
+        }
+        const frontmatter = {
+            'synced-at': new Date().toISOString(),
+        };
+        await writeFile(project, relativePath, page.content, frontmatter);
+        // Read back to get the actual mtime
+        const result = await readFile(project, relativePath);
+        return {
+            externalId: relativePath,
+            url: buildFileUrl(project, relativePath),
+            provider: 'folder',
+            project,
+            title: page.title,
+            content: page.content,
+            contentType: 'markdown',
+            updatedAt: new Date(result.mtime).toISOString(),
+            raw: { frontmatter: result.frontmatter },
+        };
+    }
+    /**
+     * Update an existing document file in the folder.
+     *
+     * Reads the existing file, merges the updates (preserving existing
+     * frontmatter), and writes back. Returns the updated document.
+     *
+     * @param project - Absolute path to the base directory
+     * @param externalId - Relative file path of the existing document
+     * @param updates - Partial document input with fields to update
+     * @returns The updated ExternalDocument
+     */
+    async updatePage(project, externalId, updates) {
+        // Read the existing file to preserve frontmatter and content
+        const existing = await readFile(project, externalId);
+        // Merge content: use update if provided, otherwise keep existing
+        const mergedContent = updates.content !== undefined ? updates.content : existing.content;
+        // Merge frontmatter: preserve existing, update synced-at
+        const mergedFrontmatter = {
+            ...existing.frontmatter,
+            'synced-at': new Date().toISOString(),
+        };
+        // If title is being updated, store it in frontmatter
+        if (updates.title !== undefined) {
+            mergedFrontmatter.title = updates.title;
+        }
+        await writeFile(project, externalId, mergedContent, mergedFrontmatter);
+        // Read back to get accurate mtime
+        const result = await readFile(project, externalId);
+        const title = updates.title ?? extractTitle(externalId, mergedContent, mergedFrontmatter);
+        return {
+            externalId,
+            url: buildFileUrl(project, externalId),
+            provider: 'folder',
+            project,
+            title,
+            content: mergedContent,
+            contentType: 'markdown',
+            updatedAt: new Date(result.mtime).toISOString(),
+            raw: { frontmatter: result.frontmatter },
+        };
+    }
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Extracts a document title from available sources, in priority order:
+ * 1. Frontmatter `title` field
+ * 2. First markdown heading (# Title)
+ * 3. Filename without extension
+ *
+ * @param relativePath - Relative file path for fallback
+ * @param content - Markdown content for heading extraction
+ * @param frontmatter - Parsed frontmatter for title field
+ * @returns The best available title
+ */
+function extractTitle(relativePath, content, frontmatter) {
+    // 1. Check frontmatter title
+    if (typeof frontmatter.title === 'string' &&
+        frontmatter.title.trim().length > 0) {
+        return frontmatter.title.trim();
+    }
+    // 2. Check first markdown heading
+    const headingMatch = content.match(/^#\s+(.+)$/m);
+    if (headingMatch) {
+        return headingMatch[1].trim();
+    }
+    // 3. Fall back to filename without extension
+    const basename = path.basename(relativePath, path.extname(relativePath));
+    return basename;
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Creates a new FolderDocumentAdapter instance.
+ *
+ * @returns A configured FolderDocumentAdapter
+ */
+export function createFolderDocumentAdapter() {
+    return new FolderDocumentAdapter();
+}
+//# sourceMappingURL=folder-document-adapter.js.map

package/dist/external-sync/providers/folder/folder-document-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-document-adapter.js","sourceRoot":"","sources":["../../../../src/external-sync/providers/folder/folder-document-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAQlC,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,GAGX,MAAM,gBAAgB,CAAC;AAExB,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,MAAM,IAAI,GAAG,KAAK;SACf,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAEzB,OAAO,IAAI,IAAI,UAAU,CAAC;AAC5B,CAAC;AAED,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,QAAgB,EAAE,YAAoB;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC1D,OAAO,UAAU,YAAY,EAAE,CAAC;AAClC,CAAC;AAED,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,qBAAqB;IAChC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CACX,OAAe,EACf,UAAkB;QAElB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAEnD,OAAO;gBACL,UAAU;gBACV,GAAG,EAAE,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC;gBACtC,QAAQ,EAAE,QAAQ;gBAClB,OAAO;gBACP,KAAK,EAAE,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC;gBACnE,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,WAAW,EAAE,UAAU;gBACvB,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;gBAC/C,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE;aACzC,CAAC;QACJ,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,yCAAyC;YACzC,IACE,GAAG;gBACH,OAAO,GAAG,KAAK,QAAQ;gBACvB,MAAM,IAAI,GAAG;gBACZ,GAAwB,CAAC,IAAI,KAAK,QAAQ,EAC3C,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,kDAAkD;YAClD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,cAAc,CAClB,OAAe,EACf,KAAgB;QAEhB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QAE7D,MAAM,SAAS,GAAuB,EAAE,CAAC;QACzC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,SAAS,CAAC,IAAI,CAAC;gBACb,UAAU,EAAE,KAAK,CAAC,IAAI;gBACtB,GAAG,EAAE,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC;gBACtC,QAAQ,EAAE,QAAQ;gBAClB,OAAO;gBACP,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC;gBACnE,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,WAAW,EAAE,UAAU;gBACvB,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;gBAC9C,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE;aACzC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,CACd,OAAe,EACf,IAA2B;QAE3B,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAErC,mDAAmD;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAEjE,IAAI,YAAY,GAAG,GAAG,SAAS,GAAG,QAAQ,KAAK,CAAC;QAEhD,2DAA2D;QAC3D,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,OAAO,MAAM,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC;YAC/C,YAAY,GAAG,GAAG,SAAS,GAAG,QAAQ,IAAI,OAAO,KAAK,CAAC;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,WAAW,GAAsB;YACrC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;QAEF,MAAM,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAElE,oCAAoC;QACpC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAErD,OAAO;YACL,UAAU,EAAE,YAAY;YACxB,GAAG,EAAE,YAAY,CAAC,OAAO,EAAE,YAAY,CAAC;YACxC,QAAQ,EAAE,QAAQ;YAClB,OAAO;YACP,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,UAAU;YACvB,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;YAC/C,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE;SACzC,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,UAAU,CACd,OAAe,EACf,UAAkB,EAClB,OAAuC;QAEvC,6DAA6D;QAC7D,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAErD,iEAAiE;QACjE,MAAM,aAAa,GACjB,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;QAErE,yDAAyD;QACzD,MAAM,iBAAiB,GAAsB;YAC3C,GAAG,QAAQ,CAAC,WAAW;YACvB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;QAEF,qDAAqD;QACrD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,iBAAiB,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC1C,CAAC;QAED,MAAM,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,CAAC,CAAC;QAEvE,kCAAkC;QAClC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAEnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,iBAAiB,CAAC,CAAC;QAE1F,OAAO;YACL,UAAU;YACV,GAAG,EAAE,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC;YACtC,QAAQ,EAAE,QAAQ;YAClB,OAAO;YACP,KAAK;YACL,OAAO,EAAE,aAAa;YACtB,WAAW,EAAE,UAAU;YACvB,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;YAC/C,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE;SACzC,CAAC;IACJ,CAAC;CACF;AAED,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;GAUG;AACH,SAAS,YAAY,CACnB,YAAoB,EACpB,OAAe,EACf,WAA8B;IAE9B,6BAA6B;IAC7B,IACE,OAAO,WAAW,CAAC,KAAK,KAAK,QAAQ;QACrC,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EACnC,CAAC;QACD,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IAED,kCAAkC;IAClC,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAClD,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;IAED,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IACzE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,qBAAqB,EAAE,CAAC;AACrC,CAAC"}

package/dist/external-sync/providers/folder/folder-fs.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Folder Filesystem Client
+ *
+ * Filesystem layer for the folder sync provider. Reads, writes, and lists
+ * markdown files with YAML frontmatter in a local directory tree.
+ *
+ * Follows the same API client pattern as github-api.ts — a focused,
+ * dependency-light module that handles I/O for a single provider.
+ *
+ * Uses the `yaml` package for frontmatter parsing/serialization.
+ */
+/**
+ * YAML frontmatter fields recognized by the folder sync provider.
+ * Additional fields are preserved as-is during round-trips.
+ */
+export interface FolderFrontmatter {
+    /** Stoneforge element ID linked to this file */
+    'stoneforge-id'?: string;
+    /** Document category */
+    category?: string;
+    /** Tags for classification */
+    tags?: string[];
+    /** ISO 8601 timestamp of last sync */
+    'synced-at'?: string;
+    /** Additional arbitrary frontmatter fields (preserved on round-trip) */
+    [key: string]: unknown;
+}
+/**
+ * Result of reading a markdown file with frontmatter
+ */
+export interface FolderFileReadResult {
+    /** Markdown body content (without frontmatter) */
+    readonly content: string;
+    /** Parsed YAML frontmatter (empty object if none) */
+    readonly frontmatter: FolderFrontmatter;
+    /** File modification time as Unix timestamp (milliseconds) */
+    readonly mtime: number;
+}
+/**
+ * Entry returned when listing files in a folder
+ */
+export interface FolderFileEntry {
+    /** Path relative to the base directory (forward slashes) */
+    readonly path: string;
+    /** File modification time as Unix timestamp (milliseconds) */
+    readonly mtime: number;
+}
+/**
+ * Options for listing files
+ */
+export interface ListFilesOptions {
+    /**
+     * Only return files modified after this Unix timestamp (milliseconds).
+     * Compares against the file's mtime.
+     */
+    since?: number;
+}
+/**
+ * Typed error for folder filesystem failures.
+ */
+export declare class FolderFsError extends Error {
+    /** The operation that failed */
+    readonly operation: 'read' | 'write' | 'list';
+    /** The file path involved (if applicable) */
+    readonly filePath: string | null;
+    /** The underlying system error code (e.g., 'ENOENT', 'EACCES') */
+    readonly code: string | null;
+    constructor(message: string, operation: 'read' | 'write' | 'list', filePath?: string | null, code?: string | null, cause?: Error);
+    /**
+     * Whether this error is due to a missing file or directory
+     */
+    get isNotFound(): boolean;
+    /**
+     * Whether this error is due to a permission issue
+     */
+    get isPermissionError(): boolean;
+}
+/**
+ * Type guard for FolderFsError
+ */
+export declare function isFolderFsError(error: unknown): error is FolderFsError;
+/**
+ * Parses YAML frontmatter from a markdown string.
+ *
+ * Expects the standard `---` delimited frontmatter block at the start of the file.
+ * Returns the body content and parsed frontmatter separately.
+ *
+ * @param raw - Raw file content (may or may not have frontmatter)
+ * @returns Parsed frontmatter and body content
+ */
+export declare function parseFrontmatter(raw: string): {
+    content: string;
+    frontmatter: FolderFrontmatter;
+};
+/**
+ * Serializes frontmatter and content into a markdown string with YAML front matter.
+ *
+ * @param content - Markdown body content
+ * @param frontmatter - Frontmatter key-value pairs
+ * @returns Complete file content with frontmatter block
+ */
+export declare function serializeFrontmatter(content: string, frontmatter: FolderFrontmatter): string;
+/**
+ * Reads a markdown file with YAML frontmatter from a folder.
+ *
+ * @param basePath - Absolute path to the base directory
+ * @param relativePath - Path relative to basePath (e.g., 'notes/meeting.md')
+ * @returns Parsed file content, frontmatter, and modification time
+ * @throws {FolderFsError} If the file cannot be read
+ */
+export declare function readFile(basePath: string, relativePath: string): Promise<FolderFileReadResult>;
+/**
+ * Writes a markdown file with YAML frontmatter to a folder.
+ *
+ * Writes atomically by first writing to a temporary file in the same directory,
+ * then renaming. This prevents partial writes from corrupting files.
+ *
+ * @param basePath - Absolute path to the base directory
+ * @param relativePath - Path relative to basePath (e.g., 'notes/meeting.md')
+ * @param content - Markdown body content
+ * @param frontmatter - YAML frontmatter key-value pairs
+ * @throws {FolderFsError} If the file cannot be written
+ */
+export declare function writeFile(basePath: string, relativePath: string, content: string, frontmatter: FolderFrontmatter): Promise<void>;
+/**
+ * Recursively lists all `.md` files in a directory tree.
+ *
+ * Excludes:
+ * - Dotfiles (files starting with `.`)
+ * - Files inside dot-directories (directories starting with `.`)
+ *
+ * @param basePath - Absolute path to the base directory
+ * @param options - Optional filtering (e.g., `since` timestamp)
+ * @returns Array of file entries with relative paths and modification times
+ * @throws {FolderFsError} If the directory cannot be read
+ */
+export declare function listFiles(basePath: string, options?: ListFilesOptions): Promise<FolderFileEntry[]>;
+/**
+ * Checks whether a file exists at the given relative path within a base directory.
+ *
+ * @param basePath - Absolute path to the base directory
+ * @param relativePath - Path relative to basePath (e.g., 'notes/meeting.md')
+ * @returns True if the file exists, false otherwise
+ */
+export declare function fileExists(basePath: string, relativePath: string): Promise<boolean>;
+//# sourceMappingURL=folder-fs.d.ts.map

package/dist/external-sync/providers/folder/folder-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-fs.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/folder/folder-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAC9C,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EACpC,QAAQ,GAAE,MAAM,GAAG,IAAW,EAC9B,IAAI,GAAE,MAAM,GAAG,IAAW,EAC1B,KAAK,CAAC,EAAE,KAAK;IAcf;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,iBAAiB,IAAI,OAAO,CAE/B;CACF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AASD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,iBAAiB,CAAC;CAChC,CAsDA;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,iBAAiB,GAC7B,MAAM,CAYR;AAMD;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAqC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,iBAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC,CAqB5B;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAOlB"}