@njdamstra/appwrite-utils-cli 1.8.9

package/src/functions/fnConfigDiscovery.ts

@@ -0,0 +1,103 @@
+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 '@njdamstra/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

@@ -0,0 +1,271 @@
+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,
+} from "@njdamstra/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
+ * - 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 => event && typeof event === 'string' && event.trim().length > 0)
+    .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

@@ -0,0 +1,227 @@
+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

@@ -0,0 +1,54 @@
+# 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'
+}
+```