appwrite-utils-cli 1.7.9 → 1.8.1

package/CHANGELOG.md

@@ -1,199 +1,14 @@
-# Changelog
-
-All notable changes to the appwrite-utils-cli package will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.6.1] - 2025-10-02
-
-### Changed
-- **Code Organization**: Major refactoring to improve maintainability
-  - Extracted wipe operations into dedicated module (501 lines)
-  - Extracted transfer operations into dedicated module (516 lines)
-  - Extracted config discovery logic into separate file (502 lines)
-  - Split interactive CLI into 5 focused command modules (1,595 lines total)
-  - Reduced large file sizes by 30-60% while maintaining all functionality
-- **Logging Standardization**: Unified logging across entire codebase
-  - Replaced ~500 console.* calls with MessageFormatter
-  - Consistent prefixes and formatting for better debugging
-  - Integrated with Winston structured logging
-- **New Utilities**: Added shared utility modules for better code reuse
-  - errorUtils.ts for centralized error handling
-  - directoryUtils.ts for file system operations
-  - typeGuards.ts for TypeScript type safety
-  - pathResolvers.ts for consistent path resolution
-
-## [1.6.0] - 2025-01-27
-
-### Added
-- **Session Authentication Integration**: Complete integration with Appwrite CLI session authentication
-  - New CLI flags: `--use-session`, `--session`, `--sessionCookie` for flexible authentication
-  - Automatic detection and usage of sessions from `~/.appwrite/prefs.json`
-  - Priority authentication system: explicit session → session from prefs → API key → error
-  - Enhanced error messages with available session listing and login guidance
-  - Seamless integration maintaining backward compatibility with API key workflows
-
-- **Native Project Configuration Support**: Full support for appwrite.json/appwrite.config.json files
-  - Automatic project configuration detection and loading from current directory tree
-  - Support for both Collections and TablesDB project formats from official Appwrite CLI
-  - Enhanced project context awareness for better tooling integration
-  - Conversion between project config and internal AppwriteConfig formats
-  - Priority system: CLI args → project config → YAML config → interactive prompt
-
-- **Intelligent Version-Aware Setup**: Enhanced setup command with smart detection
-  - **Project-First Detection**: Automatically detects project type from existing appwrite.json
-  - **Session-Powered Version Detection**: Uses session auth for server version checking when available
-  - **Context-Aware Templates**: Generates tables/columns templates for TablesDB (1.8.0+)
-  - **Legacy Support**: Generates collections/attributes templates for older versions
-  - **Smart Schema Generation**: Creates appropriate JSON schemas (table.schema.json vs collection.schema.json)
-  - **Enhanced Examples**: TablesDB templates include unique constraints and row-level security features
-
-- **Enhanced Client Creation**: Completely overhauled authentication flow
-  - New `getClientWithAuth()` function with intelligent fallback system
-  - Session validation and endpoint matching for security
-  - Enhanced `UtilsController` with session authentication support
-  - Automatic session discovery when no API key provided
-  - Clear authentication method logging and error reporting
-
-- **Hono-TypeScript Function Template**: New web framework template for modern API development
-  - Complete Hono.dev integration with Appwrite functions
-  - Request/response adapters for seamless Appwrite-Hono bridge
-  - Built-in middleware for logging, error handling, and context injection
-  - Example API endpoints with database operations and authentication
-  - Comprehensive documentation and usage examples
-
-- **Enhanced Function Templates**: Improved TypeScript and Python templates
-  - Complete Pydantic models for Python functions with proper type hints
-  - Enhanced Zod schemas for TypeScript functions with full validation
-  - Better error handling and context validation in templates
-  - Updated dependencies (Hono, Zod, Pydantic) in template configurations
-
-- **Dual Collections/Tables Support**: Full support for both legacy and TablesDB APIs
-  - Enhanced YAML loading from both `collections/` and `tables/` directories simultaneously
-  - Automatic conflict detection and resolution between folder structures
-  - Version-aware folder selection based on Appwrite API detection
-  - Backward compatibility with existing projects
-
-- **Interactive CLI Enhancements**: Improved user experience and database association
-  - Better collection/table selection with type indicators (🟢 Collection, 🔵 Table)
-  - Enhanced database filtering using optional `databaseId` for tables
-  - Improved prompts and contextual information display
-  - Better organization of mixed collection/table scenarios
-
-- **Configuration Validation & Migration**: Comprehensive validation and migration tools
-  - New CLI flags: `--validate`, `--validate-strict`, `--migrate-collections-to-tables`
-  - Configuration validation with detailed error reporting and suggestions
-  - Multiple migration strategies for different project needs
-  - Integration with config loading for automatic validation
-
-- **Enhanced Sync Operations**: Fixed and improved sync-from-Appwrite functionality
-  - **Fixed Database Syncing**: Remote databases now properly sync into `config.yaml`
-  - **Version-Aware YAML Generation**: Correct schema references and folder selection
-  - **Improved Error Handling**: Better user feedback and error recovery
-  - **Enhanced Logging**: Comprehensive operation tracking and debugging
-
-### Changed
-- **Authentication Priority**: Complete overhaul of authentication handling throughout CLI
-  - Session authentication now preferred over API key when available
-  - Enhanced error messages guide users to proper authentication setup
-  - Better integration with existing Appwrite CLI workflows
-  - Maintained full backward compatibility with existing projects
-
-- **Setup Command Experience**: Major improvements to project initialization
-  - Intelligent detection provides better user feedback about project type
-  - Version-aware terminology throughout setup process
-  - Enhanced console output with detection source information
-  - Better guidance for TablesDB features and capabilities
-
-- **Configuration Loading**: Enhanced to work with multiple configuration sources
-  - Project configuration loading from appwrite.json files
-  - Better conflict resolution between different config sources
-  - Enhanced validation and error handling for mixed scenarios
-
-- **Enhanced Logging Infrastructure**: Comprehensive logging throughout the CLI
-  - Structured JSON logging with operation context and timing
-  - Version detection and adapter selection logging
-  - Attribute min/max value processing logs with before/after values
-  - Performance timing for bottleneck identification
-
-- **Improved Template System**: Better function template organization and options
-  - Added "TypeScript with Hono Web Framework" option to CLI
-  - Enhanced template variable replacement system
-  - Better template defaults and configuration
-  - Improved template documentation and examples
-
-### Fixed
-- **Authentication Error Handling**: Resolved issues with missing authentication
-  - Better fallback logic when session authentication unavailable
-  - Clear error messages with actionable guidance
-  - Proper handling of invalid or expired session cookies
-  - Enhanced validation of authentication methods
-
-- **Type Safety**: Resolved TypeScript compilation issues
-  - Fixed session authentication type definitions
-  - Proper null/undefined handling in project configuration
-  - Enhanced type inference throughout authentication flow
-  - Better error message types and interfaces
-
-- **Version Detection**: Improved reliability of server version detection
-  - Better error handling when version detection fails
-  - Enhanced fallback mechanisms for offline scenarios
-  - Improved session-based version detection accuracy
-
-- **Integer/Float Min/Max Handling**: Resolved issues with extreme values in attribute creation
-  - Implemented 10 billion threshold logic for min/max values
-  - Proper undefined value handling for Appwrite API compatibility
-  - Consistent normalization between create and update operations
-  - Better comparison logic for determining when updates are needed
-
-- **Collection Re-pushing Prevention**: Eliminated unnecessary collection processing
-  - Intelligent state management prevents duplicate operations
-  - Surgical queue processing for relationship attributes only
-  - Better cache management and state tracking
-  - Performance improvements for large collection push operations
-
-- **Version-Aware Attribute Creation**: Proper API mode detection and routing
-  - All attribute operations now route through adapter pattern
-  - TablesDB vs Legacy API terminology used correctly
-  - Fixed direct SDK calls that bypassed version detection
-  - Maintained backward compatibility with pre-1.8.0 Appwrite
-
-- **Sync-from-Appwrite Issues**: Comprehensive fixes for YAML generation
-  - Database definitions now properly added to configuration
-  - Version-aware folder structure (tables/ vs collections/)
-  - Correct schema references in generated YAML files
-  - Enhanced error handling and user feedback
-
-### Technical Improvements
-- **New Utilities**: Added comprehensive session and project management utilities
-  - `sessionAuth.ts` - Complete session management and validation
-  - `projectConfig.ts` - Appwrite project configuration handling
-  - Enhanced `getClientFromConfig.ts` with session authentication support
-  - Improved `setupFiles.ts` with intelligent version detection
-
-- **Enhanced Type Definitions**: Better TypeScript support throughout
-  - Comprehensive session authentication types
-  - Project configuration interfaces and validation
-  - Enhanced error handling and message formatting
-  - Better integration between authentication methods
-
-- **Improved Error Handling**: More helpful and actionable error messages
-  - Authentication method reporting and guidance
-  - Session availability checking and listing
-  - Project configuration validation feedback
-  - Version detection status and fallback information
-
-- **Full TypeScript Type Safety**: Enhanced type definitions throughout
-- **Comprehensive Test Coverage**: Extensive testing for all new features
-- **Performance Optimizations**: Reduced redundant operations and improved efficiency
-- **Enhanced Debugging**: Better visibility into CLI operations and state changes
-
-## [1.5.2] - 2024-XX-XX
-
-### Previous
-- Earlier version features and improvements
-
-## Earlier Versions
-
-Please refer to git history for changes prior to v1.6.0.
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- Push flow now uses explicit, manual selection for databases and tables/collections. No more auto-selecting all databases on `--push`.
+- Adapter-first orchestration for schema updates. Attributes and indexes are compared and only created/updated when changed.
+- Added clear summaries after attribute and index operations (create/update/skip counts).
+- Improved index handling: existence check, tolerant duplicate handling, and availability polling.
+- Multi-database targeting supported via `databaseIds` (alongside `databaseId`) on table/collection definitions.
+- Per-function configuration discovery via `.fnconfig.yaml` anywhere in the repository. Relative `dirPath` resolves from the file’s directory; `~` expands to homedir.
+- TablesDB/legacy detection is fetch-based; no additional SDK packages required.
+

