@njdamstra/appwrite-utils-cli 1.8.9 → 1.10.1

package/src/functions/pathResolution.ts

@@ -1,227 +0,0 @@
-import { existsSync, statSync, readdirSync } from 'node:fs';
-import { join, resolve, isAbsolute } from 'node:path';
-import { homedir } from 'node:os';
-import { MessageFormatter } from '../shared/messageFormatter.js';
-import { logger } from '../shared/logging.js';
-
-/**
- * Expands tilde (~) in paths to the user's home directory
- * @param pathStr - Path string that may contain ~
- * @returns Expanded path with home directory
- */
-export function expandTildePath(pathStr: string): string {
-  if (!pathStr) return pathStr;
-
-  if (pathStr.startsWith('~/') || pathStr === '~') {
-    const expandedPath = pathStr.replace(/^~(?=$|\/|\\)/, homedir());
-    logger.debug('Expanded tilde path', { original: pathStr, expanded: expandedPath });
-    return expandedPath;
-  }
-
-  return pathStr;
-}
-
-/**
- * Normalizes function name to standard format (lowercase, dashes instead of spaces)
- * @param name - Function name to normalize
- * @returns Normalized function name
- */
-export function normalizeFunctionName(name: string): string {
-  if (!name) return name;
-
-  const normalized = name.toLowerCase().replace(/\s+/g, '-');
-
-  if (normalized !== name) {
-    logger.debug('Normalized function name', { original: name, normalized });
-  }
-
-  return normalized;
-}
-
-/**
- * Validates that a directory exists and contains function markers
- * @param dirPath - Directory path to validate
- * @returns True if directory is a valid function directory
- */
-export function validateFunctionDirectory(dirPath: string): boolean {
-  try {
-    // Check if directory exists
-    if (!existsSync(dirPath)) {
-      logger.debug('Directory does not exist', { dirPath });
-      return false;
-    }
-
-    // Check if it's actually a directory
-    const stats = statSync(dirPath);
-    if (!stats.isDirectory()) {
-      logger.debug('Path is not a directory', { dirPath });
-      return false;
-    }
-
-    // Check for function markers
-    const contents = readdirSync(dirPath);
-    const hasPackageJson = contents.includes('package.json');
-    const hasPyprojectToml = contents.includes('pyproject.toml');
-    const hasSrcDir = contents.includes('src');
-
-    const isValid = hasPackageJson || hasPyprojectToml || hasSrcDir;
-
-    logger.debug('Function directory validation', {
-      dirPath,
-      isValid,
-      markers: {
-        hasPackageJson,
-        hasPyprojectToml,
-        hasSrcDir
-      }
-    });
-
-    return isValid;
-  } catch (error) {
-    logger.debug('Error validating function directory', {
-      dirPath,
-      error: error instanceof Error ? error.message : String(error)
-    });
-    return false;
-  }
-}
-
-/**
- * Helper function to search for function in standard locations
- * @param configDirPath - Directory where config file is located
- * @param normalizedName - Normalized function name
- * @returns First valid function directory path or undefined
- */
-export function findFunctionInStandardLocations(
-  configDirPath: string,
-  normalizedName: string
-): string | undefined {
-  const searchPaths = [
-    // Same directory as config
-    join(configDirPath, 'functions', normalizedName),
-    // Parent directory of config
-    join(configDirPath, '..', 'functions', normalizedName),
-    // Current working directory
-    join(process.cwd(), 'functions', normalizedName),
-  ];
-
-  logger.debug('Searching for function in standard locations', {
-    normalizedName,
-    configDirPath,
-    searchPaths
-  });
-
-  for (const searchPath of searchPaths) {
-    const resolvedPath = resolve(searchPath);
-    logger.debug('Checking search path', { searchPath, resolvedPath });
-
-    if (validateFunctionDirectory(resolvedPath)) {
-      logger.debug('Found function in standard location', { resolvedPath });
-      return resolvedPath;
-    }
-  }
-
-  logger.debug('Function not found in any standard location', { normalizedName });
-  return undefined;
-}
-
-/**
- * Resolves the absolute path to a function directory
- * Handles multiple resolution strategies with proper priority
- *
- * @param functionName - Name of the function
- * @param configDirPath - Directory where config file is located
- * @param dirPath - Optional explicit dirPath from config
- * @param explicitPath - Optional path passed as parameter (highest priority)
- * @returns Absolute path to the function directory
- * @throws Error if function directory cannot be found or is invalid
- */
-export function resolveFunctionDirectory(
-  functionName: string,
-  configDirPath: string,
-  dirPath?: string,
-  explicitPath?: string
-): string {
-  logger.debug('Resolving function directory', {
-    functionName,
-    configDirPath,
-    dirPath,
-    explicitPath
-  });
-
-  const normalizedName = normalizeFunctionName(functionName);
-
-  // Priority 1: Explicit path parameter (highest priority)
-  if (explicitPath) {
-    logger.debug('Using explicit path parameter');
-    const expandedPath = expandTildePath(explicitPath);
-    const resolvedPath = isAbsolute(expandedPath)
-      ? expandedPath
-      : resolve(process.cwd(), expandedPath);
-
-    if (!validateFunctionDirectory(resolvedPath)) {
-      const errorMsg = `Explicit path is not a valid function directory: ${resolvedPath}`;
-      logger.error(errorMsg);
-      MessageFormatter.error('Invalid function directory', errorMsg, { prefix: 'Path Resolution' });
-      throw new Error(errorMsg);
-    }
-
-    logger.debug('Resolved using explicit path', { resolvedPath });
-    MessageFormatter.debug(`Resolved function directory using explicit path: ${resolvedPath}`, undefined, { prefix: 'Path Resolution' });
-    return resolvedPath;
-  }
-
-  // Priority 2: dirPath from config (relative to config location)
-  if (dirPath) {
-    logger.debug('Using dirPath from config');
-    const expandedPath = expandTildePath(dirPath);
-    const resolvedPath = isAbsolute(expandedPath)
-      ? expandedPath
-      : resolve(configDirPath, expandedPath);
-
-    if (!validateFunctionDirectory(resolvedPath)) {
-      const errorMsg = `Config dirPath is not a valid function directory: ${resolvedPath}`;
-      logger.error(errorMsg);
-      MessageFormatter.error('Invalid function directory', errorMsg, { prefix: 'Path Resolution' });
-      throw new Error(errorMsg);
-    }
-
-    logger.debug('Resolved using config dirPath', { resolvedPath });
-    MessageFormatter.debug(`Resolved function directory using config dirPath: ${resolvedPath}`, undefined, { prefix: 'Path Resolution' });
-    return resolvedPath;
-  }
-
-  // Priority 3: Search standard locations
-  logger.debug('Searching standard locations for function');
-  const foundPath = findFunctionInStandardLocations(configDirPath, normalizedName);
-
-  if (foundPath) {
-    logger.debug('Resolved using standard location search', { foundPath });
-    MessageFormatter.debug(`Found function directory in standard location: ${foundPath}`, undefined, { prefix: 'Path Resolution' });
-    return foundPath;
-  }
-
-  // Priority 4: Not found - throw error
-  const searchedLocations = [
-    join(configDirPath, 'functions', normalizedName),
-    join(configDirPath, '..', 'functions', normalizedName),
-    join(process.cwd(), 'functions', normalizedName),
-  ];
-
-  const errorMsg = `Function directory not found for '${functionName}' (normalized: '${normalizedName}'). ` +
-    `Searched locations:\n${searchedLocations.map(p => `  - ${p}`).join('\n')}`;
-
-  logger.error('Function directory not found', {
-    functionName,
-    normalizedName,
-    searchedLocations
-  });
-
-  MessageFormatter.error(
-    'Function directory not found',
-    errorMsg,
-    { prefix: 'Path Resolution' }
-  );
-
-  throw new Error(errorMsg);
-}

