kontexted 0.1.12 → 0.1.14

package/README.md

@@ -1,6 +1,6 @@
 # Kontexted CLI
 
-A command-line tool for Kontexted that provides MCP proxy functionality and workspace management.
+The official CLI for Kontexted—provides **Disk Sync**, MCP proxy, server management, and workspace operations for AI-assisted development.
 
 ## Installation
 
@@ -8,68 +8,217 @@ A command-line tool for Kontexted that provides MCP proxy functionality and work
 npm install -g kontexted
 ```
 
-## Usage
+## Overview
 
-### Authentication
+Kontexted provides three ways for AI assistants to access your notes:
 
-Log in to a Kontexted server:
+| Method | Best For | Setup Difficulty |
+|--------|----------|------------------|
+| **Disk Sync** | Direct file access, all AI tools | ★☆☆ Easy |
+| **MCP Server** | Claude Desktop, MCP-compatible tools | ★★☆ Medium |
+| **CLI Skills** | Scripted operations, custom workflows | ★★★ Advanced |
 
-```bash
-kontexted login --url https://app.example.com --workspace my-workspace --alias prod
-```
+---
 
-With an alias and write permissions:
+## Disk Sync (Recommended)
+
+Sync your Kontexted workspace to disk as markdown files. This is the **recommended method** for AI coding agents to access your notes.
+
+### Quick Start
 
 ```bash
-kontexted login --url https://app.example.com --workspace my-workspace --alias prod --write
+# In your project directory
+kontexted sync init --alias my-workspace --dir .
+kontexted sync start --daemon
 ```
 
-### MCP Proxy Mode
+Your notes are now available at `.kontexted/folder/note.md`
+
+### How It Works
+
+- Notes sync to `.kontexted/` as markdown files
+- Real-time bidirectional sync with file watching
+- Directory is gitignored; `.ignore` file allows AI tools to reference files
+- Works with opencode, Claude Code, Cursor, Windsurf, and any AI that reads files
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `sync init --alias <name> --dir .` | Initialize sync in current directory |
+| `sync start --daemon` | Start background sync with file watching |
+| `sync start --foreground` | Start sync in foreground |
+| `sync stop` | Stop sync daemon |
+| `sync status` | Check sync status |
+| `sync force-pull` | Pull all notes from server |
+| `sync force-push` | Push all local changes to server |
+| `sync conflicts list` | List sync conflicts |
+| `sync conflicts show <id>` | Show conflict details |
+| `sync conflicts resolve <id> --strategy <local\|remote>` | Resolve conflict |
+| `sync reset` | Reset sync state |
+
+---
+
+## MCP Proxy
 
-Start the MCP proxy server (for use with Claude Desktop or other MCP clients):
+Start the MCP proxy server for Claude Desktop or other MCP clients:
 
 ```bash
-# Using alias
-kontexted --alias prod
+# Read-only mode
+kontexted mcp --alias <name>
 
-# Using workspace name
-kontexted --workspace my-workspace
+# With write access
+kontexted mcp --alias <name> --write
+```
+
+### Configuring Claude Desktop
 
-# Enable write mode for this session
-kontexted --alias prod --write
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-# Disable write mode for this session
-kontexted --alias prod --write-off
+```json
+{
+  "mcpServers": {
+    "kontexted": {
+      "command": "kontexted",
+      "args": ["mcp", "--alias", "my-workspace", "--write"]
+    }
+  }
+}
 ```
 
-### Manage Profiles
+---
+
+## Server Management
 
-Show stored profiles:
+Run a local Kontexted server:
 
 ```bash
-kontexted show-config
+# Initialize local server (first time)
+kontexted server init
+
+# Start server in background
+kontexted server start
+
+# Start server in foreground
+kontexted server start --foreground
+
+# Stop server
+kontexted server stop
+
+# Check status
+kontexted server status
+
+# View logs
+kontexted server logs -f
+
+# Display signup invite code
+kontexted server show-invite
+
+# Diagnose issues
+kontexted server doctor
 ```
 
-Remove a profile:
+### Default Configuration
+
+| Setting | Default |
+|---------|---------|
+| Database | SQLite (`~/.kontexted/data/kontexted.db`) |
+| Port | `4729` |
+| Config | `~/.kontexted/config.json` |
+
+---
+
+## CLI Skills
+
+Direct CLI access for workspace operations:
 
 ```bash