package/README.md

@@ -4,7 +4,12 @@
 
 `appwrite-utils-cli` is a powerful, YAML-first command-line interface tool designed for Appwrite developers who need to manage database migrations, schema generation, data import, and comprehensive project management. Built on a modular architecture with enhanced performance, this CLI tool facilitates complex tasks like setting up databases, running migrations, generating schemas, and managing backups efficiently.
 
-**Version 1.6.1**: Major refactoring for improved code organization - extracted operations into focused modules, standardized logging across the codebase, and added utility libraries for better maintainability.
+Highlights:
+- Adapter-first database orchestration (no legacy attribute fall-through)
+- Safe diff-based updates for attributes and indexes (no duplicate creations)
+- Manual push selections (no auto-push of all DBs)
+- Multi-database targeting per table/collection via `databaseIds`
+- Per-function configuration via `.fnconfig.yaml` (discovered anywhere in repo)
 
 ## Features
 
@@ -15,10 +20,10 @@
 - **Enhanced Performance**: Configurable rate limiting and batch processing for optimal performance
 - **Safety First**: Smart confirmation dialogs for destructive operations with explicit confirmations
 
-### Dual API Support (Collections & TablesDB)
+### Dual API Support (Collections & TablesDB)
 - **Collections API**: Traditional Appwrite database operations with document-based terminology
 - **TablesDB API**: New high-performance table API with column-based terminology
