kontexted 0.1.12 → 0.1.13

package/dist/lib/sync/types.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Type definitions for the sync feature
+ * @packageDocumentation
+ */
+/**
+ * Sync configuration stored in .sync/config.json
+ */
+export interface SyncConfig {
+    /** Workspace slug being synced */
+    workspaceSlug: string;
+    /** Profile alias used for authentication */
+    alias: string;
+    /** Server URL */
+    serverUrl: string;
+    /** Sync mode */
+    syncMode: "auto" | "manual";
+    /** Conflict resolution strategy */
+    conflictStrategy: "newer-wins" | "local-wins" | "remote-wins";
+    /** Timestamp when sync was initialized */
+    initializedAt: string;
+    /** Daemon process ID (null if not running) */
+    daemonPid: number | null;
+    /** Sync directory path (relative to project root) */
+    syncDir: string;
+}
+/**
+ * File sync state stored in .sync/state.json
+ */
+export interface SyncState {
+    /** Per-file sync state */
+    files: Record<string, FileSyncState>;
+    /** Per-folder sync state */
+    folders: Record<string, FolderSyncState>;
+    /** Last full sync timestamp */
+    lastFullSync: string | null;
+    /** Sync version (for future migrations) */
+    version: number;
+}
+/**
+ * State for a single file
+ */
+export interface FileSyncState {
+    /** Content hash (SHA-256) of local file */
+    localHash: string | null;
+    /** Content hash (SHA-256) of remote note */
+    remoteHash: string | null;
+    /** Local file modification time */
+    localMtime: string | null;
+    /** Remote note updatedAt timestamp */
+    remoteMtime: string | null;
+    /** Last successful sync timestamp */
+    lastSync: string | null;
+    /** Remote note publicId */
+    publicId: string;
+    /** Remote note internal id */
+    noteId: number;
+    /** Folder path (relative to .kontexted/) */
+    folderPath: string | null;
+}
+/**
+ * State for a single folder
+ */
+export interface FolderSyncState {
+    /** Local folder modification time */
+    localMtime: string | null;
+    /** Remote folder updatedAt timestamp */
+    remoteMtime: string | null;
+    /** Last successful sync timestamp */
+    lastSync: string | null;
+    /** Remote folder publicId */
+    publicId: string;
+    /** Remote folder internal id */
+    folderId: number;
+    /** Folder path (relative to sync directory) */
+    folderPath: string;
+}
+/**
+ * Pending change in the queue (SQLite)
+ */
+export interface PendingChange {
+    id: number;
+    /** Relative file path */
+    filePath: string;
+    /** Change type */
+    type: "create" | "update" | "delete";
+    /** Content (null for delete) */
+    content: string | null;
+    /** When the change was detected */
+    detectedAt: string;
+    /** Number of retry attempts */
+    retryCount: number;
+    /** Last error message (if any) */
+    lastError: string | null;
+}
+/**
+ * Conflict log entry
+ */
+export interface ConflictLogEntry {
+    timestamp: string;
+    filePath: string;
+    winner: "local" | "remote";
+    loserPath: string;
+    localMtime: string;
+    remoteMtime: string;
+}
+/**
+ * Remote note representation for sync
+ */
+export interface RemoteNote {
+    id: number;
+    publicId: string;
+    name: string;
+    title: string;
+    content: string;
+    folderId: number | null;
+    folderPath: string | null;
+    updatedAt: string;
+}
+/**
+ * Sync status response
+ */
+export interface SyncStatus {
+    status: "running" | "stopped" | "paused" | "error";
+    workspaceSlug: string;
+    filesSynced: number;
+    pendingChanges: number;
+    conflicts: number;
+    lastSync: string | null;
+    uptime: number | null;
+    error: string | null;
+}
+/**
+ * File change event from watcher
+ */
+export interface FileChangeEvent {
+    /** Type of change detected */
+    type: "create" | "update" | "delete";
+    /** Absolute file path */
+    filePath: string;
+    /** Relative path from sync directory */
+    relativePath: string;
+}
+/**
+ * Folder change event from watcher
+ */
+export interface FolderChangeEvent {
+    /** Type of change detected */
+    type: "create" | "delete";
+    /** Relative folder path */
+    folderPath: string;
+    /** Absolute folder path */
+    absolutePath: string;
+}
+/**
+ * Remote change event from SSE
+ */
+export interface RemoteChangeEvent {
+    /** Type of remote change */
+    type: "create" | "update" | "delete";
+    /** The remote note (for create/update) */
+    note?: RemoteNote;
+    /** The public ID of the note (for delete) */
+    publicId?: string;
+}
+/**
+ * Remote folder change event from SSE
+ */
+export interface RemoteFolderChangeEvent {
+    /** Type of remote folder change */
+    type: "folder.create" | "folder.delete" | "folder.update";
+    /** The remote folder (for create/update) */
+    folder?: RemoteFolder;
+    /** The public ID of the folder (for delete) */
+    publicId?: string;
+}
+/**
+ * Deleted note information from pull response
+ */
+export interface DeletedNoteInfo {
+    /** Public ID of the deleted note */
+    publicId: string;
+    /** When the note was deleted */
+    deletedAt: string;
+}
+/**
+ * Remote folder representation
+ */
+export interface RemoteFolder {
+    /** Internal folder ID */
+    id: number;
+    /** Public folder ID */
+    publicId: string;
+    /** Folder name (slug) */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Parent folder ID */
+    parentId: number | null;
+    /** Folder path (relative to workspace root) */
+    folderPath: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Whether the folder is empty */
+    isEmpty?: boolean;
+}
+/**
+ * Response from /api/sync/pull
+ */
+export interface SyncPullResponse {
+    /** Notes that have been created or updated since the requested timestamp */
+    notes: RemoteNote[];
+    /** Notes that have been deleted since the requested timestamp */
+    deleted: DeletedNoteInfo[];
+    /** Folders that have been created or updated */
+    folders: RemoteFolder[];
+    /** Server timestamp for the next sync request */
+    syncTimestamp: string;
+}
+/**
+ * Individual change in push request
+ */
+export type SyncPushChange = SyncPushChangeCreate | SyncPushChangeUpdate | SyncPushChangeDelete | SyncPushChangeFolderCreate | SyncPushChangeFolderDelete;
+/**
+ * Create change payload
+ */
+export interface SyncPushChangeCreate {
+    /** Change type */
+    type: "create";
+    /** Temporary ID for correlating request with response */
+    tempId: string;
+    /** Note name (slug) */
+    name: string;
+    /** Note title */
+    title: string;
+    /** Note content (Markdown) */
+    content: string;
+    /** Target folder path */
+    folderPath: string | null;
+}
+/**
+ * Update change payload
+ */
+export interface SyncPushChangeUpdate {
+    /** Change type */
+    type: "update";
+    /** Public ID of the note to update */
+    publicId: string;
+    /** Note name (slug) */
+    name: string;
+    /** Note title */
+    title: string;
+    /** Note content (Markdown) */
+    content: string;
+    /** Target folder path */
+    folderPath: string | null;
+    /** Expected last modification time for conflict detection */
+    expectedMtime: string;
+}
+/**
+ * Delete change payload
+ */
+export interface SyncPushChangeDelete {
+    /** Change type */
+    type: "delete";
+    /** Public ID of the note to delete */
+    publicId: string;
+}
+/**
+ * Folder create change payload
+ */
+export interface SyncPushChangeFolderCreate {
+    /** Change type */
+    type: "folder.create";
+    /** Folder name (slug) */
+    name: string;
+    /** Parent folder path (null for root) */
+    parentPath: string | null;
+}
+/**
+ * Folder delete change payload
+ */
+export interface SyncPushChangeFolderDelete {
+    /** Change type */
+    type: "folder.delete";
+    /** Public ID of the folder to delete */
+    publicId: string;
+}
+/**
+ * Request to /api/sync/push
+ */
+export interface SyncPushRequest {
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** List of changes to push */
+    changes: SyncPushChange[];
+}
+/**
+ * Accepted change result
+ */
+export interface SyncPushAccepted {
+    /** Public ID of the note */
+    publicId: string;
+    /** Status of the operation */
+    status: "updated";
+}
+/**
+ * Created note result
+ */
+export interface SyncPushCreated {
+    /** Temporary ID from request (for correlation) */
+    tempId: string;
+    /** Public ID of the newly created note */
+    publicId: string;
+    /** Status of the operation */
+    status: "created";
+}
+/**
+ * Conflict information
+ */
+export interface SyncPushConflict {
+    /** Public ID of the conflicting note */
+    publicId: string;
+    /** Reason for conflict */
+    reason: "remote_modified";
+    /** Remote note's last modification time */
+    remoteMtime: string;
+    /** Expected modification time sent in request */
+    expectedMtime: string;
+}
+/**
+ * Push error information
+ */
+export interface SyncPushError {
+    /** Public ID of the note that failed */
+    publicId: string;
+    /** Error message */
+    error: string;
+}
+/**
+ * Response from /api/sync/push
+ */
+export interface SyncPushResponse {
+    /** Successfully updated notes */
+    accepted: SyncPushAccepted[];
+    /** Successfully created notes */
+    created: SyncPushCreated[];
+    /** Conflicts that need resolution */
+    conflicts: SyncPushConflict[];
+    /** Errors that occurred during processing */
+    errors: SyncPushError[];
+}

