appwrite-utils-cli 1.5.1 → 1.6.0

package/src/utils/pathResolvers.ts

@@ -0,0 +1,81 @@
+import path from "path";
+
+/**
+ * Path resolution utilities for Appwrite configuration and schema directories
+ */
+
+/**
+ * Resolves the schema output directory path
+ * @param configPath - Base configuration directory path
+ * @returns Full path to schemas directory
+ */
+export function resolveSchemaDir(configPath: string): string {
+  return path.join(configPath, "schemas");
+}
+
+/**
+ * Resolves the collections directory path
+ * @param configPath - Base configuration directory path
+ * @returns Full path to collections directory
+ */
+export function resolveCollectionsDir(configPath: string): string {
+  return path.join(configPath, "collections");
+}
+
+/**
+ * Resolves the tables directory path
+ * @param configPath - Base configuration directory path
+ * @returns Full path to tables directory
+ */
+export function resolveTablesDir(configPath: string): string {
+  return path.join(configPath, "tables");
+}
+
+/**
+ * Resolves the YAML schema directory path
+ * @param configPath - Base configuration directory path
+ * @returns Full path to .yaml_schemas directory
+ */
+export function resolveYamlSchemaDir(configPath: string): string {
+  return path.join(configPath, ".yaml_schemas");
+}
+
+/**
+ * Resolves the import data directory path
+ * @param configPath - Base configuration directory path
+ * @returns Full path to importData directory
+ */
+export function resolveImportDataDir(configPath: string): string {
+  return path.join(configPath, "importData");
+}
+
+/**
+ * Resolves the .appwrite configuration directory
+ * @param startDir - Directory to start searching from
+ * @returns Path to .appwrite directory or null if not found
+ */
+export function resolveAppwriteDir(startDir: string): string | null {
+  const appwriteDir = path.join(startDir, ".appwrite");
+  // Note: Actual existence check should be done by caller
+  return appwriteDir;
+}
+
+/**
+ * Resolves a collection file path within the collections directory
+ * @param configPath - Base configuration directory path
+ * @param fileName - Name of the collection file (e.g., "User.ts" or "User.yaml")
+ * @returns Full path to the collection file
+ */
+export function resolveCollectionFile(configPath: string, fileName: string): string {
+  return path.join(resolveCollectionsDir(configPath), fileName);
+}
+
+/**
+ * Resolves a table file path within the tables directory
+ * @param configPath - Base configuration directory path
+ * @param fileName - Name of the table file (e.g., "User.ts" or "User.yaml")
+ * @returns Full path to the table file
+ */
+export function resolveTableFile(configPath: string, fileName: string): string {
+  return path.join(resolveTablesDir(configPath), fileName);
+}

package/src/utils/projectConfig.ts