-- **Automatic Detection**: Smart API mode detection based on configuration and available packages
+- **Automatic Detection**: Smart API mode detection (fetch-based detection; no extra packages required)
 - **Seamless Migration**: Zero-downtime migration between Collections and TablesDB APIs
 - **Terminology Flexibility**: Support for both `collections/documents/attributes` and `tables/rows/columns`
 
@@ -53,32 +58,15 @@ npx --package=appwrite-utils-cli@latest appwrite-migrate [options]
 
 **Note: Do not install this locally into your project. It is meant to be used as a command-line tool only.**
 
-## TablesDB Support
+## TablesDB Support
 
 `appwrite-utils-cli` provides comprehensive support for both traditional Appwrite Collections API and the new TablesDB API, enabling high-performance database operations with modern terminology.
 
-### API Mode Detection
+### API Mode Detection
+
+The CLI automatically selects Collections or TablesDB using fetch-based server detection (health/version and endpoint probes). No additional SDK packages are required.
 
-The CLI automatically detects which API to use based on:
-
-1. **Package Detection**: Checks for `node-appwrite-tablesdb` package installation
-2. **Configuration**: Detects `collections` vs `tables` in YAML configuration
-3. **Environment**: Falls back to Collections API if TablesDB is not available
-
-### Installing TablesDB Support
-
-To enable TablesDB functionality, install the TablesDB package alongside the CLI:
-
-```bash
-# For global CLI usage
-npm install -g node-appwrite-tablesdb
-
-# For project-specific usage
-npm install node-appwrite-tablesdb
-npx --package=appwrite-utils-cli@latest --package=node-appwrite-tablesdb@latest appwrite-migrate --it
-```
-
-### Configuration Comparison
+### Configuration Comparison
 
 #### Collections API (Traditional)
 ```yaml
@@ -134,7 +122,7 @@ npx appwrite-utils-cli appwrite-migrate --sync --use-tablesdb
 npx appwrite-utils-cli appwrite-migrate --generate --api-mode=tablesdb
 ```
 