package/src/shared/attributeMapper.ts

@@ -1,229 +0,0 @@
-import type { CreateAttributeParams, UpdateAttributeParams } from "../adapters/DatabaseAdapter.js";
-import type { Attribute } from "@njdamstra/appwrite-utils";
-
-function ensureNumber(n: any): number | undefined {
-  if (n === null || n === undefined) return undefined;
-  const num = Number(n);
-  return Number.isFinite(num) ? num : undefined;
-}
-
-/**
- * Map a schema Attribute into DatabaseAdapter CreateAttributeParams
- * Only includes fields valid for the specific type to satisfy TS unions.
- * Also normalizes min/max ordering for numeric types to avoid server errors.
- */
-export function mapToCreateAttributeParams(
-  attr: Attribute,
-  base: { databaseId: string; tableId: string }
-): CreateAttributeParams {
-  const type = String((attr as any).type || "").toLowerCase();
-  const required = !!(attr as any).required;
-  const array = !!(attr as any).array;
-  const xdefault = (attr as any).xdefault;
-  const encrypt = (attr as any).encrypt;
-
-  // Numeric helpers
-  const rawMin = ensureNumber((attr as any).min);
-  const rawMax = ensureNumber((attr as any).max);
-  let min = rawMin;
-  let max = rawMax;
-  if (min !== undefined && max !== undefined && min >= max) {
-    // Swap to satisfy server-side validation
-    const tmp = min;
-    min = Math.min(min, max);
-    max = Math.max(tmp, max);
-    if (min === max) {
-      // If still equal, unset max to avoid error
-      max = undefined;
-    }
-  }
-
-  switch (type) {
-    case "string":
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        size: (attr as any).size ?? 255,
-        required,
-        default: xdefault,
-        array,
-        encrypt: !!encrypt,
-      };
-
-    case "integer":
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        required,
-        default: xdefault,
-        array,
-        min,
-        max,
-      };
-
-    case "double":
-    case "float":
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        required,
-        default: xdefault,
-        array,
-        min,
-        max,
-      };
-
-    case "boolean":
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        required,
-        default: xdefault,
-        array,
-      };
-
-    case "datetime":
-    case "email":
-    case "ip":
-    case "url":
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        required,
-        default: xdefault,
-        array,
-      };
-
-    case "enum":
-      {
-        const elements = (attr as any).elements;
-        if (!Array.isArray(elements) || elements.length === 0) {
-          // Creating an enum without elements is invalid – fail fast with clear messaging
-          throw new Error(
-            `Enum attribute '${(attr as any).key}' requires a non-empty 'elements' array for creation`
-          );
-        }
-      }
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        required,
-        default: xdefault,
-        array,
-        elements: (attr as any).elements,
-      };
-
-    case "relationship": {
-      // Relationship attributes require related collection and metadata
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        relatedCollection: (attr as any).relatedCollection,
-        relationType: (attr as any).relationType,
-        twoWay: (attr as any).twoWay,
-        twoWayKey: (attr as any).twoWayKey,
-        onDelete: (attr as any).onDelete,
-        side: (attr as any).side,
-      } as unknown as CreateAttributeParams;
-    }
-
-    default:
-      return {
-        databaseId: base.databaseId,
-        tableId: base.tableId,
-        key: attr.key,
-        type,
-        required,
-      } as CreateAttributeParams;
-  }
-}
-
-/**
- * Map a schema Attribute into DatabaseAdapter UpdateAttributeParams
- * Omits fields that are not explicitly provided, and guards enum updates
- * so we never send an empty elements array (preserve existing on server).
- */
-export function mapToUpdateAttributeParams(
-  attr: Attribute,
-  base: { databaseId: string; tableId: string }
-): UpdateAttributeParams {
-  const type = String((attr as any).type || "").toLowerCase();
-  const params: UpdateAttributeParams = {
-    databaseId: base.databaseId,
-    tableId: base.tableId,
-    key: (attr as any).key,
-  };
-
-  const setIfDefined = <K extends keyof UpdateAttributeParams>(
-    key: K,
-    value: UpdateAttributeParams[K]
-  ) => {
-    if (value !== undefined) (params as any)[key] = value;
-  };
-
-  // Common fields
-  setIfDefined("type", type);
-  setIfDefined("required", (attr as any).required);
-  // Only send default if explicitly provided and not on required
-  if (!(attr as any).required && (attr as any).xdefault !== undefined) {
-    setIfDefined("default", (attr as any).xdefault as any);
-  }
-  setIfDefined("array", (attr as any).array);
-  // encrypt only applies to string types
-  if (type === "string") setIfDefined("encrypt", (attr as any).encrypt);
-
-  // Numeric normalization
-  const toNum = (n: any) => (n === null || n === undefined ? undefined : (Number(n)));
-  let min = toNum((attr as any).min);
-  let max = toNum((attr as any).max);
-  if (min !== undefined && max !== undefined && min >= max) {
-    const tmp = min;
-    min = Math.min(min, max);
-    max = Math.max(tmp, max);
-    if (min === max) max = undefined;
-  }
-
-  switch (type) {
-    case "string":
-      setIfDefined("size", (attr as any).size);
-      break;
-    case "integer":
-    case "float":
-    case "double":
-      setIfDefined("min", min);
-      setIfDefined("max", max);
-      break;
-    case "enum": {
-      const elements = (attr as any).elements;
-      if (Array.isArray(elements) && elements.length > 0) {
-        // Only include when non-empty; otherwise preserve existing on server
-        setIfDefined("elements", elements as string[]);
-      }
-      break;
-    }
-    case "relationship": {
-      setIfDefined("relatedCollection", (attr as any).relatedCollection);
-      setIfDefined("relationType", (attr as any).relationType);
-      setIfDefined("twoWay", (attr as any).twoWay);
-      setIfDefined("twoWayKey", (attr as any).twoWayKey);
-      setIfDefined("onDelete", (attr as any).onDelete);
-      break;
-    }
-  }
-
-  return params;
-}