@@ -0,0 +1,299 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+import type { AppwriteConfig } from "appwrite-utils";
+
+export interface AppwriteProjectConfig {
+  projectId: string;
+  endpoint?: string;
+  projectName?: string;
+  settings?: {
+    services?: Record<string, boolean>;
+    auth?: {
+      methods?: Record<string, boolean>;
+      security?: Record<string, any>;
+    };
+  };
+  functions?: Array<{
+    $id: string;
+    name: string;
+    runtime: string;
+    entrypoint?: string;
+    path?: string;
+    commands?: string;
+    events?: string[];
+  }>;
+  // Legacy Collections API support
+  databases?: Array<{
+    $id: string;
+    name: string;
+    enabled?: boolean;
+  }>;
+  collections?: Array<{
+    $id: string;
+    $permissions?: string[];
+    databaseId: string;
+    name: string;
+    enabled?: boolean;
+    documentSecurity?: boolean;
+    attributes: Array<{
+      key: string;
+      type: string;
+      required?: boolean;
+      array?: boolean;
+      size?: number;
+      default?: any;
+      encrypt?: boolean;
+      [key: string]: any;
+    }>;
+    indexes?: Array<{
+      key: string;
+      type: string;
+      attributes: string[];
+      orders?: string[];
+    }>;
+  }>;
+  // TablesDB API support
+  tablesDB?: Array<{
+    $id: string;
+    name: string;
+    enabled?: boolean;
+  }>;
+  tables?: Array<{
+    $id: string;
+    $permissions?: string[];
+    databaseId: string;
+    name: string;
+    enabled?: boolean;
+    rowSecurity?: boolean;
+    columns: Array<{
+      key: string;
+      type: string;
+      required?: boolean;
+      array?: boolean;
+      size?: number;
+      default?: any;
+      encrypt?: boolean;
+      unique?: boolean;
+      [key: string]: any;
+    }>;
+    indexes?: Array<{
+      key: string;
+      type: string;
+      attributes: string[];
+      orders?: string[];
+    }>;
+  }>;
+  buckets?: Array<{
+    bucketId?: string;
+    $id?: string;
+    name: string;
+    maximumFileSize?: number;
+    allowedFileExtensions?: string[];
+    encryption?: boolean;
+    antiVirus?: boolean;
+    [key: string]: any;
+  }>;
+}
+
+/**
+ * Find appwrite.json or appwrite.config.json in current directory or parents
+ */
+export function findAppwriteProjectConfig(startDir: string = process.cwd()): string | null {
+  const configNames = ["appwrite.json", "appwrite.config.json"];
+  let currentDir = startDir;
+
+  // Search up to 5 levels up the directory tree
+  for (let i = 0; i < 5; i++) {
+    for (const configName of configNames) {
+      const configPath = join(currentDir, configName);
+      if (existsSync(configPath)) {
+        return configPath;
+      }
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break; // Reached filesystem root
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
+/**
+ * Load and parse appwrite project configuration
+ */
+export function loadAppwriteProjectConfig(configPath?: string): AppwriteProjectConfig | null {
+  let actualConfigPath = configPath;
+
+  if (!actualConfigPath) {
+    actualConfigPath = findAppwriteProjectConfig() || undefined;
+  }
+
+  if (!actualConfigPath || !existsSync(actualConfigPath)) {
+    return null;
+  }
+
+  try {
+    const configContent = readFileSync(actualConfigPath, "utf-8");
+    const config = JSON.parse(configContent) as AppwriteProjectConfig;
+
+    // Validate required fields
+    if (!config.projectId) {
+      MessageFormatter.warning(
+        `Appwrite project config missing required 'projectId' field: ${actualConfigPath}`,
+        { prefix: "ProjectConfig" }
+      );
+      return null;
+    }
+
+    return config;
+  } catch (error) {
+    MessageFormatter.error(
+      `Failed to parse Appwrite project config: ${actualConfigPath}`,
+      error instanceof Error ? error : new Error(String(error)),
+      { prefix: "ProjectConfig" }
+    );
+    return null;
+  }
+}
+
+/**
+ * Detect API mode from project configuration
+ */
+export function detectApiModeFromProject(projectConfig: AppwriteProjectConfig): "legacy" | "tablesdb" | "auto" {
+  // If both are present, prefer TablesDB (newer)
+  if (projectConfig.tablesDB && projectConfig.tables) {
+    return "tablesdb";
+  }
+
+  // If only legacy structure is present
+  if (projectConfig.databases && projectConfig.collections) {
+    return "legacy";
+  }
+
+  // If only TablesDB structure is present
+  if (projectConfig.tablesDB && projectConfig.tables) {
+    return "tablesdb";
+  }
+
+  // Default to auto-detection
+  return "auto";
+}
+
+/**
+ * Convert project config to AppwriteConfig format
+ */
+export function projectConfigToAppwriteConfig(
+  projectConfig: AppwriteProjectConfig,
+  existingConfig?: Partial<AppwriteConfig>
+): Partial<AppwriteConfig> {
+  const apiMode = detectApiModeFromProject(projectConfig);
+
+  const baseConfig: Partial<AppwriteConfig> = {
+    ...existingConfig,
+    appwriteProject: projectConfig.projectId,
+    apiMode,
+  };
+
+  // Set endpoint if provided in project config
+  if (projectConfig.endpoint) {
+    baseConfig.appwriteEndpoint = projectConfig.endpoint;
+  }
+
+  // Convert databases (works for both legacy and TablesDB)
+  if (projectConfig.databases || projectConfig.tablesDB) {
+    const databases = projectConfig.databases || projectConfig.tablesDB || [];
+    baseConfig.databases = databases.map(db => ({
+      $id: db.$id,
+      name: db.name,
+      // Add basic bucket configuration if not exists
+      bucket: {
+        $id: `${db.$id}_bucket`,
+        name: `${db.name} Bucket`,
+        enabled: true,
+        maximumFileSize: 30000000,
+        allowedFileExtensions: [],
+        encryption: true,
+        antivirus: true,
+      },
+    }));
+  }
+
+  // Convert buckets if present
+  if (projectConfig.buckets) {
+    baseConfig.buckets = projectConfig.buckets.map(bucket => ({
+      $id: (bucket.bucketId || bucket.$id || `bucket_${Date.now()}`) as string,
+      name: bucket.name,
+      enabled: true,
+      maximumFileSize: bucket.maximumFileSize || 30000000,
+      allowedFileExtensions: bucket.allowedFileExtensions || [],
+      encryption: bucket.encryption ?? true,
+      antivirus: bucket.antiVirus ?? false,
+    }));
+  }
+
+  return baseConfig;
+}
+
+/**
+ * Get collection/table definitions from project config
+ */
+export function getCollectionsFromProject(projectConfig: AppwriteProjectConfig): any[] {
+  if (projectConfig.tables) {
+    // Convert TablesDB tables to collection format
+    return projectConfig.tables.map(table => ({
+      name: table.name,
+      $id: table.$id,
+      $permissions: table.$permissions || [],
+      documentSecurity: table.rowSecurity || false,
+      enabled: table.enabled !== false,
+      // Convert columns to attributes for compatibility
+      attributes: table.columns.map(col => ({
+        key: col.key,
+        type: col.type,
+        required: col.required,
+        array: col.array,
+        size: col.size,
+        default: col.default,
+        encrypted: col.encrypt,
+        unique: col.unique,
+      })),
+      indexes: table.indexes || [],
+      // Mark as coming from TablesDB for processing
+      _isFromTablesDir: true,
+    }));
+  }
+
+  if (projectConfig.collections) {
+    // Legacy collections format
+    return projectConfig.collections.map(collection => ({
+      name: collection.name,
+      $id: collection.$id,
+      $permissions: collection.$permissions || [],
+      documentSecurity: collection.documentSecurity || false,
+      enabled: collection.enabled !== false,
+      attributes: collection.attributes,
+      indexes: collection.indexes || [],
+      _isFromTablesDir: false,
+    }));
+  }
+
+  return [];
+}
+
+/**
+ * Check if project config indicates TablesDB usage
+ */
+export function isTablesDBProject(projectConfig: AppwriteProjectConfig): boolean {
+  return !!(projectConfig.tablesDB && projectConfig.tables);
+}
+
+/**
+ * Get the appropriate directory name based on project config
+ */
+export function getProjectDirectoryName(projectConfig: AppwriteProjectConfig): "tables" | "collections" {
+  return isTablesDBProject(projectConfig) ? "tables" : "collections";
+}

package/src/utils/retryFailedPromises.ts

@@ -1,4 +1,6 @@
 import type { Models } from "node-appwrite";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+import { logger } from "../shared/logging.js";
 
 export const retryFailedPromises = async (
   batch: Promise<Models.Document>[],
@@ -9,7 +11,7 @@ export const retryFailedPromises = async (
 
   results.forEach((result, index) => {
     if (result.status === "rejected") {
-      console.error("Promise rejected with reason:", result.reason);
+      logger.error("Promise rejected with reason:", { reason: result.reason });
       if (maxRetries > 0) {
         toRetry.push(batch[index]);
       }
@@ -17,7 +19,7 @@ export const retryFailedPromises = async (
   });
 
   if (toRetry.length > 0) {
-    console.log(`Retrying ${toRetry.length} promises`);
+    MessageFormatter.info(`Retrying ${toRetry.length} promises`, { prefix: "Retry" });
     return retryFailedPromises(toRetry, maxRetries - 1);
   } else {
     return results

package/src/utils/sessionAuth.ts

@@ -0,0 +1,230 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+
+/**
+ * Normalizes an endpoint URL by removing trailing slashes and converting to lowercase
+ */
+function normalizeEndpoint(url: string): string {
+  return url.replace(/\/+$/, "").toLowerCase();
+}
+
+export interface AppwriteSessionPrefs {
+  [projectId: string]: {
+    endpoint: string;
+    email: string;
+    cookie: string;
+  };
+}
+
+export interface SessionAuthInfo {
+  projectId: string;
+  endpoint: string;
+  sessionCookie: string;
+  email?: string;
+}
+
+/**
+ * Load session preferences from ~/.appwrite/prefs.json
+ */
+export function loadSessionPrefs(): AppwriteSessionPrefs | null {
+  try {
+    const prefsPath = join(homedir(), ".appwrite", "prefs.json");
+
+    if (!existsSync(prefsPath)) {
+      return null;
+    }
+
+    const prefsContent = readFileSync(prefsPath, "utf-8");
+    const prefs = JSON.parse(prefsContent) as AppwriteSessionPrefs;
+
+    return prefs;
+  } catch (error) {
+    MessageFormatter.warning(
+      "Failed to load Appwrite session preferences",
+      { prefix: "Session" }
+    );
+    return null;
+  }
+}
+
+/**
+ * Get session authentication info for a specific project
+ */
+export function getSessionAuth(projectId: string): SessionAuthInfo | null {
+  const prefs = loadSessionPrefs();
+
+  if (!prefs || !prefs[projectId]) {
+    return null;
+  }
+
+  const sessionData = prefs[projectId];
+
+  // Validate session data structure
+  if (!sessionData.endpoint || !sessionData.cookie) {
+    MessageFormatter.warning(
+      `Invalid session data for project ${projectId}`,
+      { prefix: "Session" }
+    );
+    return null;
+  }
+
+  return {
+    projectId,
+    endpoint: sessionData.endpoint,
+    sessionCookie: sessionData.cookie,
+    email: sessionData.email,
+  };
+}
+
+/**
+ * Check if a session cookie appears to be valid (enhanced validation)
+ */
+export function isValidSessionCookie(cookie: string): boolean {
+  if (!cookie || typeof cookie !== "string") {
+    return false;
+  }
+
+  // Trim whitespace
+  cookie = cookie.trim();
+
+  // Basic length check
+  if (cookie.length < 10) {
+    return false;
+  }
+
+  // Basic validation - Appwrite session cookies are typically JWT-like
+  // They should contain dots and be reasonably long
+  if (!cookie.includes(".")) {
+    return false;
+  }
+
+  // Check for obviously expired or malformed tokens
+  // JWT tokens typically have 3 parts separated by dots
+  const parts = cookie.split('.');
+  if (parts.length < 2) {
+    return false;
+  }
+
+  // Additional validation - ensure it's not obviously corrupted
+  // Should contain alphanumeric characters and common JWT characters
+  const validChars = /^[A-Za-z0-9._-]+$/;
+  if (!validChars.test(cookie)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Get all available sessions from prefs
+ */
+export function getAvailableSessions(): SessionAuthInfo[] {
+  const prefs = loadSessionPrefs();
+
+  if (!prefs) {
+    return [];
+  }
+
+  const sessions: SessionAuthInfo[] = [];
+
+  for (const [projectId, sessionData] of Object.entries(prefs)) {
+    if (sessionData.endpoint && sessionData.cookie && isValidSessionCookie(sessionData.cookie)) {
+      sessions.push({
+        projectId,
+        endpoint: sessionData.endpoint,
+        sessionCookie: sessionData.cookie,
+        email: sessionData.email,
+      });
+    }
+  }
+
+  return sessions;
+}
+
+/**
+ * Find session by endpoint and project combination
+ */
+export function findSessionByEndpointAndProject(
+  endpoint: string,
+  projectId: string
+): SessionAuthInfo | null {
+  const sessionAuth = getSessionAuth(projectId);
+
+  if (!sessionAuth) {
+    MessageFormatter.debug(
+      `No session found for project ${projectId}`,
+      { prefix: "Session" }
+    );
+    return null;
+  }
+
+  // Normalize endpoints for comparison (remove trailing slashes, etc.)
+  if (normalizeEndpoint(sessionAuth.endpoint) !== normalizeEndpoint(endpoint)) {
+    MessageFormatter.warning(
+      `Session endpoint mismatch for project ${projectId}:\n` +
+      `  Session endpoint: ${sessionAuth.endpoint}\n` +
+      `  Config endpoint:  ${endpoint}\n` +
+      `  Tip: Run 'appwrite login' to update session for this endpoint`,
+      { prefix: "Session" }
+    );
+    return null;
+  }
+
+  return sessionAuth;
+}
+
+/**
+ * Check if session authentication is available for a project configuration
+ */
+export function hasSessionAuth(endpoint: string, projectId: string): boolean {
+  const sessionAuth = findSessionByEndpointAndProject(endpoint, projectId);
+  return sessionAuth !== null && isValidSessionCookie(sessionAuth.sessionCookie);
+}
+
+/**
+ * Get detailed authentication status for debugging and error reporting
+ */
+export function getAuthenticationStatus(endpoint: string, projectId: string): {
+  hasValidSession: boolean;
+  sessionExists: boolean;
+  endpointMatches: boolean;
+  cookieValid: boolean;
+  sessionInfo?: SessionAuthInfo;
+  message: string;
+} {
+  const sessionAuth = getSessionAuth(projectId);
+
+  if (!sessionAuth) {
+    return {
+      hasValidSession: false,
+      sessionExists: false,
+      endpointMatches: false,
+      cookieValid: false,
+      message: `No session found for project ${projectId}. Run 'appwrite login' to authenticate.`
+    };
+  }
+
+  const endpointMatches = normalizeEndpoint(sessionAuth.endpoint) === normalizeEndpoint(endpoint);
+  const cookieValid = isValidSessionCookie(sessionAuth.sessionCookie);
+  const hasValidSession = endpointMatches && cookieValid;
+
+  let message = "";
+  if (!endpointMatches) {
+    message = `Session endpoint mismatch. Expected: ${endpoint}, Found: ${sessionAuth.endpoint}`;
+  } else if (!cookieValid) {
+    message = `Session cookie is invalid or expired for project ${projectId}`;
+  } else {
+    message = `Valid session found for ${sessionAuth.email || 'unknown user'}`;
+  }
+
+  return {
+    hasValidSession,
+    sessionExists: true,
+    endpointMatches,
+    cookieValid,
+    sessionInfo: sessionAuth,
+    message
+  };
+}