-## YAML-First Configuration
+## YAML-First Configuration
 
 Version 1.0.0 introduces a YAML-first approach for better cross-platform compatibility and enhanced developer experience.
 
@@ -145,7 +133,7 @@ The CLI automatically detects configuration files in this order:
 2. `appwrite.yaml`
 3. `appwriteConfig.ts` (legacy, still supported)
 
-### YAML Configuration Examples
+### YAML Configuration Examples
 
 #### Collections API Configuration
 ```yaml
@@ -221,7 +209,7 @@ logging:
   console: true
 ```
 
-## Usage
+## Usage
 
 After installation, you can access the tool directly from your command line using the provided commands.
 
@@ -239,7 +227,34 @@ This provides a professional guided experience with:
 - Operation summaries with detailed statistics
 - Real-time progress bars with ETA calculations
 
-### Non-Interactive Mode
+### Push (manual selection)
+
+Pushing local schema is now an explicit, manual selection flow to avoid unintended changes:
+
+```bash
+npx appwrite-utils-cli appwrite-migrate --push
+```
+
+- Select databases from the remote project (no default auto-selection)
+- Select tables/collections to push per selected database
+- Summary confirmation is shown before applying changes
+
+Flags:
+- `--dbIds=id1,id2` pre-selects databases by ID (skips DB prompt)
+- `--collectionIds=c1,c2` pre-selects tables/collections by ID for the selected DB(s)
+
+Eligibility per DB:
+- A table/collection is considered eligible for a database if:
+  - `databaseIds` includes the database ID, or
+  - `databaseId` equals the database ID, or
+  - neither field is set (eligible everywhere)
+
+Attribute/Index behavior:
+- Attributes and indexes are compared and only created/updated when changed
+- Unchanged definitions are skipped
+- Status is monitored until available (with sensible timeouts)
+
+### Non-Interactive Mode
 
 You can also use specific flags to run tasks without the interactive prompt:
 
