appwrite-utils-cli 1.9.7 → 1.12.0

package/src/functions/fnConfigDiscovery.ts

@@ -1,103 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import yaml from 'js-yaml';
-import { homedir } from 'node:os';
-import { AppwriteFunctionSchema, type AppwriteFunction } from 'appwrite-utils';
-import { shouldIgnoreDirectory } from '../utils/directoryUtils.js';
-import { MessageFormatter } from '../shared/messageFormatter.js';
-
-function findGitRoot(startDir: string): string {
-  let dir = path.resolve(startDir);
-  while (dir !== path.parse(dir).root) {
-    if (fs.existsSync(path.join(dir, '.git'))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return path.resolve(startDir);
-}
-
-function expandTilde(p: string): string {
-  if (!p) return p;
-  if (p === '~' || p.startsWith('~/')) return p.replace(/^~(?=$|\/|\\)/, homedir());
-  return p;
-}
-
-export function discoverFnConfigs(startDir: string): AppwriteFunction[] {
-  const root = findGitRoot(startDir);
-  const results: AppwriteFunction[] = [];
-
-  const visit = (dir: string, depth = 0) => {
-    if (depth > 5) return; // cap depth
-    const base = path.basename(dir);
-    if (shouldIgnoreDirectory(base)) return;
-    let entries: fs.Dirent[] = [];
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-
-    // Check for .fnconfig.yaml / .fnconfig.yml
-    for (const fname of ['.fnconfig.yaml', '.fnconfig.yml']) {
-      const cfgPath = path.join(dir, fname);
-      if (fs.existsSync(cfgPath)) {
-        try {
-          const raw = fs.readFileSync(cfgPath, 'utf8');
-          const data = yaml.load(raw) as any;
-          const parsed = AppwriteFunctionSchema.parse({
-            $id: data.id || data.$id,
-            name: data.name,
-            runtime: data.runtime,
-            execute: data.execute || [],
-            events: data.events || [],
-            schedule: data.schedule,
-            timeout: data.timeout,
-            enabled: data.enabled,
-            logging: data.logging,
-            entrypoint: data.entrypoint,
-            commands: data.commands,
-            scopes: data.scopes,
-            installationId: data.installationId,
-            providerRepositoryId: data.providerRepositoryId,
-            providerBranch: data.providerBranch,
-            providerSilentMode: data.providerSilentMode,
-            providerRootDirectory: data.providerRootDirectory,
-            templateRepository: data.templateRepository,
-            templateOwner: data.templateOwner,
-            templateRootDirectory: data.templateRootDirectory,
-            templateVersion: data.templateVersion,
-            specification: data.specification,
-            dirPath: data.dirPath,
-            predeployCommands: data.predeployCommands,
-            deployDir: data.deployDir,
-            ignore: data.ignore,
-          });
-
-          // Resolve dirPath relative to the config file directory
-          let dirPath = parsed.dirPath || '.';
-          dirPath = expandTilde(dirPath);
-          if (!path.isAbsolute(dirPath)) dirPath = path.resolve(path.dirname(cfgPath), dirPath);
-          const merged: AppwriteFunction = { ...parsed, dirPath };
-          results.push(merged);
-        } catch (e) {
-          MessageFormatter.warning(`Failed to parse ${cfgPath}: ${e instanceof Error ? e.message : String(e)}`, { prefix: 'Functions' });
-        }
-      }
-    }
-
-    for (const entry of entries) {
-      if (entry.isDirectory()) visit(path.join(dir, entry.name), depth + 1);
-    }
-  };
-
-  visit(root, 0);
-  return results;
-}
-
-export function mergeDiscoveredFunctions(
-  central: AppwriteFunction[] = [],
-  discovered: AppwriteFunction[] = []
-): AppwriteFunction[] {
-  const map = new Map<string, AppwriteFunction>();
-  for (const f of central) if (f?.$id) map.set(f.$id, f);
-  for (const f of discovered) if (f?.$id) map.set(f.$id, f); // discovered overrides
-  return Array.from(map.values());
-}
-

package/src/functions/methods.ts

@@ -1,284 +0,0 @@
-import {
-  AppwriteException,
-  Client,
-  Functions,
-  Query,
-  Runtime,
-} from "node-appwrite";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import fs from "node:fs";
-import {
-  type AppwriteFunction,
-  type FunctionScope,
-  type Specification,
-  type Runtime as AppwriteUtilsRuntime,
-  EventTypeSchema,
-} from "appwrite-utils";
-import chalk from "chalk";
-import { extract as extractTar } from "tar";
-import { MessageFormatter } from "../shared/messageFormatter.js";
-import { expandTildePath, normalizeFunctionName } from "./pathResolution.js";
-
-/**
- * Validates and filters events array for Appwrite functions
- * - Filters out empty/invalid strings
- * - Validates against EventTypeSchema
- * - Limits to 100 items maximum (Appwrite limit)
- * - Returns empty array if input is invalid
- */
-const validateEvents = (events?: string[]): string[] => {
-  if (!events || !Array.isArray(events)) return [];
-
-  return events
-    .filter(event => {
-      if (!event || typeof event !== 'string' || event.trim().length === 0) {
-        return false;
-      }
-      // Validate against EventTypeSchema
-      const result = EventTypeSchema.safeParse(event);
-      if (!result.success) {
-        MessageFormatter.warning(`Invalid event type "${event}" will be filtered out`, { prefix: "Functions" });
-        return false;
-      }
-      return true;
-    })
-    .slice(0, 100);
-};
-
-export const listFunctions = async (
-  client: Client,
-  queries?: string[],
-  search?: string
-) => {
-  const functions = new Functions(client);
-  const functionsList = await functions.list(queries, search);
-  return functionsList;
-};
-
-export const getFunction = async (client: Client, functionId: string) => {
-  const functions = new Functions(client);
-  const functionResponse = await functions.get(functionId);
-  return functionResponse;
-};
-
-export const downloadLatestFunctionDeployment = async (
-  client: Client,
-  functionId: string,
-  basePath: string = process.cwd()
-) => {
-  const functions = new Functions(client);
-  const functionInfo = await getFunction(client, functionId);
-  const functionDeployments = await functions.listDeployments(functionId, [
-    Query.orderDesc("$createdAt"),
-  ]);
-
-  if (functionDeployments.deployments.length === 0) {
-    throw new Error("No deployments found for function");
-  }
-
-  const latestDeployment = functionDeployments.deployments[0];
-  const deploymentData = await functions.getDeploymentDownload(
-    functionId,
-    latestDeployment.$id
-  );
-
-  // Create function directory using provided basePath
-  const functionDir = join(
-    basePath,
-    normalizeFunctionName(functionInfo.name)
-  );
-  await fs.promises.mkdir(functionDir, { recursive: true });
-
-  // Create temporary file for tar extraction
-  const tarPath = join(functionDir, "temp.tar.gz");
-  const uint8Array = new Uint8Array(deploymentData);
-  await fs.promises.writeFile(tarPath, uint8Array);
-
-  try {
-    // Extract tar file
-    extractTar({
-      C: functionDir,
-      file: tarPath,
-      sync: true,
-    });
-
-    return {
-      path: functionDir,
-      function: functionInfo,
-      deployment: latestDeployment,
-    };
-  } finally {
-    // Clean up tar file
-    await fs.promises.unlink(tarPath).catch(() => {});
-  }
-};
-
-export const deleteFunction = async (client: Client, functionId: string) => {
-  const functions = new Functions(client);
-  const functionResponse = await functions.delete(functionId);
-  return functionResponse;
-};
-
-export const createFunction = async (
-  client: Client,
-  functionConfig: AppwriteFunction
-) => {
-  const functions = new Functions(client);
-  const functionResponse = await functions.create(
-    functionConfig.$id,
-    functionConfig.name,
-    functionConfig.runtime as Runtime,
-    functionConfig.execute,
-    validateEvents(functionConfig.events),
-    functionConfig.schedule,
-    functionConfig.timeout,
-    functionConfig.enabled,
-    functionConfig.logging,
-    functionConfig.entrypoint,
-    functionConfig.commands,
-    functionConfig.scopes,
-    functionConfig.installationId,
-    functionConfig.providerRepositoryId,
-    functionConfig.providerBranch,
-    functionConfig.providerSilentMode,
-    functionConfig.providerRootDirectory
-  );
-  return functionResponse;
-};
-
-export const updateFunctionSpecifications = async (
-  client: Client,
-  functionId: string,
-  specification: Specification
-) => {
-  const curFunction = await listFunctions(client, [
-    Query.equal("$id", functionId),
-  ]);
-  if (curFunction.functions.length === 0) {
-    throw new Error("Function not found");
-  }
-  const functionFound = curFunction.functions[0];
-  try {
-    const functionResponse = await updateFunction(client, {
-      ...functionFound,
-      runtime: functionFound.runtime as AppwriteUtilsRuntime,
-      scopes: functionFound.scopes as FunctionScope[],
-      specification: specification,
-    });
-    return functionResponse;
-  } catch (error) {
-    if (
-      error instanceof AppwriteException &&
-      error.message.includes("Invalid `specification`")
-    ) {
-      MessageFormatter.error(
-        "Error updating function specifications, please try setting the env variable `_FUNCTIONS_CPUS` and `_FUNCTIONS_RAM` to non-zero values",
-        undefined,
-        { prefix: "Functions" }
-      );
-    } else {
-      MessageFormatter.error("Error updating function specifications", error instanceof Error ? error : undefined, { prefix: "Functions" });
-      throw error;
-    }
-  }
-};
-
-export const listSpecifications = async (client: Client) => {
-  const functions = new Functions(client);
-  const specifications = await functions.listSpecifications();
-  return specifications;
-};
-
-export const listFunctionDeployments = async (
-  client: Client,
-  functionId: string,
-  queries?: string[]
-) => {
-  const functions = new Functions(client);
-  const deployments = await functions.listDeployments(functionId, queries);
-  return deployments;
-};
-
-export const updateFunction = async (
-  client: Client,
-  functionConfig: AppwriteFunction
-) => {
-  const functions = new Functions(client);
-  const functionResponse = await functions.update(
-    functionConfig.$id,
-    functionConfig.name,
-    functionConfig.runtime as Runtime,
-    functionConfig.execute,
-    validateEvents(functionConfig.events),
-    functionConfig.schedule,
-    functionConfig.timeout,
-    functionConfig.enabled,
-    functionConfig.logging,
-    functionConfig.entrypoint,
-    functionConfig.commands,
-    functionConfig.scopes,
-    functionConfig.installationId,
-    functionConfig.providerRepositoryId,
-    functionConfig.providerBranch,
-    functionConfig.providerSilentMode,
-    functionConfig.providerRootDirectory,
-    functionConfig.specification
-  );
-  return functionResponse;
-};
-
-export const createFunctionTemplate = async (
-  templateType: "typescript-node" | "uv" | "count-docs-in-collection" | "hono-typescript",
-  functionName: string,
-  basePath: string = "./functions"
-) => {
-  const expandedBasePath = expandTildePath(basePath);
-  const functionPath = join(expandedBasePath, functionName);
-  const currentFileUrl = import.meta.url;
-  const currentDir = dirname(fileURLToPath(currentFileUrl));
-  const templatesPath = join(currentDir, "templates", templateType);
-
-  // Create function directory
-  await fs.promises.mkdir(functionPath, { recursive: true });
-
-  // Copy template files recursively
-  const copyTemplateFiles = async (sourcePath: string, targetPath: string) => {
-    const entries = await fs.promises.readdir(sourcePath, {
-      withFileTypes: true,
-    });
-
-    for (const entry of entries) {
-      const srcPath = join(sourcePath, entry.name);
-      const destPath = join(targetPath, entry.name);
-
-      if (entry.isDirectory()) {
-        await fs.promises.mkdir(destPath, { recursive: true });
-        await copyTemplateFiles(srcPath, destPath);
-      } else {
-        let content = await fs.promises.readFile(srcPath, "utf-8");
-
-        // Replace template variables
-        content = content
-          .replace(/\{\{functionName\}\}/g, functionName)
-          .replace(/\{\{databaseId\}\}/g, "{{databaseId}}")
-          .replace(/\{\{collectionId\}\}/g, "{{collectionId}}");
-
-        await fs.promises.writeFile(destPath, content);
-      }
-    }
-  };
-
-  try {
-    await copyTemplateFiles(templatesPath, functionPath);
-    MessageFormatter.success(
-      `Created ${templateType} function template at ${functionPath}`,
-      { prefix: "Functions" }
-    );
-  } catch (error) {
-    MessageFormatter.error("Failed to create function template", error instanceof Error ? error : undefined, { prefix: "Functions" });
-    throw error;
-  }
-
-  return functionPath;
-};

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/functions/templates/count-docs-in-collection/README.md

@@ -1,54 +0,0 @@
-# Count Documents in Collection Function
-
-A utility function that accurately counts documents in an Appwrite collection, even when there are more than 5,000 documents.
-
-## Features
-- Handles collections with any number of documents
-- Supports filtering using Appwrite queries
-- Uses efficient binary search algorithm for large collections
-- Provides detailed logging during the counting process
-
-## Structure
-- `src/main.ts`: Main function implementation with counting logic
-- `src/request.ts`: Request validation schema using Zod
-
-## Usage
-Send a POST request with:
-```json
-{
-  "databaseId": "your-database-id",
-  "collectionId": "your-collection-id",
-  "queries": [Query.orderDesc("$createdAt"), Query.contains("name", "John")] // Or put the string array from after this, they are the same
-}
-```
-
-## Response
-```json
-{
-  "success": true,
-  "count": 12345
-}
-```
-
-## Development
-1. Install dependencies: `npm|yarn|bun install`
-2. Build: `npm|yarn|bun run build`
-3. Deploy: Function will be built automatically during deployment
-
-## Deployment
-Make sure it's inside `appwriteConfig.ts` functions array, and if you want to build it FIRST, before Appwrite (using your system), you can
-add the `predeployCommands` to the function in `appwriteConfig.ts`.
-
-## Example Config
-```typescript
-{
-  $id: 'count-docs',
-  name: 'Count Documents',
-  runtime: 'node-18.0',
-  path: 'functions/count-docs',
-  entrypoint: './main.js',
-  execute: ['any'],
-  predeployCommands: ['npm install', 'npm run build'],
-  deployDir: './dist'
-}
-```

package/src/functions/templates/count-docs-in-collection/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "{{functionName}}",
-  "version": "1.0.0",
-  "description": "Appwrite function to count documents in a collection",
-  "main": "src/main.ts",
-  "type": "module",
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/main.js",
-    "dev": "tsx src/main.ts"
-  },
-  "dependencies": {
-    "node-appwrite": "^13.0.0",
-    "appwrite-utils": "latest",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "tsx": "^4.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}