package/src/shared/errorUtils.ts

@@ -1,110 +0,0 @@
-/**
- * Shared error handling utilities for consistent error processing
- */
-
-/**
- * Extracts error message from unknown error type
- * @param error - Error of unknown type
- * @returns String error message
- */
-export function getErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/**
- * Normalizes unknown error to Error instance
- * @param error - Error of unknown type
- * @returns Normalized Error object
- */
-export function normalizeError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-/**
- * Checks if error is a conflict error (409)
- * @param error - Error object to check
- * @returns True if error is a conflict (duplicate resource)
- */
-export function isConflictError(error: any): boolean {
-  return error?.code === 409 || (error?.message?.toLowerCase().includes('already exists') ?? false);
-}
-
-/**
- * Checks if error is a Cloudflare error (522)
- * @param error - Error object to check
- * @returns True if error is from Cloudflare connection timeout
- */
-export function isCloudflareError(error: any): boolean {
-  return error?.code === 522 || error?.code === "522";
-}
-
-/**
- * Checks if error is authentication/authorization related
- * @param error - Error object to check
- * @returns True if error is auth-related (401, 403)
- */
-export function isAuthError(error: any): boolean {
-  const code = error?.code;
-  return code === 401 || code === 403 || code === "401" || code === "403";
-}
-
-/**
- * Error categorization helpers for smart fallback logic
- */
-
-/**
- * Checks if an error is retryable (network issues, rate limits, etc.)
- * @param errorMessage - Error message to check
- * @returns True if error is retryable
- */
-export function isRetryableError(errorMessage: string): boolean {
-  const retryableErrors = [
-    "rate limit",
-    "timeout",
-    "network",
-    "temporary",
-    "503",
-    "502",
-    "429"
-  ];
-  return retryableErrors.some(error =>
-    errorMessage.toLowerCase().includes(error)
-  );
-}
-
-/**
- * Checks if an error indicates bulk operations are not supported
- * @param errorMessage - Error message to check
- * @returns True if bulk operations not supported
- */
-export function isBulkNotSupportedError(errorMessage: string): boolean {
-  const notSupportedErrors = [
-    "method not found",
-    "not implemented",
-    "unsupported",
-    "not available",
-    "404"
-  ];
-  return notSupportedErrors.some(error =>
-    errorMessage.toLowerCase().includes(error)
-  );
-}
-
-/**
- * Checks if an error is critical (authentication, authorization, permissions)
- * @param errorMessage - Error message to check
- * @returns True if error is critical
- */
-export function isCriticalError(errorMessage: string): boolean {
-  const criticalErrors = [
-    "authentication",
-    "authorization",
-    "permission",
-    "forbidden",
-    "401",
-    "403"
-  ];
-  return criticalErrors.some(error =>
-    errorMessage.toLowerCase().includes(error)
-  );
-}