-kontexted logout --alias prod
+# Query workspace tree
+kontexted skill workspace-tree --alias <name>
+
+# Search notes
+kontexted skill search-notes --alias <name> --query "search text" --limit 10
+
+# Get note by ID
+kontexted skill note-by-id --alias <name> --note-id <id>
+
+# Create folder (requires --write login)
+kontexted skill create-folder --alias <name> --name <slug> --display-name "Name"
+
+# Create note (requires --write login)
+kontexted skill create-note --alias <name> --name <slug> --title "Title"
+
+# Update note content (requires --write login)
+kontexted skill update-note-content --alias <name> --note-id <id> --content "Content"
 ```
 
-Remove all profiles:
+---
+
+## Authentication
 
 ```bash
+# Login to a server
+kontexted login --url https://app.example.com --workspace my-workspace --alias prod
+
+# Login with write permissions
+kontexted login --url https://app.example.com --workspace my-workspace --alias prod --write
+
+# Show stored profiles
+kontexted show-config
+
+# Remove a profile
+kontexted logout --alias prod
+
+# Remove all profiles
 kontexted logout
 ```
 
+---
+
+## Command Reference
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Sync** | `sync init` | Initialize disk sync |
+| | `sync start` | Start sync daemon |
+| | `sync stop` | Stop sync daemon |
+| | `sync status` | Check status |
+| | `sync force-pull` | Force pull from server |
+| | `sync force-push` | Force push to server |
+| | `sync conflicts list` | List conflicts |
+| | `sync reset` | Reset sync state |
+| **Server** | `server init` | Initialize local server |
+| | `server start` | Start server |
+| | `server stop` | Stop server |
+| | `server status` | Check server status |
+| | `server logs` | View logs |
+| | `server show-invite` | Display invite code |
+| | `server doctor` | Diagnose issues |
+| **Auth** | `login` | Authenticate to server |
+| | `logout` | Remove stored profile |
+| | `show-config` | Display configuration |
+| **MCP** | `mcp` | Start MCP proxy |
+| **Skills** | `skill workspace-tree` | Get folder structure |
+| | `skill search-notes` | Search notes |
+| | `skill note-by-id` | Get note by ID |
+| | `skill create-folder` | Create folder |
+| | `skill create-note` | Create note |
+| | `skill update-note-content` | Update note |
+
+---
+
 ## Configuration
 
-Profiles are stored in `~/.kontexted/profile.json` with OAuth tokens.
+Profiles are stored in `~/.kontexted/config.json` with OAuth tokens.
+
+---
 
 ## Requirements
 
 - Node.js 18 or higher
 
+---
+
 ## License
 
 MIT

package/dist/commands/sync/conflicts/list.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from "commander";
+/**
+ * Handler for the sync conflicts list command
+ */
+export declare function handler(argv: {
+    json?: boolean;
+    dir?: string;
+}): Promise<void>;
+export declare const command = "list";
+export declare const desc = "List unresolved conflicts";
+export declare const builder: () => void;
+export declare function handlerYargs(argv: any): Promise<void>;
+/**
+ * Register the sync conflicts list command.
+ */
+export declare function registerConflictsListCommand(conflictsCommand: Command): void;

package/dist/commands/sync/conflicts/list.js

@@ -0,0 +1,131 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Default sync directory name
+ */
+const DEFAULT_SYNC_DIR = ".kontexted";
+/**
+ * Find the sync directory by looking for .kontexted/ or using --dir option
+ */
+async function findSyncDir(cwd, dirArg) {
+    // If --dir was provided, use it
+    if (dirArg) {
+        const syncDir = path.resolve(cwd, dirArg);
+        try {
+            await fs.access(syncDir);
+            return syncDir;
+        }
+        catch {
+            console.error(`Error: Directory not found: ${syncDir}`);
+            process.exit(1);
+        }
+    }
+    // Otherwise, look for .kontexted/ in current directory
+    const defaultSyncDir = path.join(cwd, DEFAULT_SYNC_DIR);
+    try {
+        await fs.access(defaultSyncDir);
+        return defaultSyncDir;
+    }
+    catch {
+        console.error(`Error: Sync directory not found.`);
+        console.error(`Expected to find '${DEFAULT_SYNC_DIR}/' in current directory or specify --dir option.`);
+        console.error(`Run 'kontexted sync init' first to initialize sync.`);
+        process.exit(1);
+    }
+}
+/**
+ * Read and parse conflicts.log to get all conflict entries
+ */
+async function getConflicts(syncDir) {
+    const logPath = path.join(syncDir, ".sync", "conflicts.log");
+    try {
+        const content = await fs.readFile(logPath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        return lines.map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Format timestamp for display
+ */
+function formatTimestamp(isoString) {
+    const date = new Date(isoString);
+    return date.toISOString().replace("T", " ").slice(0, 19) + " UTC";
+}
+/**
+ * Display conflicts in human-readable format
+ */
+function displayConflicts(conflicts) {
+    if (conflicts.length === 0) {
+        console.log("No conflicts found.");
+        return;
+    }
+    console.log("Conflicts:");
+    for (let i = 0; i < conflicts.length; i++) {
+        const conflict = conflicts[i];
+        const winnerText = conflict.winner === "local" ? "local wins" : "remote wins";
+        const timestamp = formatTimestamp(conflict.timestamp);
+        console.log(`  ${i + 1}. ${conflict.filePath} (${winnerText}, ${timestamp})`);
+    }
+}
+/**
+ * Display conflicts in JSON format
+ */
+function displayConflictsJson(conflicts) {
+    const output = conflicts.map((conflict, index) => ({
+        id: index + 1,
+        filePath: conflict.filePath,
+        winner: conflict.winner,
+        timestamp: conflict.timestamp,
+        localMtime: conflict.localMtime,
+        remoteMtime: conflict.remoteMtime,
+    }));
+    console.log(JSON.stringify(output, null, 2));
+}
+/**
+ * Handler for the sync conflicts list command
+ */
+export async function handler(argv) {
+    const cwd = process.cwd();
+    // Find the sync directory
+    const syncDir = await findSyncDir(cwd, argv.dir);
+    // Get conflicts
+    const conflicts = await getConflicts(syncDir);
+    // Display output
+    if (argv.json) {
+        displayConflictsJson(conflicts);
+    }
+    else {
+        displayConflicts(conflicts);
+    }
+}
+// ============ Yargs Command Module ============
+export const command = "list";
+export const desc = "List unresolved conflicts";
+export const builder = () => { };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function handlerYargs(argv) {
+    await handler({
+        json: argv.json,
+        dir: argv.dir,
+    });
+}
+// ============ Register with Commander ============
+/**
+ * Register the sync conflicts list command.
+ */
+export function registerConflictsListCommand(conflictsCommand) {
+    conflictsCommand
+        .command("list")
+        .description(desc)
+        .option("--dir <directory>", "Sync directory")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await handlerYargs({
+            json: opts.json,
+            dir: opts.dir,
+        });
+    });
+}

package/dist/commands/sync/conflicts/resolve.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+/**
+ * Handler for the sync conflicts resolve command
+ */
+export declare function handler(argv: {
+    id: string;
+    keep: "local" | "remote";
+    dir?: string;
+}): Promise<void>;
+export declare const command = "resolve";
+export declare const desc = "Manually resolve conflict";
+export declare const builder: () => void;
+export declare function handlerYargs(argv: any): Promise<void>;
+/**
+ * Register the sync conflicts resolve command.
+ */
+export declare function registerConflictsResolveCommand(conflictsCommand: Command): void;

package/dist/commands/sync/conflicts/resolve.js

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Default sync directory name
+ */
+const DEFAULT_SYNC_DIR = ".kontexted";
+/**
+ * Find the sync directory by looking for .kontexted/ or using --dir option
+ */
+async function findSyncDir(cwd, dirArg) {
+    // If --dir was provided, use it
+    if (dirArg) {
+        const syncDir = path.resolve(cwd, dirArg);
+        try {
+            await fs.access(syncDir);
+            return syncDir;
+        }
+        catch {
+            console.error(`Error: Directory not found: ${syncDir}`);
+            process.exit(1);
+        }
+    }
+    // Otherwise, look for .kontexted/ in current directory
+    const defaultSyncDir = path.join(cwd, DEFAULT_SYNC_DIR);
+    try {
+        await fs.access(defaultSyncDir);
+        return defaultSyncDir;
+    }
+    catch {
+        console.error(`Error: Sync directory not found.`);
+        console.error(`Expected to find '${DEFAULT_SYNC_DIR}/' in current directory or specify --dir option.`);
+        console.error(`Run 'kontexted sync init' first to initialize sync.`);
+        process.exit(1);
+    }
+}
+/**
+ * Read and parse conflicts.log to get all conflict entries
+ */
+async function getConflicts(syncDir) {
+    const logPath = path.join(syncDir, ".sync", "conflicts.log");
+    try {
+        const content = await fs.readFile(logPath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        return lines.map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Write conflicts back to the log file
+ */
+async function writeConflicts(syncDir, conflicts) {
+    const logPath = path.join(syncDir, ".sync", "conflicts.log");
+    const content = conflicts
+        .map((entry) => JSON.stringify(entry))
+        .join("\n");
+    await fs.writeFile(logPath, content, "utf-8");
+}
+/**
+ * Load sync state from .sync/state.json
+ */
+async function loadSyncState(syncDir) {
+    const statePath = path.join(syncDir, ".sync", "state.json");
+    try {
+        const stateRaw = await fs.readFile(statePath, "utf-8");
+        return JSON.parse(stateRaw);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Save sync state to .sync/state.json
+ */
+async function saveSyncState(syncDir, state) {
+    const statePath = path.join(syncDir, ".sync", "state.json");
+    await fs.writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+}
+/**
+ * Handler for the sync conflicts resolve command
+ */
+export async function handler(argv) {
+    const cwd = process.cwd();
+    // Find the sync directory
+    const syncDir = await findSyncDir(cwd, argv.dir);
+    // Parse the conflict ID (1-based index)
+    const conflictId = parseInt(argv.id, 10);
+    if (isNaN(conflictId) || conflictId < 1) {
+        console.error(`Error: Invalid conflict ID: ${argv.id}`);
+        process.exit(1);
+    }
+    // Get conflicts
+    const conflicts = await getConflicts(syncDir);
+    // Find the conflict by ID (convert to 0-based index)
+    const conflictIndex = conflictId - 1;
+    if (conflictIndex < 0 || conflictIndex >= conflicts.length) {
+        console.error(`Error: Conflict not found: ${argv.id}`);
+        console.error(`Total conflicts: ${conflicts.length}`);
+        process.exit(1);
+    }
+    const conflict = conflicts[conflictIndex];
+    // Resolve the conflict
+    const localFilePath = path.join(syncDir, conflict.filePath);
+    if (argv.keep === "local") {
+        // Keep local version - already in place, just remove conflict entry
+        console.log(`Resolved conflict #${conflictId}: keeping local version`);
+        console.log(`  File: ${conflict.filePath}`);
+    }
+    else {
+        // Keep remote version - copy loser (shadow) to main file
+        const loserPath = path.join(syncDir, conflict.loserPath);
+        const loserContent = await fs.readFile(loserPath, "utf-8");
+        await fs.writeFile(localFilePath, loserContent, "utf-8");
+        console.log(`Resolved conflict #${conflictId}: keeping remote version`);
+        console.log(`  File: ${conflict.filePath}`);
+        console.log(`  Copied from: ${conflict.loserPath}`);
+    }
+    // Update sync state - mark file as synced with the new hash
+    let state = await loadSyncState(syncDir);
+    if (state) {
+        // Get the new content hash
+        const newContent = await fs.readFile(localFilePath, "utf-8");
+        const newHash = await hashContent(newContent);
+        // Update the file state
+        if (state.files[conflict.filePath]) {
+            state.files[conflict.filePath].localHash = newHash;
+            state.files[conflict.filePath].remoteHash = newHash;
+            await saveSyncState(syncDir, state);
+            console.log(`  Updated sync state for ${conflict.filePath}`);
+        }
+    }
+    // Remove the conflict from the log
+    conflicts.splice(conflictIndex, 1);
+    await writeConflicts(syncDir, conflicts);
+    console.log(`  Conflict removed from conflicts.log`);
+}
+/**
+ * Simple hash function for content (SHA-256 via crypto)
+ */
+async function hashContent(content) {
+    const crypto = await import("node:crypto");
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+// ============ Yargs Command Module ============
+export const command = "resolve";
+export const desc = "Manually resolve conflict";
+export const builder = () => { };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function handlerYargs(argv) {
+    await handler({
+        id: argv.id,
+        keep: argv.keep,
+        dir: argv.dir,
+    });
+}
+// ============ Register with Commander ============
+/**
+ * Register the sync conflicts resolve command.
+ */
+export function registerConflictsResolveCommand(conflictsCommand) {
+    conflictsCommand
+        .command("resolve <id>")
+        .description(desc)
+        .requiredOption("--keep <local|remote>", "Which version to keep: 'local' or 'remote'")
+        .option("--dir <directory>", "Sync directory")
+        .action(async (id, opts) => {
+        if (!opts.keep) {
+            console.error("Error: --keep option is required");
+            console.error("Usage: kontexted sync conflicts resolve <id> --keep <local|remote>");
+            process.exit(1);
+        }
+        if (opts.keep !== "local" && opts.keep !== "remote") {
+            console.error("Error: --keep must be 'local' or 'remote'");
+            process.exit(1);
+        }
+        await handlerYargs({
+            id,
+            keep: opts.keep,
+            dir: opts.dir,
+        });
+    });
+}

package/dist/commands/sync/conflicts/show.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from "commander";
+/**
+ * Handler for the sync conflicts show command
+ */
+export declare function handler(argv: {
+    id: string;
+    dir?: string;
+}): Promise<void>;
+export declare const command = "show";
+export declare const desc = "Show details of a conflict";
+export declare const builder: () => void;
+export declare function handlerYargs(argv: any): Promise<void>;
+/**
+ * Register the sync conflicts show command.
+ */
+export declare function registerConflictsShowCommand(conflictsCommand: Command): void;