contextloop-cli 0.1.1 → 0.2.0

package/dist/index.js

@@ -31,7 +31,10 @@ var CLIError = class extends Error {
       AUTH_EXPIRED: 2,
       PROJECT_NOT_SET: 6,
       TIMEOUT: 12,
-      FILE_TOO_LARGE: 13
+      FILE_TOO_LARGE: 13,
+      SYNC_CONFLICT: 7,
+      SYNC_PARTIAL_FAILURE: 8,
+      VALIDATION_ERROR: 5
     };
     return exitCodes[this.code] ?? 1;
   }
@@ -131,6 +134,7 @@ import * as crypto2 from "crypto";
 import * as os from "os";
 var SERVICE_NAME = "contextloop-cli";
 var CREDENTIALS_FILENAME = "credentials.enc";
+var LOCAL_CONFIG_DIR = ".contextloop";
 var KEY_API_KEY = "api-key";
 var KEY_ACCESS_TOKEN = "access-token";
 var KEY_REFRESH_TOKEN = "refresh-token";
@@ -138,13 +142,32 @@ var ENCRYPTION_ALGORITHM = "aes-256-gcm";
 var KEY_LENGTH = 32;
 var IV_LENGTH = 16;
 var AUTH_TAG_LENGTH = 16;
-function getConfigDir() {
+function getGlobalConfigDir() {
   const home = os.homedir();
   if (process.platform === "win32") {
     return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "contextloop-cli");
   }
   return path.join(process.env.XDG_CONFIG_HOME || path.join(home, ".config"), "contextloop-cli");
 }