package/dist/lib/sync/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for the sync feature
+ * @packageDocumentation
+ */
+export {};

package/dist/lib/sync/utils.d.ts

@@ -0,0 +1,51 @@
+import type { RemoteNote } from "./types.js";
+/**
+ * Update .gitignore to exclude the sync directory.
+ * Also creates a .ignore file with negation pattern for grep compatibility.
+ *
+ * @param syncDir - The sync directory name to exclude (e.g., ".kontexted-sync")
+ */
+export declare function updateGitignore(syncDir: string): Promise<void>;
+/**
+ * Parse markdown content to extract title and body.
+ * Checks for frontmatter first, then falls back to H1 heading.
+ *
+ * @param content - The markdown content to parse
+ * @returns Object containing extracted title and remaining body content
+ */
+export declare function parseMarkdown(content: string): {
+    title: string;
+    body: string;
+};
+/**
+ * Format a remote note as markdown.
+ * Adds title as H1 if not already present in content.
+ *
+ * @param note - The remote note to format
+ * @returns Markdown-formatted string with title as H1
+ */
+export declare function formatMarkdown(note: RemoteNote): string;
+/**
+ * Ensure a directory exists, creating it recursively if necessary.
+ *
+ * @param filePath - The file path whose directory should exist
+ */
+export declare function ensureDirectoryExists(filePath: string): Promise<void>;
+/**
+ * Compute the relative file path for a note.
+ * Uses the note's name with .md extension and folder path if present.
+ *
+ * @param note - The remote note to compute path for
+ * @returns Relative file path (e.g., "folder/subfolder/note.md")
+ */
+export declare function computeFilePath(note: RemoteNote): string;
+/**
+ * Execute a function with exponential backoff retry.
+ *
+ * @param fn - The async function to execute
+ * @param maxRetries - Maximum number of retry attempts (default: 3)
+ * @param baseDelay - Base delay in milliseconds (default: 1000)
+ * @returns Promise that resolves with the function's result
+ * @throws Last error if all retries are exhausted
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;

package/dist/lib/sync/utils.js

@@ -0,0 +1,126 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * Update .gitignore to exclude the sync directory.
+ * Also creates a .ignore file with negation pattern for grep compatibility.
+ *
+ * @param syncDir - The sync directory name to exclude (e.g., ".kontexted-sync")
+ */
+export async function updateGitignore(syncDir) {
+    const gitignorePath = join(process.cwd(), ".gitignore");
+    let content = "";
+    try {
+        content = await readFile(gitignorePath, "utf-8");
+    }
+    catch {
+        // File doesn't exist
+    }
+    if (!content.includes(`${syncDir}/`)) {
+        content += `\n# Kontexted sync\n${syncDir}/\n`;
+        await writeFile(gitignorePath, content, "utf-8");
+    }
+    // Create .ignore for grep compatibility
+    const ignorePath = join(process.cwd(), ".ignore");
+    let ignoreContent = "";
+    try {
+        ignoreContent = await readFile(ignorePath, "utf-8");
+    }
+    catch {
+        // File doesn't exist
+    }
+    if (!ignoreContent.includes(`!${syncDir}/`)) {
+        ignoreContent += `\n!${syncDir}/\n`;
+        await writeFile(ignorePath, ignoreContent, "utf-8");
+    }
+}
+/**
+ * Parse markdown content to extract title and body.
+ * Checks for frontmatter first, then falls back to H1 heading.
+ *
+ * @param content - The markdown content to parse
+ * @returns Object containing extracted title and remaining body content
+ */
+export function parseMarkdown(content) {
+    // Check for frontmatter
+    if (content.startsWith("---\n")) {
+        const endIndex = content.indexOf("\n---\n", 4);
+        if (endIndex !== -1) {
+            const frontmatter = content.slice(4, endIndex);
+            const body = content.slice(endIndex + 5);
+            const titleMatch = frontmatter.match(/title:\s*(.+)/);
+            return {
+                title: titleMatch?.[1]?.trim() ?? "",
+                body
+            };
+        }
+    }
+    // Check for H1 title
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    return {
+        title: h1Match?.[1]?.trim() ?? "",
+        body: content
+    };
+}
+/**
+ * Format a remote note as markdown.
+ * Adds title as H1 if not already present in content.
+ *
+ * @param note - The remote note to format
+ * @returns Markdown-formatted string with title as H1
+ */
+export function formatMarkdown(note) {
+    // Handle case where content is undefined (from some SSE events)
+    const content = note.content ?? "";
+    // If content starts with H1 matching title, keep as-is
+    if (content.startsWith(`# ${note.title}`)) {
+        return content;
+    }
+    // Otherwise, add title as H1
+    return `# ${note.title}\n\n${content}`;
+}
+/**
+ * Ensure a directory exists, creating it recursively if necessary.
+ *
+ * @param filePath - The file path whose directory should exist
+ */
+export async function ensureDirectoryExists(filePath) {
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true });
+}
+/**
+ * Compute the relative file path for a note.
+ * Uses the note's name with .md extension and folder path if present.
+ *
+ * @param note - The remote note to compute path for
+ * @returns Relative file path (e.g., "folder/subfolder/note.md")
+ */
+export function computeFilePath(note) {
+    const fileName = `${note.name}.md`;
+    if (note.folderPath) {
+        return join(note.folderPath, fileName);
+    }
+    return fileName;
+}
+/**
+ * Execute a function with exponential backoff retry.
+ *
+ * @param fn - The async function to execute
+ * @param maxRetries - Maximum number of retry attempts (default: 3)
+ * @param baseDelay - Base delay in milliseconds (default: 1000)
+ * @returns Promise that resolves with the function's result
+ * @throws Last error if all retries are exhausted
+ */
+export async function withRetry(fn, maxRetries = 3, baseDelay = 1000) {
+    let lastError = null;
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            const delay = baseDelay * Math.pow(2, i);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kontexted",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "CLI tool for Kontexted - MCP proxy, workspaces management, and local server",
   "type": "module",
   "bin": {
@@ -30,21 +30,24 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
+    "chokidar": "^5.0.0",
     "commander": "^12.1.0",
+    "eventsource": "^4.1.0",
     "yargs": "^17.7.2",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/yargs": "^17.0.35",
+    "bun-types": "^1.3.9",
     "tsc-alias": "^1.8.10",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "@kontexted/darwin-arm64": "0.1.12",
-    "@kontexted/linux-x64": "0.1.12",
-    "@kontexted/windows-x64": "0.1.12"
+    "@kontexted/darwin-arm64": "0.1.13",
+    "@kontexted/linux-x64": "0.1.13",
+    "@kontexted/windows-x64": "0.1.13"
   }
 }