@@ -247,7 +262,7 @@ You can also use specific flags to run tasks without the interactive prompt:
 npx --package=appwrite-utils-cli@latest appwrite-migrate [options]
 ```
 
-## YAML Import Configuration System
+## YAML Import Configuration System
 
 Version 1.0.0 introduces a powerful YAML-based import system with sophisticated data handling capabilities.
 
@@ -1045,3 +1060,45 @@ npx appwrite-utils-cli appwrite-migrate --generateConstants --constantsLanguages
 - 0.0.22: Converted all import processes except `postImportActions` and Relationship Resolution to the local data import, so it should be much faster.
 - 0.0.6: Added `setTargetFieldFromOtherCollectionDocumentsByMatchingField` for the below, but setting a different field than the field you matched. The names are long, but at least you know what's going on lmao.
 - 0.0.5: Added `setFieldFromOtherCollectionDocuments` to set an array of ID's for instance from another collection as a `postImportAction`
+## Multi-Database Targeting
+
+You can target the same table/collection to multiple databases by adding `databaseIds` to the definition:
+
+```ts
+// Example: table.ts
+export default {
+  name: 'Analytics',
+  databaseIds: ['dev', 'staging', 'main'],
+  attributes: [
+    { key: 'timestamp', type: 'datetime', required: true },
+    { key: 'totalUsers', type: 'integer' }
+  ],
+  indexes: [{ key: 'ts_idx', type: 'key', attributes: ['timestamp'] }]
+};
+```
+
+During push, this table will appear under each selected database whose ID matches `databaseIds`.
+
+## Per-Function Configuration (.fnconfig.yaml)
+
+You can define functions in per-directory YAML files named `.fnconfig.yaml` (or `.fnconfig.yml`), discovered anywhere under your git repository root:
+
+```yaml
+# ./functions/reporting/.fnconfig.yaml
+id: reporting
+name: Reporting
+runtime: node-22.0
+execute: ["any"]
+events: []
+dirPath: ./  # defaults to the directory containing this file
+commands: npm install
+entrypoint: index.js
+```
+
+Rules:
+- If `dirPath` starts with `~`, it expands to your home directory
+- Relative `dirPath` resolves against the `.fnconfig.yaml` directory
+- Absolute `dirPath` is used as-is
+- `.fnconfig.yaml` definitions merge with central `.appwrite/config.yaml` functions; if the same `$id` exists in both, `.fnconfig.yaml` overrides
+
+Deployment uses the merged function set and resolves paths according to these rules.

package/dist/adapters/AdapterFactory.js

@@ -9,9 +9,9 @@ import { detectAppwriteVersionCached, isVersionAtLeast } from "../utils/versionD
 import { TablesDBAdapter } from './TablesDBAdapter.js';
 import { LegacyAdapter } from './LegacyAdapter.js';
 import { logger } from '../shared/logging.js';
-import { getClientWithAuth } from '../utils/getClientFromConfig.js';
 import { isValidSessionCookie } from '../utils/sessionAuth.js';
 import { MessageFormatter } from '../shared/messageFormatter.js';
+import { Client } from 'node-appwrite';
 /**
  * AdapterFactory - Main factory class for creating database adapters
  */
@@ -157,18 +157,10 @@ export class AdapterFactory {
     static async createTablesDBAdapter(config) {
         const startTime = Date.now();
         try {
-            logger.info('Loading TablesDB SDK', {
+            logger.info('Creating TablesDB adapter (static SDK imports)', {
                 endpoint: config.appwriteEndpoint,
                 operation: 'createTablesDBAdapter'
             });
-            // Dynamic import of TablesDB SDK
-            const importStartTime = Date.now();
-            const { Client, TablesDB } = await import('node-appwrite-tablesdb');
-            const importDuration = Date.now() - importStartTime;
-            logger.debug('TablesDB SDK import successful', {
-                importDuration,
-                operation: 'createTablesDBAdapter'
-            });
             // Use pre-configured client or create session-aware client with TablesDB Client
             let client;
             if (config.preConfiguredClient) {
@@ -200,12 +192,10 @@ export class AdapterFactory {
                     throw new Error("No authentication available for adapter");
                 }
             }
-            const tablesDB = new TablesDB(client);
-            const adapter = new TablesDBAdapter(tablesDB);
+            const adapter = new TablesDBAdapter(client);
             const totalDuration = Date.now() - startTime;
             logger.info('TablesDB adapter created successfully', {
                 totalDuration,
-                importDuration,
                 endpoint: config.appwriteEndpoint,
                 operation: 'createTablesDBAdapter'
             });
@@ -231,18 +221,10 @@ export class AdapterFactory {
     static async createLegacyAdapter(config) {
         const startTime = Date.now();
         try {
-            logger.info('Loading legacy Appwrite SDK', {
+            logger.info('Creating legacy adapter (static SDK imports)', {
                 endpoint: config.appwriteEndpoint,
                 operation: 'createLegacyAdapter'
             });
-            // Dynamic import of legacy SDK
-            const importStartTime = Date.now();
-            const { Client, Databases } = await import('node-appwrite');
-            const importDuration = Date.now() - importStartTime;
-            logger.debug('Legacy SDK import successful', {
-                importDuration,
-                operation: 'createLegacyAdapter'
-            });
             // Use pre-configured client or create session-aware client with Legacy Client
             let client;
             if (config.preConfiguredClient) {
@@ -274,12 +256,10 @@ export class AdapterFactory {
                     throw new Error("No authentication available for adapter");
                 }
             }
-            const databases = new Databases(client);
-            const adapter = new LegacyAdapter(databases);
+            const adapter = new LegacyAdapter(client);
             const totalDuration = Date.now() - startTime;
             logger.info('Legacy adapter created successfully', {
                 totalDuration,
-                importDuration,
                 endpoint: config.appwriteEndpoint,
                 operation: 'createLegacyAdapter'
             });

package/dist/adapters/DatabaseAdapter.d.ts

@@ -5,6 +5,7 @@
  * (collections/documents) and new TablesDB (tables/rows) APIs. All internal
  * code uses TablesDB-style method signatures for consistency.
  */
+import type { Client } from "node-appwrite";
 import type { ApiMode } from "../utils/versionDetection.js";
 export interface CreateRowParams {
     databaseId: string;
@@ -36,6 +37,7 @@ export interface CreateTableParams {
     name: string;
     permissions?: string[];
     documentSecurity?: boolean;
+    rowSecurity?: boolean;
     enabled?: boolean;
 }
 export interface UpdateTableParams {
@@ -44,6 +46,7 @@ export interface UpdateTableParams {
     name: string;
     permissions?: string[];
     documentSecurity?: boolean;
+    rowSecurity?: boolean;
     enabled?: boolean;
 }
 export interface ListTablesParams {
@@ -108,8 +111,20 @@ export interface UpdateAttributeParams {
     databaseId: string;
     tableId: string;
     key: string;
+    type?: string;
     required?: boolean;
     default?: any;
+    size?: number;
+    min?: number;
+    max?: number;
+    array?: boolean;
+    encrypt?: boolean;
+    elements?: string[];
+    relatedCollection?: string;
+    relationType?: string;
+    twoWay?: boolean;
+    twoWayKey?: string;
+    onDelete?: string;
 }
 export interface DeleteAttributeParams {
     databaseId: string;
@@ -176,9 +191,9 @@ export interface DatabaseAdapter {
  * Base adapter class with common functionality
  */
 export declare abstract class BaseAdapter implements DatabaseAdapter {
-    protected client: any;
+    protected client: Client;
     protected apiMode: ApiMode;
-    constructor(client: any, apiMode: ApiMode);
+    constructor(client: Client, apiMode: ApiMode);
     abstract listRows(params: ListRowsParams): Promise<ApiResponse>;
     abstract createRow(params: CreateRowParams): Promise<ApiResponse>;
     abstract updateRow(params: UpdateRowParams): Promise<ApiResponse>;

package/dist/adapters/LegacyAdapter.d.ts

@@ -6,13 +6,14 @@
  * code can use modern TablesDB patterns while maintaining compatibility with
  * older Appwrite instances.
  */
+import { Client } from "node-appwrite";
 import { BaseAdapter, type CreateRowParams, type UpdateRowParams, type ListRowsParams, type DeleteRowParams, type CreateTableParams, type UpdateTableParams, type ListTablesParams, type DeleteTableParams, type GetTableParams, type BulkCreateRowsParams, type BulkUpsertRowsParams, type BulkDeleteRowsParams, type CreateIndexParams, type ListIndexesParams, type DeleteIndexParams, type CreateAttributeParams, type UpdateAttributeParams, type DeleteAttributeParams, type ApiResponse, type AdapterMetadata } from './DatabaseAdapter.js';
 /**
  * LegacyAdapter - Translates TablesDB calls to legacy Databases API
  */
 export declare class LegacyAdapter extends BaseAdapter {
     private databases;
-    constructor(client: any);
+    constructor(client: Client);
     listRows(params: ListRowsParams): Promise<ApiResponse>;
     createRow(params: CreateRowParams): Promise<ApiResponse>;
     updateRow(params: UpdateRowParams): Promise<ApiResponse>;