+function findLocalConfigDir() {
+  let current = process.cwd();
+  const root = path.parse(current).root;
+  while (current !== root) {
+    const configDir = path.join(current, LOCAL_CONFIG_DIR);
+    if (fs.existsSync(configDir) && fs.statSync(configDir).isDirectory()) {
+      return configDir;
+    }
+    current = path.dirname(current);
+  }
+  return null;
+}
+function getOrCreateLocalConfigDir() {
+  const configDir = path.join(process.cwd(), LOCAL_CONFIG_DIR);
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true, mode: 448 });
+  }
+  return configDir;
+}
 function getMachineKey() {
   const machineId = `${os.hostname()}-${os.userInfo().username}-${SERVICE_NAME}`;
   return crypto2.scryptSync(machineId, "contextloop-cli-salt", KEY_LENGTH);
@@ -217,11 +240,14 @@ var KeyringBackend = class {
   }
 };
 var EncryptedFileBackend = class {
-  name = "encrypted-file";
+  name;
   configDir;
   filePath;
-  constructor() {
-    this.configDir = getConfigDir();
+  scope;
+  constructor(scope = "global", configDir) {
+    this.scope = scope;
+    this.name = scope === "local" ? "encrypted-file-local" : "encrypted-file";
+    this.configDir = configDir ?? getGlobalConfigDir();
     this.filePath = path.join(this.configDir, CREDENTIALS_FILENAME);
   }
   readStore() {
@@ -281,10 +307,16 @@ async function getBackend() {
   backendInitialized = true;
   return activeBackend;
 }
-async function storeApiKey(apiKey) {
+async function storeApiKey(apiKey, local = false) {
   try {
-    const backend = await getBackend();
-    await backend.set(KEY_API_KEY, apiKey);
+    if (local) {
+      const configDir = getOrCreateLocalConfigDir();
+      const backend = new EncryptedFileBackend("local", configDir);
+      await backend.set(KEY_API_KEY, apiKey);
+    } else {
+      const backend = await getBackend();
+      await backend.set(KEY_API_KEY, apiKey);
+    }
   } catch (error) {
     throw new CLIError(
       "KEYCHAIN_ERROR",
@@ -292,20 +324,44 @@ async function storeApiKey(apiKey) {
     );
   }
 }
-async function getApiKey() {
+async function getApiKeyWithScope() {
   if (process.env.CONTEXTLOOP_API_KEY) {
-    return process.env.CONTEXTLOOP_API_KEY;
+    return { apiKey: process.env.CONTEXTLOOP_API_KEY, scope: "environment" };
+  }
+  const localDir = findLocalConfigDir();
+  if (localDir) {
+    try {
+      const localBackend = new EncryptedFileBackend("local", localDir);
+      const localKey = await localBackend.get(KEY_API_KEY);
+      if (localKey) {
+        return { apiKey: localKey, scope: "local" };
+      }
+    } catch {
+    }
   }
   try {
     const backend = await getBackend();
-    return await backend.get(KEY_API_KEY);
+    const key = await backend.get(KEY_API_KEY);
+    if (key) {
+      return { apiKey: key, scope: "global" };
+    }
   } catch {
-    return null;
   }
+  return { apiKey: null, scope: null };
+}
+async function getApiKey() {
+  const { apiKey } = await getApiKeyWithScope();
+  return apiKey;
 }
-async function storeTokens(accessToken, refreshToken) {
+async function storeTokens(accessToken, refreshToken, local = false) {
   try {
-    const backend = await getBackend();
+    let backend;
+    if (local) {
+      const configDir = getOrCreateLocalConfigDir();
+      backend = new EncryptedFileBackend("local", configDir);
+    } else {
+      backend = await getBackend();
+    }
     await backend.set(KEY_ACCESS_TOKEN, accessToken);
     if (refreshToken) {
       await backend.set(KEY_REFRESH_TOKEN, refreshToken);
@@ -317,32 +373,68 @@ async function storeTokens(accessToken, refreshToken) {
     );
   }
 }
-async function getTokens() {
+async function getTokensWithScope() {
+  const localDir = findLocalConfigDir();
+  if (localDir) {
+    try {
+      const localBackend = new EncryptedFileBackend("local", localDir);
+      const accessToken = await localBackend.get(KEY_ACCESS_TOKEN);
+      if (accessToken) {
+        const refreshToken = await localBackend.get(KEY_REFRESH_TOKEN);
+        return { accessToken, refreshToken, scope: "local" };
+      }
+    } catch {
+    }
+  }
   try {
     const backend = await getBackend();
     const accessToken = await backend.get(KEY_ACCESS_TOKEN);
-    const refreshToken = await backend.get(KEY_REFRESH_TOKEN);
-    return { accessToken, refreshToken };
+    if (accessToken) {
+      const refreshToken = await backend.get(KEY_REFRESH_TOKEN);
+      return { accessToken, refreshToken, scope: "global" };
+    }
   } catch {
-    return { accessToken: null, refreshToken: null };
   }
+  return { accessToken: null, refreshToken: null, scope: null };
 }
-async function getCredentials() {
-  const apiKey = await getApiKey();
-  const { accessToken, refreshToken } = await getTokens();
+async function getTokens() {
+  const { accessToken, refreshToken } = await getTokensWithScope();
+  return { accessToken, refreshToken };
+}
+async function getCredentialsWithScope() {
+  const { apiKey, scope: apiKeyScope } = await getApiKeyWithScope();
+  const { accessToken, refreshToken, scope: tokenScope } = await getTokensWithScope();
+  const scope = apiKeyScope ?? tokenScope;
   return {
-    apiKey: apiKey ?? void 0,
-    accessToken: accessToken ?? void 0,
-    refreshToken: refreshToken ?? void 0
+    credentials: {
+      apiKey: apiKey ?? void 0,
+      accessToken: accessToken ?? void 0,
+      refreshToken: refreshToken ?? void 0
+    },
+    scope
   };
 }
-async function clearCredentials() {
-  try {
-    const backend = await getBackend();
-    await backend.delete(KEY_API_KEY);
-    await backend.delete(KEY_ACCESS_TOKEN);
-    await backend.delete(KEY_REFRESH_TOKEN);
-  } catch {
+async function clearCredentials(scope = "all") {
+  if (scope === "local" || scope === "all") {
+    const localDir = findLocalConfigDir();
+    if (localDir) {
+      try {
+        const localBackend = new EncryptedFileBackend("local", localDir);
+        await localBackend.delete(KEY_API_KEY);
+        await localBackend.delete(KEY_ACCESS_TOKEN);
+        await localBackend.delete(KEY_REFRESH_TOKEN);
+      } catch {
+      }
+    }
+  }
+  if (scope === "global" || scope === "all") {
+    try {
+      const backend = await getBackend();
+      await backend.delete(KEY_API_KEY);
+      await backend.delete(KEY_ACCESS_TOKEN);
+      await backend.delete(KEY_REFRESH_TOKEN);
+    } catch {
+    }
   }
 }
 
@@ -381,7 +473,7 @@ function createAPIClient(config2, logger) {
   function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  async function request(method, path4, options = {}) {
+  async function request(method, path6, options = {}) {
     const authHeader = await getAuthHeader();
     const headers = {
       "Content-Type": "application/json"
@@ -395,8 +487,8 @@ function createAPIClient(config2, logger) {
     let lastError = null;
     for (let attempt = 0; attempt <= RATE_LIMIT_CONFIG.maxRetries; attempt++) {
       try {
-        logger.debug(`${method} ${path4}`, { query, attempt });
-        const response = await ofetch(`${baseURL}${path4}`, {
+        logger.debug(`${method} ${path6}`, { query, attempt });
+        const response = await ofetch(`${baseURL}${path6}`, {
           method,
           headers,
           body: options.body,
@@ -508,9 +600,9 @@ function createAPIClient(config2, logger) {
         `/cli/projects/${projectId}/documents/${documentId}`
       );
     },
-    async getDocumentByPath(projectId, path4) {
+    async getDocumentByPath(projectId, path6) {
       return request("GET", `/cli/projects/${projectId}/documents`, {
-        query: { path: path4 }
+        query: { path: path6 }
       });
     },
     async createDocument(projectId, data) {
@@ -699,6 +791,18 @@ import http from "http";
 import { URL } from "url";
 import open from "open";
 import chalk2 from "chalk";
+import { ofetch as ofetch2 } from "ofetch";
+async function fetchProjectInfo(apiUrl, projectId, accessToken) {
+  try {
+    const project = await ofetch2(`${apiUrl}/cli/projects/${projectId}`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+      timeout: 1e4
+    });
+    return { name: project.name, slug: project.slug };
+  } catch {
+    return null;
+  }
+}
 var CALLBACK_PORT = 54320;
 var CALLBACK_PATH = "/callback";
 var AUTH_TIMEOUT_MS = 5 * 60 * 1e3;
@@ -881,7 +985,18 @@ ${authUrl.toString()}`);
   if (tokens.project_id) {
     saveConfig({ defaultProjectId: tokens.project_id });
     console.log(chalk2.green("Successfully authenticated!"));
-    console.log(chalk2.gray(`Default project set to: ${tokens.project_id}`));
+    const projectInfo = await fetchProjectInfo(
+      config2.apiUrl,
+      tokens.project_id,
+      tokens.access_token
+    );
+    if (projectInfo) {
+      console.log(
+        chalk2.gray(`Default project set to ${chalk2.bold(projectInfo.name)} (${tokens.project_id})`)
+      );
+    } else {
+      console.log(chalk2.gray(`Default project set to: ${tokens.project_id}`));
+    }
   } else {
     console.log(chalk2.green("Successfully authenticated!"));
   }
@@ -964,7 +1079,18 @@ async function manualLogin(config2, logger) {
   if (tokens.project_id) {
     saveConfig({ defaultProjectId: tokens.project_id });
     console.log(chalk2.green("Successfully authenticated!"));
-    console.log(chalk2.gray(`Default project set to: ${tokens.project_id}`));
+    const projectInfo = await fetchProjectInfo(
+      config2.apiUrl,
+      tokens.project_id,
+      tokens.access_token
+    );
+    if (projectInfo) {
+      console.log(
+        chalk2.gray(`Default project set to ${chalk2.bold(projectInfo.name)} (${tokens.project_id})`)
+      );
+    } else {
+      console.log(chalk2.gray(`Default project set to: ${tokens.project_id}`));
+    }
   } else {
     console.log(chalk2.green("Successfully authenticated!"));
   }
@@ -1061,22 +1187,36 @@ function formatRelativeTime(date) {
 // src/commands/auth.ts
 function registerAuthCommands(program2, context2) {
   const auth = program2.command("auth").description("Authentication commands");
-  auth.command("login").description("Authenticate with ContextLoop").option("--api-key <key>", "Login with an API key").option("--manual", "Use manual login flow (for environments without browser)").action(async (options) => {
+  auth.command("login").description("Authenticate with ContextLoop").option("--api-key <key>", "Login with an API key").option("--local", "Store credentials in project directory (.contextloop/)").option("--manual", "Use manual login flow (for environments without browser)").action(async (options) => {
     const globalOptions = program2.opts();
     try {
+      const isLocal = options.local ?? false;
+      const scopeLabel = isLocal ? "project" : "global";
       if (options.apiKey) {
         const spinner = ora("Validating API key...").start();
         try {
           const { user } = await context2.apiClient.validateApiKey(options.apiKey);
-          await storeApiKey(options.apiKey);
-          spinner.succeed(`Logged in as ${chalk4.bold(user.name)} (${user.email})`);
+          await storeApiKey(options.apiKey, isLocal);
+          spinner.succeed(
+            `Logged in as ${chalk4.bold(user.name)} (${user.email}) [${chalk4.cyan(scopeLabel)}]`
+          );
+          if (isLocal) {
+            console.log(chalk4.gray("Credentials stored in .contextloop/ directory"));
+            console.log(chalk4.yellow("Tip: Add .contextloop/ to your .gitignore"));
+          }
         } catch (error) {
           spinner.fail("Login failed");
           throw error;
         }
       } else if (options.manual) {
+        if (isLocal) {
+          console.log(chalk4.yellow("Note: OAuth login currently only supports global scope"));
+        }
         await manualLogin(context2.config, context2.logger);
       } else {
+        if (isLocal) {
+          console.log(chalk4.yellow("Note: OAuth login currently only supports global scope"));
+        }
         await interactiveLogin(context2.config, context2.logger);
       }
     } catch (error) {
@@ -1084,12 +1224,21 @@ function registerAuthCommands(program2, context2) {
       process.exit(getExitCode(error));
     }
   });
-  auth.command("logout").description("Clear stored credentials").action(async () => {
+  auth.command("logout").description("Clear stored credentials").option("--local", "Clear only project-local credentials").option("--global", "Clear only global credentials").option("--all", "Clear all credentials (default)").action(async (options) => {
     const globalOptions = program2.opts();
     try {
-      await clearCredentials();
-      clearConfig(["defaultProjectId", "defaultProjectSlug"]);
-      console.log(chalk4.green("Logged out successfully."));
+      let scope = "all";
+      if (options.local && !options.global) {
+        scope = "local";
+      } else if (options.global && !options.local) {
+        scope = "global";
+      }
+      await clearCredentials(scope);
+      if (scope === "global" || scope === "all") {
+        clearConfig(["defaultProjectId", "defaultProjectSlug"]);
+      }
+      const scopeMsg = scope === "local" ? "project-local" : scope === "global" ? "global" : "all";
+      console.log(chalk4.green(`Logged out successfully (${scopeMsg} credentials cleared).`));
     } catch (error) {
       console.error(formatError(error, globalOptions.format));
       process.exit(getExitCode(error));
@@ -1098,7 +1247,7 @@ function registerAuthCommands(program2, context2) {
   auth.command("whoami").description("Display current user information").action(async () => {
     const globalOptions = program2.opts();
     try {
-      const creds = await getCredentials();
+      const { credentials: creds, scope } = await getCredentialsWithScope();
       if (!creds.apiKey && !creds.accessToken) {
         if (globalOptions.format === "json") {
           console.log(JSON.stringify({ loggedIn: false }));
@@ -1113,27 +1262,56 @@ function registerAuthCommands(program2, context2) {
       const spinner = ora("Fetching user info...").start();
       try {
         const user = await context2.apiClient.getCurrentUser();
-        spinner.stop();
         const defaultProjectId = context2.config.defaultProjectId;
+        let project = null;
+        if (defaultProjectId) {
+          spinner.text = "Fetching project info...";
+          try {
+            project = await context2.apiClient.getProject(defaultProjectId);
+          } catch {
+            project = null;
+          }
+        }
+        spinner.stop();
+        const localDir = findLocalConfigDir();
         printOutput(
-          user,
+          { user, project, scope, localDir },
           {
-            text: (u) => {
+            text: ({ user: u, project: p, scope: s, localDir: ld }) => {
               const lines = [
                 chalk4.bold(u.name),
                 chalk4.gray(u.email),
                 chalk4.gray(`ID: ${u.id}`)
               ];
-              if (defaultProjectId) {
+              lines.push("");
+              const scopeLabel = s === "environment" ? chalk4.magenta("environment variable") : s === "local" ? chalk4.cyan("project-local") : chalk4.blue("global");
+              lines.push(`Auth: ${scopeLabel}`);
+              if (s === "local" && ld) {
+                lines.push(chalk4.gray(`  ${ld}`));
+              }
+              if (p) {
+                lines.push("");
+                lines.push(chalk4.bold("Current project:"));
+                lines.push(`  ${chalk4.cyan(p.name)}`);
+                lines.push(chalk4.gray(`  ID: ${p.id}`));
+                if (p.slug) {
+                  lines.push(chalk4.gray(`  Slug: ${p.slug}`));
+                }
+              } else if (defaultProjectId) {
                 lines.push("");
-                lines.push(chalk4.gray(`Default project: ${defaultProjectId}`));
+                lines.push(chalk4.yellow(`Default project: ${defaultProjectId} (not found)`));
+              } else {
+                lines.push("");
+                lines.push(chalk4.gray("No default project set."));
+                lines.push(chalk4.gray("Run 'contextloop project use <id>' to set one."));
               }
               return lines.join("\n");
             },
-            json: (u) => ({
+            json: ({ user: u, project: p, scope: s }) => ({
               loggedIn: true,
               user: u,
-              defaultProjectId: defaultProjectId || null
+              authScope: s,
+              project: p ? { id: p.id, name: p.name, slug: p.slug, role: p.role } : null
             })
           },
           globalOptions
@@ -2222,6 +2400,887 @@ Page ${r.pagination.page} of ${r.pagination.totalPages} (${r.pagination.totalIte
   });
 }
 
+// src/commands/sync.ts
+import ora6 from "ora";
+import chalk9 from "chalk";
+
+// src/lib/sync/pool.ts
+async function executeWithPool(items, executor, options) {
+  const { concurrency, onProgress } = options;
+  const successes = [];
+  const failures = [];
+  if (items.length === 0) {
+    return { successes, failures };
+  }
+  let completed = 0;
+  let nextIndex = 0;
+  return new Promise((resolve) => {
+    const executing = /* @__PURE__ */ new Set();
+    function processNext() {
+      while (executing.size < concurrency && nextIndex < items.length) {
+        const currentIndex = nextIndex++;
+        const item = items[currentIndex];
+        const promise = executor(item).then((result) => {
+          successes.push({ item, result });
+        }).catch((error) => {
+          failures.push({
+            item,
+            error: error instanceof Error ? error : new Error(String(error))
+          });
+        }).finally(() => {
+          executing.delete(promise);
+          completed++;
+          onProgress?.(completed, items.length);
+          if (completed === items.length) {
+            resolve({ successes, failures });
+          } else {
+            processNext();
+          }
+        });
+        executing.add(promise);
+      }
+    }
+    processNext();
+  });
+}
+async function mapWithPool(items, executor, options) {
+  const { concurrency, onProgress } = options;
+  const results = new Array(items.length);
+  if (items.length === 0) {
+    return results;
+  }
+  let completed = 0;
+  let nextIndex = 0;
+  return new Promise((resolve) => {
+    const executing = /* @__PURE__ */ new Set();
+    function processNext() {
+      while (executing.size < concurrency && nextIndex < items.length) {
+        const currentIndex = nextIndex++;
+        const item = items[currentIndex];
+        const promise = executor(item).then((value) => {
+          results[currentIndex] = { success: true, value };
+        }).catch((error) => {
+          results[currentIndex] = {
+            success: false,
+            error: error instanceof Error ? error : new Error(String(error))
+          };
+        }).finally(() => {
+          executing.delete(promise);
+          completed++;
+          onProgress?.(completed, items.length);
+          if (completed === items.length) {
+            resolve(results);
+          } else {
+            processNext();
+          }
+        });
+        executing.add(promise);
+      }
+    }
+    processNext();
+  });
+}
+
+// src/lib/sync/local.ts
+import fs4 from "fs";
+import path4 from "path";
+import { glob as glob2 } from "glob";
+
+// src/lib/hash.ts
+import crypto3 from "crypto";
+function computeMD5(content) {
+  return crypto3.createHash("md5").update(content, "utf8").digest("hex");
+}
+
+// src/lib/sync/local.ts
+var IGNORE_FILE_NAME = ".contextignore";
+var DEFAULT_INCLUDE = ["**/*.md"];
+var DEFAULT_EXCLUDE = [
+  "node_modules/**",
+  ".git/**",
+  ".DS_Store",
+  "**/.DS_Store",
+  "**/*.tmp",
+  "**/~*",
+  "**/*.swp",
+  "**/*.swo",
+  IGNORE_FILE_NAME
+  // Don't sync the ignore file itself
+];
+function parseIgnoreFile(content) {
+  const patterns = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    patterns.push(trimmed);
+  }
+  return patterns;
+}
+function loadIgnorePatterns(baseDir) {
+  const ignoreFilePath = path4.join(baseDir, IGNORE_FILE_NAME);
+  try {
+    if (fs4.existsSync(ignoreFilePath)) {
+      const content = fs4.readFileSync(ignoreFilePath, "utf8");
+      return parseIgnoreFile(content);
+    }
+  } catch {
+  }
+  return [];
+}
+async function listLocalFiles(options) {
+  const { baseDir, include = DEFAULT_INCLUDE, exclude = [] } = options;
+  const absoluteBaseDir = path4.resolve(baseDir);
+  if (!fs4.existsSync(absoluteBaseDir)) {
+    throw new Error(`Directory does not exist: ${absoluteBaseDir}`);
+  }
+  const stats = fs4.statSync(absoluteBaseDir);
+  if (!stats.isDirectory()) {
+    throw new Error(`Not a directory: ${absoluteBaseDir}`);
+  }
+  const ignorePatterns = loadIgnorePatterns(absoluteBaseDir);
+  const allExclude = [...DEFAULT_EXCLUDE, ...ignorePatterns, ...exclude];
+  const files = await glob2(include, {
+    cwd: absoluteBaseDir,
+    nodir: true,
+    dot: false,
+    ignore: allExclude
+  });
+  const items = /* @__PURE__ */ new Map();
+  for (const relativePath of files) {
+    const absolutePath = path4.join(absoluteBaseDir, relativePath);
+    try {
+      const fileStats = fs4.statSync(absolutePath);
+      if (fileStats.isDirectory()) {
+        continue;
+      }
+      const content = fs4.readFileSync(absolutePath, "utf8");
+      const normalizedPath = "/" + relativePath.split(path4.sep).join("/");
+      items.set(normalizedPath, {
+        path: normalizedPath,
+        absolutePath,
+        contentHash: computeMD5(content),
+        mtime: fileStats.mtime,
+        size: content.length
+      });
+    } catch {
+      continue;
+    }
+  }
+  return items;
+}
+function normalizePath(inputPath) {
+  let normalized = inputPath.replace(/\\/g, "/");
+  normalized = normalized.replace(/\/+/g, "/");
+  if (!normalized.startsWith("/")) {
+    normalized = "/" + normalized;
+  }
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+function toLocalPath(normalizedPath, baseDir) {
+  const relativePath = normalizedPath.slice(1);
+  return path4.join(path4.resolve(baseDir), relativePath);
+}
+
+// src/lib/sync/remote.ts
+async function listRemoteFiles(options) {
+  const { apiClient: apiClient2, projectId, remotePath, concurrency } = options;
+  const allDocuments = [];
+  let page = 1;
+  const pageSize = 100;
+  let hasMore = true;
+  while (hasMore) {
+    const response = await apiClient2.listDocuments(projectId, {
+      page,
+      pageSize,
+      path: remotePath
+    });
+    const documents = response.documents.filter((d) => !d.isFolder);
+    allDocuments.push(...documents);
+    hasMore = response.pagination.page < response.pagination.totalPages;
+    page++;
+  }
+  const filteredDocuments = remotePath ? allDocuments.filter((d) => {
+    const normalizedDocPath = normalizePath(d.path);
+    const normalizedRemotePath = normalizePath(remotePath);
+    return normalizedDocPath === normalizedRemotePath || normalizedDocPath.startsWith(normalizedRemotePath + "/");
+  }) : allDocuments;
+  const results = await mapWithPool(
+    filteredDocuments,
+    async (doc) => {
+      const fullDoc = await apiClient2.getDocument(projectId, doc.id);
+      return fullDoc;
+    },
+    { concurrency }
+  );
+  const items = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    if (result.success) {
+      const doc = result.value;
+      const normalizedPath = normalizePath(doc.path);
+      const adjustedPath = remotePath ? getRelativePath(normalizedPath, normalizePath(remotePath)) : normalizedPath;
+      items.set(adjustedPath, {
+        path: adjustedPath,
+        id: doc.id,
+        version: doc.version,
+        contentHash: computeMD5(doc.content),
+        mtime: new Date(doc.updatedAt),
+        size: doc.content.length
+      });
+    }
+  }
+  return items;
+}
+function getRelativePath(fullPath, basePath) {
+  if (fullPath === basePath) {
+    return "/" + fullPath.split("/").pop();
+  }
+  if (fullPath.startsWith(basePath + "/")) {
+    return fullPath.slice(basePath.length);
+  }
+  return fullPath;
+}
+
+// src/lib/sync/compare.ts
+function compareSyncItems(localItems, remoteItems, options) {
+  const { direction, deleteOrphans, conflictStrategy } = options;
+  const actions = [];
+  const conflicts = [];
+  const allPaths = /* @__PURE__ */ new Set([...localItems.keys(), ...remoteItems.keys()]);
+  for (const path6 of allPaths) {
+    const local = localItems.get(path6);
+    const remote = remoteItems.get(path6);
+    if (local && remote) {
+      if (local.contentHash === remote.contentHash) {
+        actions.push({
+          type: "skip",
+          path: path6,
+          local,
+          remote,
+          reason: "Identical content"
+        });
+      } else {
+        handleContentDiff(local, remote, direction, conflictStrategy, actions, conflicts);
+      }
+    } else if (local && !remote) {
+      handleLocalOnly(local, direction, deleteOrphans, actions);
+    } else if (!local && remote) {
+      handleRemoteOnly(remote, direction, deleteOrphans, actions);
+    }
+  }
+  actions.sort((a, b) => a.path.localeCompare(b.path));
+  conflicts.sort((a, b) => a.path.localeCompare(b.path));
+  return {
+    actions,
+    conflicts,
+    summary: computeSummary(actions, conflicts, localItems.size, remoteItems.size)
+  };
+}
+function handleContentDiff(local, remote, direction, conflictStrategy, actions, conflicts) {
+  const path6 = local.path;
+  if (direction === "push") {
+    actions.push({
+      type: "update-remote",
+      path: path6,
+      local,
+      remote,
+      reason: "Local is source of truth (push mode)"
+    });
+  } else if (direction === "pull") {
+    actions.push({
+      type: "update-local",
+      path: path6,
+      local,
+      remote,
+      reason: "Remote is source of truth (pull mode)"
+    });
+  } else {
+    switch (conflictStrategy) {
+      case "newest": {
+        const localNewer = local.mtime > remote.mtime;
+        actions.push({
+          type: localNewer ? "update-remote" : "update-local",
+          path: path6,
+          local,
+          remote,
+          reason: localNewer ? `Local newer (${formatTime(local.mtime)} > ${formatTime(remote.mtime)})` : `Remote newer (${formatTime(remote.mtime)} > ${formatTime(local.mtime)})`
+        });
+        break;
+      }
+      case "local":
+        actions.push({
+          type: "update-remote",
+          path: path6,
+          local,
+          remote,
+          reason: "Local wins (--conflict local)"
+        });
+        break;
+      case "remote":
+        actions.push({
+          type: "update-local",
+          path: path6,
+          local,
+          remote,
+          reason: "Remote wins (--conflict remote)"
+        });
+        break;
+      case "skip":
+        actions.push({
+          type: "skip",
+          path: path6,
+          local,
+          remote,
+          reason: "Conflict skipped (--conflict skip)"
+        });
+        break;
+      case "error":
+      default:
+        conflicts.push({
+          path: path6,
+          local,
+          remote
+        });
+        break;
+    }
+  }
+}
+function handleLocalOnly(local, direction, deleteOrphans, actions) {
+  const path6 = local.path;
+  if (direction === "pull") {
+    if (deleteOrphans) {
+      actions.push({
+        type: "delete-local",
+        path: path6,
+        local,
+        reason: "Not on remote (--delete)"
+      });
+    } else {
+      actions.push({
+        type: "skip",
+        path: path6,
+        local,
+        reason: "Local-only (no --delete)"
+      });
+    }
+  } else {
+    actions.push({
+      type: "create-remote",
+      path: path6,
+      local,
+      reason: "New local file"
+    });
+  }
+}
+function handleRemoteOnly(remote, direction, deleteOrphans, actions) {
+  const path6 = remote.path;
+  if (direction === "push") {
+    if (deleteOrphans) {
+      actions.push({
+        type: "delete-remote",
+        path: path6,
+        remote,
+        reason: "Not local (--delete)"
+      });
+    } else {
+      actions.push({
+        type: "skip",
+        path: path6,
+        remote,
+        reason: "Remote-only (no --delete)"
+      });
+    }
+  } else {
+    actions.push({
+      type: "create-local",
+      path: path6,
+      remote,
+      reason: "New remote file"
+    });
+  }
+}
+function computeSummary(actions, conflicts, totalLocal, totalRemote) {
+  const summary = {
+    totalLocal,
+    totalRemote,
+    toCreate: { local: 0, remote: 0 },
+    toUpdate: { local: 0, remote: 0 },
+    toDelete: { local: 0, remote: 0 },
+    toSkip: 0,
+    conflicts: conflicts.length
+  };
+  for (const action of actions) {
+    switch (action.type) {
+      case "create-local":
+        summary.toCreate.local++;
+        break;
+      case "create-remote":
+        summary.toCreate.remote++;
+        break;
+      case "update-local":
+        summary.toUpdate.local++;
+        break;
+      case "update-remote":
+        summary.toUpdate.remote++;
+        break;
+      case "delete-local":
+        summary.toDelete.local++;
+        break;
+      case "delete-remote":
+        summary.toDelete.remote++;
+        break;
+      case "skip":
+        summary.toSkip++;
+        break;
+    }
+  }
+  return summary;
+}
+function formatTime(date) {
+  return date.toISOString().replace("T", " ").slice(0, 19);
+}
+function hasChanges(plan) {
+  return plan.actions.some((a) => a.type !== "skip") || plan.conflicts.length > 0;
+}
+function getOperationCount(plan) {
+  return plan.actions.filter((a) => a.type !== "skip").length;
+}
+
+// src/lib/sync/execute.ts
+import fs5 from "fs";
+import path5 from "path";
+async function executeSyncPlan(plan, options) {
+  const { apiClient: apiClient2, projectId, localBaseDir, remotePath, concurrency, onProgress } = options;
+  const skipped = plan.actions.filter((a) => a.type === "skip");
+  const actionsToExecute = plan.actions.filter((a) => a.type !== "skip");
+  if (actionsToExecute.length === 0) {
+    return { executed: [], failed: [], skipped };
+  }
+  const result = await executeWithPool(
+    actionsToExecute,
+    async (action) => {
+      await executeSingleAction(action, {
+        apiClient: apiClient2,
+        projectId,
+        localBaseDir,
+        remotePath
+      });
+    },
+    {
+      concurrency,
+      onProgress: (completed, total) => {
+        const currentAction = actionsToExecute[completed - 1];
+        onProgress?.(completed, total, currentAction);
+      }
+    }
+  );
+  return {
+    executed: result.successes.map((s) => s.item),
+    failed: result.failures.map((f) => ({ action: f.item, error: f.error })),
+    skipped
+  };
+}
+async function executeSingleAction(action, context2) {
+  const { apiClient: apiClient2, projectId, localBaseDir, remotePath } = context2;
+  switch (action.type) {
+    case "create-local":
+    case "update-local": {
+      if (!action.remote) {
+        throw new Error(`No remote info for action: ${action.path}`);
+      }
+      const doc = await apiClient2.getDocument(projectId, action.remote.id);
+      const localPath = toLocalPath(action.path, localBaseDir);
+      const dir = path5.dirname(localPath);
+      if (!fs5.existsSync(dir)) {
+        fs5.mkdirSync(dir, { recursive: true });
+      }
+      fs5.writeFileSync(localPath, doc.content, "utf8");
+      break;
+    }
+    case "create-remote": {
+      if (!action.local) {
+        throw new Error(`No local info for action: ${action.path}`);
+      }
+      const content = fs5.readFileSync(action.local.absolutePath, "utf8");
+      const title = path5.basename(action.path);
+      const fullRemotePath = remotePath ? normalizePath(remotePath + action.path) : action.path;
+      await apiClient2.createDocument(projectId, {
+        title,
+        content,
+        path: fullRemotePath
+      });
+      break;
+    }
+    case "update-remote": {
+      if (!action.local || !action.remote) {
+        throw new Error(`Missing info for action: ${action.path}`);
+      }
+      const content = fs5.readFileSync(action.local.absolutePath, "utf8");
+      await apiClient2.updateDocument(projectId, action.remote.id, {
+        content,
+        createVersion: true
+      });
+      break;
+    }
+    case "delete-local": {
+      if (!action.local) {
+        throw new Error(`No local info for action: ${action.path}`);
+      }
+      fs5.unlinkSync(action.local.absolutePath);
+      cleanupEmptyDirs(path5.dirname(action.local.absolutePath), localBaseDir);
+      break;
+    }
+    case "delete-remote": {
+      if (!action.remote) {
+        throw new Error(`No remote info for action: ${action.path}`);
+      }
+      await apiClient2.deleteDocument(projectId, action.remote.id);
+      break;
+    }
+    case "skip":
+      break;
+  }
+}
+function cleanupEmptyDirs(dirPath, baseDir) {
+  const resolvedBase = path5.resolve(baseDir);
+  let current = path5.resolve(dirPath);
+  while (current !== resolvedBase && current.startsWith(resolvedBase)) {
+    try {
+      const entries = fs5.readdirSync(current);
+      if (entries.length === 0) {
+        fs5.rmdirSync(current);
+        current = path5.dirname(current);
+      } else {
+        break;
+      }
+    } catch {
+      break;
+    }
+  }
+}
+function countOperations(result) {
+  let uploaded = 0;
+  let downloaded = 0;
+  let deleted = 0;
+  for (const action of result.executed) {
+    switch (action.type) {
+      case "create-remote":
+      case "update-remote":
+        uploaded++;
+        break;
+      case "create-local":
+      case "update-local":
+        downloaded++;
+        break;
+      case "delete-local":
+      case "delete-remote":
+        deleted++;
+        break;
+    }
+  }
+  return {
+    uploaded,
+    downloaded,
+    deleted,
+    failed: result.failed.length
+  };
+}
+
+// src/commands/sync.ts
+var DEFAULT_CONCURRENCY = 5;
+var MAX_CONCURRENCY = 10;
+function collect(value, previous) {
+  return [...previous, value];
+}
+function getProjectId4(globalOptions, context2) {
+  const projectId = globalOptions.project || context2.config.defaultProjectId;
+  if (!projectId) {
+    throw new CLIError(
+      "PROJECT_NOT_SET",
+      "No project specified",
+      "Use --project <id> or run 'contextloop project use <id>' to set a default"
+    );
+  }
+  return projectId;
+}
+function parseConcurrency(value) {
+  if (!value) {
+    return DEFAULT_CONCURRENCY;
+  }
+  const num = parseInt(value, 10);
+  if (isNaN(num) || num < 1) {
+    throw new CLIError("VALIDATION_ERROR", "Concurrency must be a positive integer");
+  }
+  return Math.min(num, MAX_CONCURRENCY);
+}
+function parseConflictStrategy(value) {
+  const strategies = ["newest", "local", "remote", "skip", "error"];
+  if (!value) {
+    return "error";
+  }
+  if (!strategies.includes(value)) {
+    throw new CLIError(
+      "VALIDATION_ERROR",
+      `Invalid conflict strategy: ${value}`,
+      `Valid strategies: ${strategies.join(", ")}`
+    );
+  }
+  return value;
+}
+function formatDryRun(plan, globalOptions) {
+  printOutput(
+    plan,
+    {
+      text: (p) => formatDryRunText(p),
+      json: (p) => ({
+        dryRun: true,
+        actions: p.actions,
+        conflicts: p.conflicts,
+        summary: p.summary
+      })
+    },
+    globalOptions
+  );
+}
+function formatDryRunText(plan) {
+  const lines = [];
+  lines.push(chalk9.cyan("\n=== Sync Preview (dry-run) ===\n"));
+  const groups = {
+    "create-remote": [],
+    "update-remote": [],
+    "create-local": [],
+    "update-local": [],
+    "delete-remote": [],
+    "delete-local": []
+  };
+  for (const action of plan.actions) {
+    if (action.type !== "skip" && groups[action.type]) {
+      groups[action.type].push(action);
+    }
+  }
+  const labels = {
+    "create-remote": { label: "Upload (new)", icon: "+", color: chalk9.green },
+    "update-remote": { label: "Upload (update)", icon: "~", color: chalk9.yellow },
+    "create-local": { label: "Download (new)", icon: "+", color: chalk9.green },
+    "update-local": { label: "Download (update)", icon: "~", color: chalk9.yellow },
+    "delete-remote": { label: "Delete remote", icon: "-", color: chalk9.red },
+    "delete-local": { label: "Delete local", icon: "-", color: chalk9.red }
+  };
+  for (const [type, actions] of Object.entries(groups)) {
+    if (actions.length > 0) {
+      const { label, icon, color } = labels[type];
+      lines.push(color.bold(`${label} (${actions.length}):`));
+      for (const action of actions) {
+        lines.push(color(`  ${icon} ${action.path}`));
+      }
+      lines.push("");
+    }
+  }
+  if (plan.conflicts.length > 0) {
+    lines.push(chalk9.red.bold(`Conflicts (${plan.conflicts.length}):`));
+    for (const conflict of plan.conflicts) {
+      lines.push(chalk9.red(`  ! ${conflict.path}`));
+      lines.push(chalk9.gray(`    Local:  ${conflict.local.mtime.toISOString()}`));
+      lines.push(chalk9.gray(`    Remote: ${conflict.remote.mtime.toISOString()}`));
+    }
+    lines.push("");
+  }
+  const s = plan.summary;
+  lines.push(chalk9.bold("Summary:"));
+  lines.push(`  Upload:   ${s.toCreate.remote} new, ${s.toUpdate.remote} updated`);
+  lines.push(`  Download: ${s.toCreate.local} new, ${s.toUpdate.local} updated`);
+  lines.push(`  Delete:   ${s.toDelete.local} local, ${s.toDelete.remote} remote`);
+  lines.push(`  Skip:     ${s.toSkip}`);
+  if (s.conflicts > 0) {
+    lines.push(chalk9.red(`  Conflicts: ${s.conflicts}`));
+  }
+  lines.push("");
+  lines.push(chalk9.cyan("Run without --dry-run to execute these changes."));
+  return lines.join("\n");
+}
+function formatResult(result, globalOptions) {
+  printOutput(
+    result,
+    {
+      text: (r) => formatResultText(r),
+      json: (r) => ({
+        executed: r.executed,
+        failed: r.failed.map((f) => ({
+          action: f.action,
+          error: f.error.message
+        })),
+        skipped: r.skipped.length
+      })
+    },
+    globalOptions
+  );
+}
+function formatResultText(result) {
+  const lines = [];
+  const counts = countOperations(result);
+  const total = counts.uploaded + counts.downloaded + counts.deleted;
+  if (total > 0) {
+    const parts = [];
+    if (counts.uploaded > 0) parts.push(`${counts.uploaded} uploaded`);
+    if (counts.downloaded > 0) parts.push(`${counts.downloaded} downloaded`);
+    if (counts.deleted > 0) parts.push(`${counts.deleted} deleted`);
+    lines.push(chalk9.green(`
+Synced ${total} file(s) (${parts.join(", ")})`));
+  }
+  if (result.failed.length > 0) {
+    lines.push(chalk9.red(`
+Failed: ${result.failed.length} operation(s)`));
+    for (const failure of result.failed) {
+      lines.push(chalk9.red(`  - ${failure.action.path}: ${failure.error.message}`));
+    }
+  }
+  if (total === 0 && result.failed.length === 0) {
+    lines.push(chalk9.green("\nEverything is in sync!"));
+  }
+  return lines.join("\n");
+}
+async function runSync(localDir, direction, options, globalOptions, context2) {
+  const projectId = getProjectId4(globalOptions, context2);
+  const concurrency = parseConcurrency(options.concurrency);
+  const conflictStrategy = parseConflictStrategy(options.conflict);
+  const syncOptions = {
+    direction,
+    remotePath: options.remotePath,
+    deleteOrphans: options.delete || false,
+    conflictStrategy,
+    concurrency,
+    dryRun: options.dryRun || false,
+    include: options.include.length > 0 ? options.include : void 0,
+    exclude: options.exclude.length > 0 ? options.exclude : void 0
+  };
+  const scanSpinner = ora6("Scanning local files...").start();
+  let localItems;
+  try {
+    localItems = await listLocalFiles({
+      baseDir: localDir,
+      include: syncOptions.include,
+      exclude: syncOptions.exclude
+    });
+    scanSpinner.succeed(`Found ${localItems.size} local file(s)`);
+  } catch (error) {
+    scanSpinner.fail("Failed to scan local files");
+    throw error;
+  }
+  const fetchSpinner = ora6("Fetching remote files...").start();
+  let remoteItems;
+  try {
+    remoteItems = await listRemoteFiles({
+      apiClient: context2.apiClient,
+      projectId,
+      remotePath: syncOptions.remotePath,
+      concurrency
+    });
+    fetchSpinner.succeed(`Found ${remoteItems.size} remote file(s)`);
+  } catch (error) {
+    fetchSpinner.fail("Failed to fetch remote files");
+    throw error;
+  }
+  const compareSpinner = ora6("Comparing files...").start();
+  const plan = compareSyncItems(localItems, remoteItems, syncOptions);
+  compareSpinner.stop();
+  if (plan.conflicts.length > 0 && conflictStrategy === "error") {
+    formatDryRun(plan, globalOptions);
+    throw new CLIError(
+      "SYNC_CONFLICT",
+      `${plan.conflicts.length} conflict(s) detected`,
+      "Use --conflict <strategy> to resolve (newest, local, remote, skip)"
+    );
+  }
+  if (syncOptions.dryRun) {
+    formatDryRun(plan, globalOptions);
+    return;
+  }
+  if (!hasChanges(plan)) {
+    console.log(chalk9.green("\nEverything is in sync!"));
+    return;
+  }
+  const deletionCount = plan.summary.toDelete.local + plan.summary.toDelete.remote;
+  if (deletionCount > 0 && !options.force) {
+    formatDryRun(plan, globalOptions);
+    console.log(
+      chalk9.yellow(`
+This will delete ${deletionCount} file(s). Use --force to skip this warning.`)
+    );
+    throw new CLIError("VALIDATION_ERROR", "Deletions require --force flag");
+  }
+  const opCount = getOperationCount(plan);
+  const execSpinner = ora6(`Syncing 0/${opCount}...`).start();
+  try {
+    const result = await executeSyncPlan(plan, {
+      apiClient: context2.apiClient,
+      projectId,
+      localBaseDir: localDir,
+      remotePath: syncOptions.remotePath,
+      concurrency,
+      onProgress: (completed, total) => {
+        execSpinner.text = `Syncing ${completed}/${total}...`;
+      }
+    });
+    execSpinner.stop();
+    formatResult(result, globalOptions);
+    if (result.failed.length > 0) {
+      throw new CLIError(
+        "SYNC_PARTIAL_FAILURE",
+        `${result.failed.length} operation(s) failed`,
+        "Run again to retry failed operations"
+      );
+    }
+  } catch (error) {
+    execSpinner.stop();
+    throw error;
+  }
+}
+function registerSyncCommands(program2, context2) {
+  const sync = program2.command("sync").description("Sync files with ContextLoop");
+  const addCommonOptions = (cmd) => {
+    return cmd.option("--remote-path <path>", "Remote path prefix to sync").option("--delete", "Delete files that do not exist on the source side").option(
+      "--conflict <strategy>",
+      "Conflict resolution: newest, local, remote, skip, error",
+      "error"
+    ).option("--concurrency <n>", "Max concurrent operations", String(DEFAULT_CONCURRENCY)).option("--dry-run", "Preview changes without executing").option("--include <glob>", "Include pattern (can be repeated)", collect, []).option("--exclude <glob>", "Exclude pattern (can be repeated)", collect, []).option("--force", "Skip confirmation for deletions");
+  };
+  addCommonOptions(sync).argument("[local-dir]", "Local directory to sync", ".").action(async (localDir, options) => {
+    const globalOptions = program2.opts();
+    try {
+      await runSync(localDir, "both", options, globalOptions, context2);
+    } catch (error) {
+      console.error(formatError(error, globalOptions.format));
+      process.exit(getExitCode(error));
+    }
+  });
+  addCommonOptions(
+    sync.command("push").argument("<local-dir>", "Local directory to push").description("Push local files to remote (local -> remote)")
+  ).action(async (localDir, options) => {
+    const globalOptions = program2.opts();
+    try {
+      await runSync(localDir, "push", options, globalOptions, context2);
+    } catch (error) {
+      console.error(formatError(error, globalOptions.format));
+      process.exit(getExitCode(error));
+    }
+  });
+  addCommonOptions(
+    sync.command("pull").argument("<local-dir>", "Local directory to pull into").description("Pull remote files to local (remote -> local)")
+  ).action(async (localDir, options) => {
+    const globalOptions = program2.opts();
+    try {
+      await runSync(localDir, "pull", options, globalOptions, context2);
+    } catch (error) {
+      console.error(formatError(error, globalOptions.format));
+      process.exit(getExitCode(error));
+    }
+  });
+}
+
 // src/index.ts
 var program = new Command();
 program.name("contextloop").description("CLI for ContextLoop - manage documents and context").version("0.1.0").option("-p, --project <id>", "Project ID or slug").option("-f, --format <format>", "Output format: text, json", "text").option("-q, --quiet", "Suppress non-essential output").option("-v, --verbose", "Enable verbose logging").option("--no-color", "Disable colored output");
@@ -2238,6 +3297,7 @@ registerProjectCommands(program, context);
 registerDocumentCommands(program, context);
 registerContextCommands(program, context);
 registerCommentCommands(program, context);
+registerSyncCommands(program, context);
 async function main() {
   try {
     await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextloop-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI for ContextLoop - upload, download, and manage documents",
   "type": "module",
   "bin": {
@@ -23,23 +23,23 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.2.0",
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "conf": "^12.0.0",
-    "glob": "^10.3.0",
-    "ofetch": "^1.3.0",
-    "open": "^10.0.0",
-    "ora": "^8.0.0"
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "conf": "^15.0.2",
+    "glob": "^13.0.0",
+    "ofetch": "^1.5.1",
+    "open": "^11.0.0",
+    "ora": "^9.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^7.0.0",
-    "@typescript-eslint/parser": "^7.0.0",
-    "@vitest/coverage-v8": "^1.3.0",
-    "eslint": "^8.57.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.4.0",
-    "vitest": "^1.3.0"
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint": "^9.39.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
   },
   "engines": {
     "node": ">=20.0.0"