@njdamstra/appwrite-utils-cli 1.8.9 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/CONFIG_TODO.md +1189 -0
  3. package/SELECTION_DIALOGS.md +146 -0
  4. package/SERVICE_IMPLEMENTATION_REPORT.md +462 -0
  5. package/dist/adapters/index.d.ts +7 -8
  6. package/dist/adapters/index.js +7 -9
  7. package/dist/backups/operations/bucketBackup.js +2 -2
  8. package/dist/backups/operations/collectionBackup.d.ts +1 -1
  9. package/dist/backups/operations/collectionBackup.js +3 -3
  10. package/dist/backups/operations/comprehensiveBackup.d.ts +1 -1
  11. package/dist/backups/operations/comprehensiveBackup.js +2 -2
  12. package/dist/backups/tracking/centralizedTracking.d.ts +1 -1
  13. package/dist/backups/tracking/centralizedTracking.js +2 -2
  14. package/dist/cli/commands/configCommands.js +51 -7
  15. package/dist/cli/commands/databaseCommands.d.ts +1 -0
  16. package/dist/cli/commands/databaseCommands.js +119 -9
  17. package/dist/cli/commands/functionCommands.js +3 -3
  18. package/dist/cli/commands/importFileCommands.d.ts +7 -0
  19. package/dist/cli/commands/importFileCommands.js +674 -0
  20. package/dist/cli/commands/schemaCommands.js +3 -3
  21. package/dist/cli/commands/storageCommands.js +2 -3
  22. package/dist/cli/commands/transferCommands.js +3 -5
  23. package/dist/collections/attributes.d.ts +1 -1
  24. package/dist/collections/attributes.js +2 -35
  25. package/dist/collections/indexes.js +1 -3
  26. package/dist/collections/methods.d.ts +1 -1
  27. package/dist/collections/methods.js +111 -192
  28. package/dist/collections/tableOperations.d.ts +1 -0
  29. package/dist/collections/tableOperations.js +55 -23
  30. package/dist/collections/transferOperations.d.ts +1 -1
  31. package/dist/collections/transferOperations.js +3 -4
  32. package/dist/collections/wipeOperations.d.ts +4 -3
  33. package/dist/collections/wipeOperations.js +112 -39
  34. package/dist/databases/methods.js +2 -2
  35. package/dist/databases/setup.js +2 -2
  36. package/dist/examples/yamlTerminologyExample.js +2 -2
  37. package/dist/functions/deployments.d.ts +1 -1
  38. package/dist/functions/deployments.js +5 -5
  39. package/dist/functions/fnConfigDiscovery.js +2 -2
  40. package/dist/functions/methods.js +16 -4
  41. package/dist/init.js +1 -1
  42. package/dist/interactiveCLI.d.ts +6 -1
  43. package/dist/interactiveCLI.js +63 -9
  44. package/dist/main.js +130 -177
  45. package/dist/migrations/afterImportActions.js +2 -3
  46. package/dist/migrations/appwriteToX.d.ts +1 -1
  47. package/dist/migrations/appwriteToX.js +9 -7
  48. package/dist/migrations/comprehensiveTransfer.js +3 -5
  49. package/dist/migrations/dataLoader.js +2 -5
  50. package/dist/migrations/importController.js +3 -4
  51. package/dist/migrations/importDataActions.js +3 -3
  52. package/dist/migrations/relationships.js +1 -2
  53. package/dist/migrations/services/DataTransformationService.js +2 -2
  54. package/dist/migrations/services/FileHandlerService.js +1 -1
  55. package/dist/migrations/services/ImportOrchestrator.js +4 -4
  56. package/dist/migrations/services/RateLimitManager.js +1 -1
  57. package/dist/migrations/services/RelationshipResolver.js +1 -1
  58. package/dist/migrations/services/UserMappingService.js +1 -1
  59. package/dist/migrations/services/ValidationService.js +1 -1
  60. package/dist/migrations/transfer.d.ts +8 -4
  61. package/dist/migrations/transfer.js +106 -55
  62. package/dist/migrations/yaml/YamlImportConfigLoader.js +1 -1
  63. package/dist/migrations/yaml/YamlImportIntegration.js +2 -2
  64. package/dist/migrations/yaml/generateImportSchemas.js +1 -1
  65. package/dist/setupCommands.d.ts +1 -1
  66. package/dist/setupCommands.js +5 -6
  67. package/dist/setupController.js +1 -1
  68. package/dist/shared/backupTracking.d.ts +1 -1
  69. package/dist/shared/backupTracking.js +2 -2
  70. package/dist/shared/confirmationDialogs.js +1 -1
  71. package/dist/shared/migrationHelpers.d.ts +1 -1
  72. package/dist/shared/migrationHelpers.js +3 -3
  73. package/dist/shared/operationQueue.d.ts +1 -1
  74. package/dist/shared/operationQueue.js +2 -3
  75. package/dist/shared/operationsTable.d.ts +1 -1
  76. package/dist/shared/operationsTable.js +2 -2
  77. package/dist/shared/progressManager.js +1 -1
  78. package/dist/shared/selectionDialogs.js +9 -8
  79. package/dist/storage/methods.js +4 -4
  80. package/dist/storage/schemas.d.ts +2 -2
  81. package/dist/tables/indexManager.d.ts +65 -0
  82. package/dist/tables/indexManager.js +294 -0
  83. package/dist/types.d.ts +2 -2
  84. package/dist/types.js +1 -1
  85. package/dist/users/methods.js +2 -3
  86. package/dist/utils/configMigration.js +1 -1
  87. package/dist/utils/index.d.ts +1 -1
  88. package/dist/utils/index.js +1 -1
  89. package/dist/utils/loadConfigs.d.ts +2 -2
  90. package/dist/utils/loadConfigs.js +6 -7
  91. package/dist/utils/setupFiles.js +5 -7
  92. package/dist/utilsController.d.ts +15 -8
  93. package/dist/utilsController.js +57 -28
  94. package/package.json +7 -3
  95. package/src/adapters/index.ts +8 -34
  96. package/src/backups/operations/bucketBackup.ts +2 -2
  97. package/src/backups/operations/collectionBackup.ts +4 -4
  98. package/src/backups/operations/comprehensiveBackup.ts +3 -3
  99. package/src/backups/tracking/centralizedTracking.ts +3 -3
  100. package/src/cli/commands/configCommands.ts +72 -8
  101. package/src/cli/commands/databaseCommands.ts +161 -9
  102. package/src/cli/commands/functionCommands.ts +4 -3
  103. package/src/cli/commands/importFileCommands.ts +815 -0
  104. package/src/cli/commands/schemaCommands.ts +3 -3
  105. package/src/cli/commands/storageCommands.ts +2 -3
  106. package/src/cli/commands/transferCommands.ts +3 -6
  107. package/src/collections/attributes.ts +3 -39
  108. package/src/collections/indexes.ts +2 -4
  109. package/src/collections/methods.ts +115 -150
  110. package/src/collections/tableOperations.ts +57 -21
  111. package/src/collections/transferOperations.ts +4 -5
  112. package/src/collections/wipeOperations.ts +154 -51
  113. package/src/databases/methods.ts +2 -2
  114. package/src/databases/setup.ts +2 -2
  115. package/src/examples/yamlTerminologyExample.ts +2 -2
  116. package/src/functions/deployments.ts +6 -5
  117. package/src/functions/fnConfigDiscovery.ts +2 -2
  118. package/src/functions/methods.ts +17 -4
  119. package/src/init.ts +1 -1
  120. package/src/interactiveCLI.ts +75 -10
  121. package/src/main.ts +143 -287
  122. package/src/migrations/afterImportActions.ts +2 -3
  123. package/src/migrations/appwriteToX.ts +12 -8
  124. package/src/migrations/comprehensiveTransfer.ts +6 -6
  125. package/src/migrations/dataLoader.ts +2 -5
  126. package/src/migrations/importController.ts +3 -4
  127. package/src/migrations/importDataActions.ts +3 -3
  128. package/src/migrations/relationships.ts +1 -2
  129. package/src/migrations/services/DataTransformationService.ts +2 -2
  130. package/src/migrations/services/FileHandlerService.ts +1 -1
  131. package/src/migrations/services/ImportOrchestrator.ts +4 -4
  132. package/src/migrations/services/RateLimitManager.ts +1 -1
  133. package/src/migrations/services/RelationshipResolver.ts +1 -1
  134. package/src/migrations/services/UserMappingService.ts +1 -1
  135. package/src/migrations/services/ValidationService.ts +1 -1
  136. package/src/migrations/transfer.ts +126 -83
  137. package/src/migrations/yaml/YamlImportConfigLoader.ts +1 -1
  138. package/src/migrations/yaml/YamlImportIntegration.ts +2 -2
  139. package/src/migrations/yaml/generateImportSchemas.ts +1 -1
  140. package/src/setupCommands.ts +5 -6
  141. package/src/setupController.ts +1 -1
  142. package/src/shared/backupTracking.ts +3 -3
  143. package/src/shared/confirmationDialogs.ts +1 -1
  144. package/src/shared/migrationHelpers.ts +4 -4
  145. package/src/shared/operationQueue.ts +3 -4
  146. package/src/shared/operationsTable.ts +3 -3
  147. package/src/shared/progressManager.ts +1 -1
  148. package/src/shared/selectionDialogs.ts +9 -8
  149. package/src/storage/methods.ts +4 -4
  150. package/src/tables/indexManager.ts +409 -0
  151. package/src/types.ts +2 -2
  152. package/src/users/methods.ts +2 -3
  153. package/src/utils/configMigration.ts +1 -1
  154. package/src/utils/index.ts +1 -1
  155. package/src/utils/loadConfigs.ts +15 -7
  156. package/src/utils/setupFiles.ts +5 -7
  157. package/src/utilsController.ts +86 -32
  158. package/dist/adapters/AdapterFactory.d.ts +0 -94
  159. package/dist/adapters/AdapterFactory.js +0 -405
  160. package/dist/adapters/DatabaseAdapter.d.ts +0 -233
  161. package/dist/adapters/DatabaseAdapter.js +0 -50
  162. package/dist/adapters/LegacyAdapter.d.ts +0 -50
  163. package/dist/adapters/LegacyAdapter.js +0 -612
  164. package/dist/adapters/TablesDBAdapter.d.ts +0 -45
  165. package/dist/adapters/TablesDBAdapter.js +0 -571
  166. package/dist/config/ConfigManager.d.ts +0 -445
  167. package/dist/config/ConfigManager.js +0 -625
  168. package/dist/config/configMigration.d.ts +0 -87
  169. package/dist/config/configMigration.js +0 -390
  170. package/dist/config/configValidation.d.ts +0 -66
  171. package/dist/config/configValidation.js +0 -358
  172. package/dist/config/index.d.ts +0 -8
  173. package/dist/config/index.js +0 -7
  174. package/dist/config/services/ConfigDiscoveryService.d.ts +0 -126
  175. package/dist/config/services/ConfigDiscoveryService.js +0 -374
  176. package/dist/config/services/ConfigLoaderService.d.ts +0 -129
  177. package/dist/config/services/ConfigLoaderService.js +0 -540
  178. package/dist/config/services/ConfigMergeService.d.ts +0 -208
  179. package/dist/config/services/ConfigMergeService.js +0 -308
  180. package/dist/config/services/ConfigValidationService.d.ts +0 -214
  181. package/dist/config/services/ConfigValidationService.js +0 -310
  182. package/dist/config/services/SessionAuthService.d.ts +0 -225
  183. package/dist/config/services/SessionAuthService.js +0 -456
  184. package/dist/config/services/__tests__/ConfigMergeService.test.d.ts +0 -1
  185. package/dist/config/services/__tests__/ConfigMergeService.test.js +0 -271
  186. package/dist/config/services/index.d.ts +0 -13
  187. package/dist/config/services/index.js +0 -10
  188. package/dist/config/yamlConfig.d.ts +0 -722
  189. package/dist/config/yamlConfig.js +0 -702
  190. package/dist/functions/pathResolution.d.ts +0 -37
  191. package/dist/functions/pathResolution.js +0 -185
  192. package/dist/shared/attributeMapper.d.ts +0 -20
  193. package/dist/shared/attributeMapper.js +0 -203
  194. package/dist/shared/errorUtils.d.ts +0 -54
  195. package/dist/shared/errorUtils.js +0 -95
  196. package/dist/shared/functionManager.d.ts +0 -48
  197. package/dist/shared/functionManager.js +0 -336
  198. package/dist/shared/indexManager.d.ts +0 -24
  199. package/dist/shared/indexManager.js +0 -151
  200. package/dist/shared/jsonSchemaGenerator.d.ts +0 -50
  201. package/dist/shared/jsonSchemaGenerator.js +0 -290
  202. package/dist/shared/logging.d.ts +0 -61
  203. package/dist/shared/logging.js +0 -116
  204. package/dist/shared/messageFormatter.d.ts +0 -39
  205. package/dist/shared/messageFormatter.js +0 -162
  206. package/dist/shared/pydanticModelGenerator.d.ts +0 -17
  207. package/dist/shared/pydanticModelGenerator.js +0 -615
  208. package/dist/shared/schemaGenerator.d.ts +0 -40
  209. package/dist/shared/schemaGenerator.js +0 -556
  210. package/dist/utils/ClientFactory.d.ts +0 -87
  211. package/dist/utils/ClientFactory.js +0 -212
  212. package/dist/utils/configDiscovery.d.ts +0 -78
  213. package/dist/utils/configDiscovery.js +0 -472
  214. package/dist/utils/constantsGenerator.d.ts +0 -31
  215. package/dist/utils/constantsGenerator.js +0 -321
  216. package/dist/utils/dataConverters.d.ts +0 -46
  217. package/dist/utils/dataConverters.js +0 -139
  218. package/dist/utils/directoryUtils.d.ts +0 -22
  219. package/dist/utils/directoryUtils.js +0 -59
  220. package/dist/utils/getClientFromConfig.d.ts +0 -39
  221. package/dist/utils/getClientFromConfig.js +0 -199
  222. package/dist/utils/helperFunctions.d.ts +0 -63
  223. package/dist/utils/helperFunctions.js +0 -156
  224. package/dist/utils/pathResolvers.d.ts +0 -53
  225. package/dist/utils/pathResolvers.js +0 -72
  226. package/dist/utils/projectConfig.d.ts +0 -119
  227. package/dist/utils/projectConfig.js +0 -171
  228. package/dist/utils/retryFailedPromises.d.ts +0 -2
  229. package/dist/utils/retryFailedPromises.js +0 -23
  230. package/dist/utils/sessionAuth.d.ts +0 -48
  231. package/dist/utils/sessionAuth.js +0 -164
  232. package/dist/utils/typeGuards.d.ts +0 -35
  233. package/dist/utils/typeGuards.js +0 -57
  234. package/dist/utils/validationRules.d.ts +0 -43
  235. package/dist/utils/validationRules.js +0 -42
  236. package/dist/utils/versionDetection.d.ts +0 -58
  237. package/dist/utils/versionDetection.js +0 -251
  238. package/dist/utils/yamlConverter.d.ts +0 -100
  239. package/dist/utils/yamlConverter.js +0 -428
  240. package/dist/utils/yamlLoader.d.ts +0 -70
  241. package/dist/utils/yamlLoader.js +0 -267
  242. package/src/adapters/AdapterFactory.ts +0 -510
  243. package/src/adapters/DatabaseAdapter.ts +0 -306
  244. package/src/adapters/LegacyAdapter.ts +0 -841
  245. package/src/adapters/TablesDBAdapter.ts +0 -773
  246. package/src/config/ConfigManager.ts +0 -808
  247. package/src/config/README.md +0 -274
  248. package/src/config/configMigration.ts +0 -575
  249. package/src/config/configValidation.ts +0 -445
  250. package/src/config/index.ts +0 -10
  251. package/src/config/services/ConfigDiscoveryService.ts +0 -463
  252. package/src/config/services/ConfigLoaderService.ts +0 -740
  253. package/src/config/services/ConfigMergeService.ts +0 -388
  254. package/src/config/services/ConfigValidationService.ts +0 -394
  255. package/src/config/services/SessionAuthService.ts +0 -565
  256. package/src/config/services/__tests__/ConfigMergeService.test.ts +0 -351
  257. package/src/config/services/index.ts +0 -29
  258. package/src/config/yamlConfig.ts +0 -761
  259. package/src/functions/pathResolution.ts +0 -227
  260. package/src/shared/attributeMapper.ts +0 -229
  261. package/src/shared/errorUtils.ts +0 -110
  262. package/src/shared/functionManager.ts +0 -525
  263. package/src/shared/indexManager.ts +0 -254
  264. package/src/shared/jsonSchemaGenerator.ts +0 -383
  265. package/src/shared/logging.ts +0 -149
  266. package/src/shared/messageFormatter.ts +0 -208
  267. package/src/shared/pydanticModelGenerator.ts +0 -618
  268. package/src/shared/schemaGenerator.ts +0 -644
  269. package/src/utils/ClientFactory.ts +0 -240
  270. package/src/utils/configDiscovery.ts +0 -557
  271. package/src/utils/constantsGenerator.ts +0 -369
  272. package/src/utils/dataConverters.ts +0 -159
  273. package/src/utils/directoryUtils.ts +0 -61
  274. package/src/utils/getClientFromConfig.ts +0 -257
  275. package/src/utils/helperFunctions.ts +0 -228
  276. package/src/utils/pathResolvers.ts +0 -81
  277. package/src/utils/projectConfig.ts +0 -299
  278. package/src/utils/retryFailedPromises.ts +0 -29
  279. package/src/utils/sessionAuth.ts +0 -230
  280. package/src/utils/typeGuards.ts +0 -65
  281. package/src/utils/validationRules.ts +0 -88
  282. package/src/utils/versionDetection.ts +0 -292
  283. package/src/utils/yamlConverter.ts +0 -542
  284. package/src/utils/yamlLoader.ts +0 -371
package/src/main.ts CHANGED
@@ -6,35 +6,20 @@ import { InteractiveCLI } from "./interactiveCLI.js";
6
6
  import { UtilsController, type SetupOptions } from "./utilsController.js";
7
7
  import type { TransferOptions } from "./migrations/transfer.js";
8
8
  import { Databases, Storage, type Models } from "node-appwrite";
9
- import { getClient } from "./utils/getClientFromConfig.js";
9
+ import { getClient } from "@njdamstra/appwrite-utils-helpers";
10
10
  import { fetchAllDatabases } from "./databases/methods.js";
11
11
  import { setupDirsFiles } from "./utils/setupFiles.js";
12
12
  import { fetchAllCollections } from "./collections/methods.js";
13
13
  import type { Specification } from "@njdamstra/appwrite-utils";
14
14
  import chalk from "chalk";
15
15
  import { listSpecifications } from "./functions/methods.js";
16
- import { MessageFormatter } from "./shared/messageFormatter.js";
16
+ import { MessageFormatter, logger, AuthenticationError } from "@njdamstra/appwrite-utils-helpers";
17
17
  import { ConfirmationDialogs } from "./shared/confirmationDialogs.js";
18
18
  import { SelectionDialogs } from "./shared/selectionDialogs.js";
19
- import { logger } from "./shared/logging.js";
20
19
  import type { SyncSelectionSummary, DatabaseSelection, BucketSelection } from "./shared/selectionDialogs.js";
21
20
  import path from "path";
22
21
  import fs from "fs";
23
22
  import { createRequire } from "node:module";
24
- import {
25
- loadAppwriteProjectConfig,
26
- findAppwriteProjectConfig,
27
- projectConfigToAppwriteConfig,
28
- } from "./utils/projectConfig.js";
29
- import {
30
- hasSessionAuth,
31
- getAvailableSessions,
32
- getAuthenticationStatus,
33
- } from "./utils/sessionAuth.js";
34
- import {
35
- findYamlConfig,
36
- loadYamlConfigWithSession,
37
- } from "./config/yamlConfig.js";
38
23
 
39
24
  const require = createRequire(import.meta.url);
40
25
  if (!(globalThis as any).require) {
@@ -43,6 +28,7 @@ if (!(globalThis as any).require) {
43
28
 
44
29
  interface CliOptions {
45
30
  config?: string;
31
+ appwriteConfig?: boolean;
46
32
  it?: boolean;
47
33
  dbIds?: string;
48
34
  collectionIds?: string;
@@ -83,7 +69,7 @@ interface CliOptions {
83
69
  constantsOutput?: string;
84
70
  migrateCollectionsToTables?: boolean;
85
71
  useSession?: boolean;
86
- session?: string;
72
+ sessionCookie?: string;
87
73
  listBackups?: boolean;
88
74
  autoSync?: boolean;
89
75
  selectBuckets?: boolean;
@@ -92,6 +78,10 @@ interface CliOptions {
92
78
  schemaFormat?: 'zod' | 'json' | 'pydantic' | 'both' | 'all';
93
79
  schemaOutDir?: string;
94
80
  constantsInclude?: string;
81
+ // Direct file import
82
+ importFile?: string;
83
+ targetDb?: string;
84
+ targetTable?: string;
95
85
  }
96
86
 
97
87
  type ParsedArgv = ArgumentsCamelCase<CliOptions>;
@@ -370,6 +360,11 @@ const argv = yargs(hideBin(process.argv))
370
360
  type: "string",
371
361
  description: "Path to Appwrite configuration file (appwriteConfig.ts)",
372
362
  })
363
+ .option("appwriteConfig", {
364
+ alias: ["appwrite-config", "use-appwrite-config"],
365
+ type: "boolean",
366
+ description: "Prefer loading from appwrite.config.json instead of config.yaml",
367
+ })
373
368
  .option("it", {
374
369
  alias: ["interactive", "i"],
375
370
  type: "boolean",
@@ -611,209 +606,91 @@ const argv = yargs(hideBin(process.argv))
611
606
  type: "string",
612
607
  description: "Explicit session cookie to use for authentication",
613
608
  })
609
+ .option("importFile", {
610
+ alias: ["import-file"],
611
+ type: "string",
612
+ description: "Import a CSV or JSON file directly into a table (no config needed)",
613
+ })
614
+ .option("targetDb", {
615
+ alias: ["target-db"],
616
+ type: "string",
617
+ description: "Target database ID for --importFile (prompted if omitted)",
618
+ })
619
+ .option("targetTable", {
620
+ alias: ["target-table"],
621
+ type: "string",
622
+ description: "Target table ID for --importFile (prompted if omitted)",
623
+ })
614
624
  .parse() as ParsedArgv;
615
625
 
616
626
  async function main() {
617
627
  const startTime = Date.now();
618
628
  const operationStats: Record<string, number> = {};
619
629
 
620
- // Early session detection for better user guidance
621
- const availableSessions = getAvailableSessions();
622
- let hasAnyValidSessions = availableSessions.length > 0;
623
-
624
630
  if (argv.it) {
625
- const cli = new InteractiveCLI(process.cwd());
631
+ const cli = new InteractiveCLI(process.cwd(), {
632
+ useSession: argv.useSession,
633
+ sessionCookie: argv.sessionCookie
634
+ });
626
635
  await cli.run();
627
636
  } else {
628
- // Enhanced config creation with session and project file support
629
- let directConfig: any = undefined;
637
+ // Non-interactive mode - pass auth flags through to controller
638
+ // ConfigManager will handle config discovery and auth decisions
639
+ // Users can provide credentials via CLI flags even without a config file
630
640
 
631
- // Show authentication status on startup if no config provided
632
- if (
633
- !argv.config &&
634
- !argv.endpoint &&
635
- !argv.projectId &&
636
- !argv.apiKey &&
637
- !argv.useSession &&
638
- !argv.sessionCookie
639
- ) {
640
- if (hasAnyValidSessions) {
641
- MessageFormatter.info(
642
- `Found ${availableSessions.length} available session(s)`,
643
- { prefix: "Auth" }
644
- );
645
- availableSessions.forEach((session) => {
646
- MessageFormatter.info(
647
- ` \u2022 ${session.projectId} (${session.email || "unknown"}) at ${
648
- session.endpoint
649
- }`,
650
- { prefix: "Auth" }
651
- );
652
- });
653
- MessageFormatter.info(
654
- "Use --session to enable session authentication",
655
- { prefix: "Auth" }
656
- );
657
- } else {
658
- MessageFormatter.info("No active Appwrite sessions found", {
659
- prefix: "Auth",
660
- });
661
- MessageFormatter.info(
662
- "\u2022 Run 'appwrite login' to authenticate with session",
663
- { prefix: "Auth" }
664
- );
665
- MessageFormatter.info(
666
- "\u2022 Or provide --apiKey for API key authentication",
667
- { prefix: "Auth" }
668
- );
669
- }
670
- }
641
+ const controller = UtilsController.getInstance(process.cwd());
671
642
 
672
- // Priority 1: Check for appwrite.json project configuration
673
- const projectConfigPath = findAppwriteProjectConfig(process.cwd());
674
- if (projectConfigPath) {
675
- const projectConfig = loadAppwriteProjectConfig(projectConfigPath);
676
- if (projectConfig) {
677
- directConfig = projectConfigToAppwriteConfig(projectConfig);
678
- MessageFormatter.info(
679
- `Loaded project configuration from ${projectConfigPath}`,
680
- { prefix: "CLI" }
681
- );
682
- }
683
- }
643
+ // Build init options from CLI flags
644
+ const initOptions: any = {
645
+ useSession: argv.useSession,
646
+ sessionCookie: argv.sessionCookie,
647
+ preferJson: argv.appwriteConfig,
648
+ };
684
649
 
685
- // Priority 2: CLI arguments override project config
686
- if (
687
- argv.endpoint ||
688
- argv.projectId ||
689
- argv.apiKey ||
690
- argv.useSession ||
691
- argv.sessionCookie
692
- ) {
693
- directConfig = {
694
- ...directConfig,
695
- appwriteEndpoint: argv.endpoint || directConfig?.appwriteEndpoint,
696
- appwriteProject: argv.projectId || directConfig?.appwriteProject,
697
- appwriteKey: argv.apiKey || directConfig?.appwriteKey,
650
+ // Add CLI overrides if provided - these can work even without a config file
651
+ if (argv.endpoint || argv.projectId || argv.apiKey) {
652
+ initOptions.overrides = {
653
+ appwriteEndpoint: argv.endpoint,
654
+ appwriteProject: argv.projectId,
655
+ appwriteKey: argv.apiKey,
698
656
  };
699
657
  }
700
658
 
701
- // Priority 3: Session authentication support with improved detection
702
- let sessionAuthAvailable = false;
703
-
704
- if (directConfig?.appwriteEndpoint && directConfig?.appwriteProject) {
705
- sessionAuthAvailable = hasSessionAuth(
706
- directConfig.appwriteEndpoint,
707
- directConfig.appwriteProject
708
- );
709
- }
710
-
711
- if (argv.useSession || argv.sessionCookie) {
712
- if (argv.sessionCookie) {
713
- // Explicit session cookie provided
714
- MessageFormatter.info(
715
- "Using explicit session cookie for authentication",
716
- { prefix: "Auth" }
717
- );
718
- } else if (sessionAuthAvailable) {
719
- MessageFormatter.info(
720
- "Session authentication detected and will be used",
721
- { prefix: "Auth" }
722
- );
723
- } else {
724
- MessageFormatter.warning(
725
- "Session authentication requested but no valid session found",
726
- { prefix: "Auth" }
727
- );
728
- const availableSessions = getAvailableSessions();
729
- if (availableSessions.length > 0) {
730
- MessageFormatter.info(
731
- `Available sessions: ${availableSessions
732
- .map((s) => `${s.projectId} (${s.email || "unknown"})`)
733
- .join(", ")}`,
734
- { prefix: "Auth" }
735
- );
736
- MessageFormatter.info(
737
- "Use --session flag to enable session authentication",
738
- { prefix: "Auth" }
739
- );
740
- } else {
741
- MessageFormatter.warning(
742
- "No Appwrite CLI sessions found. Please run 'appwrite login' first.",
743
- { prefix: "Auth" }
744
- );
745
- }
746
- MessageFormatter.error(
747
- "Session authentication requested but not available",
748
- undefined,
749
- { prefix: "Auth" }
750
- );
751
- return; // Exit early if session auth was requested but not available
659
+ try {
660
+ await controller.init(initOptions);
661
+ } catch (error) {
662
+ if (error instanceof AuthenticationError) {
663
+ MessageFormatter.error(error.getFormattedMessage(), undefined, { prefix: "Auth" });
664
+ process.exit(1);
752
665
  }
753
- } else if (sessionAuthAvailable && !argv.apiKey) {
754
- // Auto-detect session authentication when no API key is provided
755
- MessageFormatter.info(
756
- "Session authentication detected - no API key required",
757
- { prefix: "Auth" }
758
- );
759
- MessageFormatter.info(
760
- "Use --session flag to explicitly enable session authentication",
761
- { prefix: "Auth" }
762
- );
666
+ // Re-throw other errors
667
+ throw error;
763
668
  }
764
669
 
765
- // Enhanced session authentication support:
766
- // 1. If session auth is explicitly requested via flags, use it
767
- // 2. If no API key is provided but sessions are available, offer to use session auth
768
- // 3. Auto-detect session authentication when possible
769
- let finalDirectConfig = directConfig;
770
-
771
- if (
772
- (argv.useSession || argv.sessionCookie) &&
773
- (!directConfig ||
774
- !directConfig.appwriteEndpoint ||
775
- !directConfig.appwriteProject)
776
- ) {
777
- // Don't pass incomplete directConfig - let UtilsController load YAML config normally
778
- finalDirectConfig = null;
779
- } else if (
780
- finalDirectConfig &&
781
- !finalDirectConfig.appwriteKey &&
782
- !argv.useSession &&
783
- !argv.sessionCookie
784
- ) {
785
- // Auto-detect session authentication when no API key provided
786
- if (sessionAuthAvailable) {
787
- MessageFormatter.info(
788
- "No API key provided, but session authentication is available",
789
- { prefix: "Auth" }
790
- );
791
- MessageFormatter.info(
792
- "Automatically using session authentication (add --session to suppress this message)",
793
- { prefix: "Auth" }
794
- );
795
- // Implicitly enable session authentication
796
- argv.useSession = true;
797
- }
670
+ // After init, check if we have a valid config (from file OR CLI overrides)
671
+ if (!controller.config) {
672
+ MessageFormatter.error("No Appwrite configuration available", undefined, { prefix: "CLI" });
673
+ MessageFormatter.info("Provide credentials via CLI flags (--endpoint, --projectId, --apiKey or --session)", { prefix: "CLI" });
674
+ MessageFormatter.info("Or create a config file using --setup", { prefix: "CLI" });
675
+ return;
798
676
  }
799
677
 
800
- // Create controller with session authentication support using singleton
801
- const controller = UtilsController.getInstance(
802
- process.cwd(),
803
- finalDirectConfig
804
- );
678
+ const parsedArgv = argv;
805
679
 
806
- // Pass session authentication options to the controller
807
- const initOptions: any = {};
808
- if (argv.useSession || argv.sessionCookie) {
809
- initOptions.useSession = true;
810
- if (argv.sessionCookie) {
811
- initOptions.sessionCookie = argv.sessionCookie;
680
+ if (argv.importFile) {
681
+ const { importFileFromPath, importFilePromptMissing } = await import("./cli/commands/importFileCommands.js");
682
+ if (!controller.adapter) {
683
+ MessageFormatter.error("No adapter available — check your credentials", undefined, { prefix: "Import" });
684
+ return;
685
+ }
686
+ if (parsedArgv.targetDb && parsedArgv.targetTable) {
687
+ await importFileFromPath(controller.adapter, argv.importFile, parsedArgv.targetDb, parsedArgv.targetTable);
688
+ } else {
689
+ await importFilePromptMissing(controller.adapter, controller.database, argv.importFile, parsedArgv.targetDb, parsedArgv.targetTable);
812
690
  }
691
+ return;
813
692
  }
814
693
 
815
- await controller.init(initOptions);
816
-
817
694
  if (argv.setup) {
818
695
  await setupDirsFiles(false, process.cwd());
819
696
  return;
@@ -827,10 +704,10 @@ async function main() {
827
704
 
828
705
  if (argv.generateConstants) {
829
706
  const { ConstantsGenerator } = await import(
830
- "./utils/constantsGenerator.js"
707
+ "@njdamstra/appwrite-utils-helpers"
831
708
  );
832
709
  type SupportedLanguage =
833
- import("./utils/constantsGenerator.js").SupportedLanguage;
710
+ import("@njdamstra/appwrite-utils-helpers").SupportedLanguage;
834
711
 
835
712
  if (!controller.config) {
836
713
  MessageFormatter.error("No Appwrite configuration found", undefined, {
@@ -928,7 +805,7 @@ async function main() {
928
805
  }
929
806
 
930
807
  const { migrateCollectionsToTables } = await import(
931
- "./config/configMigration.js"
808
+ "@njdamstra/appwrite-utils-helpers"
932
809
  );
933
810
 
934
811
  MessageFormatter.info("Starting collections to tables migration...", {
@@ -965,55 +842,9 @@ async function main() {
965
842
  return;
966
843
  }
967
844
 
968
- if (!controller.config) {
969
- // Provide better guidance based on available authentication methods
970
- const availableSessions = getAvailableSessions();
971
-
972
- if (availableSessions.length > 0) {
973
- MessageFormatter.error("No Appwrite configuration found", undefined, {
974
- prefix: "CLI",
975
- });
976
- MessageFormatter.info("Available authentication options:", {
977
- prefix: "Auth",
978
- });
979
- MessageFormatter.info("• Session authentication: Add --session flag", {
980
- prefix: "Auth",
981
- });
982
- MessageFormatter.info(
983
- "• API key authentication: Add --apiKey YOUR_API_KEY",
984
- { prefix: "Auth" }
985
- );
986
- MessageFormatter.info(
987
- `• Available sessions: ${availableSessions
988
- .map((s) => `${s.projectId} (${s.email || "unknown"})`)
989
- .join(", ")}`,
990
- { prefix: "Auth" }
991
- );
992
- } else {
993
- MessageFormatter.error("No Appwrite configuration found", undefined, {
994
- prefix: "CLI",
995
- });
996
- MessageFormatter.info("Authentication options:", { prefix: "Auth" });
997
- MessageFormatter.info(
998
- "• Login with Appwrite CLI: Run 'appwrite login' then use --session flag",
999
- { prefix: "Auth" }
1000
- );
1001
- MessageFormatter.info("• Use API key: Add --apiKey YOUR_API_KEY", {
1002
- prefix: "Auth",
1003
- });
1004
- MessageFormatter.info(
1005
- "• Create config file: Run with --setup to initialize project configuration",
1006
- { prefix: "Auth" }
1007
- );
1008
- }
1009
- return;
1010
- }
1011
-
1012
- const parsedArgv = argv;
1013
-
1014
845
  // List backups if requested
1015
846
  if (parsedArgv.listBackups) {
1016
- const { AdapterFactory } = await import("./adapters/AdapterFactory.js");
847
+ const { AdapterFactory } = await import("@njdamstra/appwrite-utils-helpers");
1017
848
  const { listBackups } = await import("./shared/backupTracking.js");
1018
849
 
1019
850
  if (!controller.config) {
@@ -1150,7 +981,7 @@ async function main() {
1150
981
  const { comprehensiveBackup } = await import(
1151
982
  "./backups/operations/comprehensiveBackup.js"
1152
983
  );
1153
- const { AdapterFactory } = await import("./adapters/AdapterFactory.js");
984
+ const { AdapterFactory } = await import("@njdamstra/appwrite-utils-helpers");
1154
985
 
1155
986
  // Get tracking database ID (interactive prompt if not specified)
1156
987
  let trackingDatabaseId = parsedArgv.trackingDatabaseId;
@@ -1397,7 +1228,10 @@ async function main() {
1397
1228
 
1398
1229
  // Build DatabaseSelection[] with tableIds per DB
1399
1230
  const databaseSelections: DatabaseSelection[] = [];
1400
- const allConfigItems = controller.config.collections || controller.config.tables || [];
1231
+ const allConfigItems = [
1232
+ ...(controller.config.collections || []),
1233
+ ...(controller.config.tables || [])
1234
+ ];
1401
1235
  let lastSelectedTableIds: string[] | null = null;
1402
1236
 
1403
1237
  for (const dbId of selectedDbIds) {
@@ -1413,8 +1247,16 @@ async function main() {
1413
1247
  return true; // eligible everywhere if unspecified
1414
1248
  });
1415
1249
 
1416
- // Fetch available tables from remote for selection context
1250
+ // Fetch available tables from remote for status/context
1417
1251
  const availableTables = await fetchAllCollections(dbId, controller.database);
1252
+ const remoteTableIds = new Set(availableTables.map(table => table.$id));
1253
+ const localItems = eligibleConfigItems;
1254
+ const localItemIds = localItems.map(item => item.$id || (item as any).id || (item as any).tableId || item.name);
1255
+ const localNewItems = localItems.filter(item => {
1256
+ const itemId = item.$id || (item as any).id || (item as any).tableId || item.name;
1257
+ return !remoteTableIds.has(itemId);
1258
+ });
1259
+ const localNewIds = localNewItems.map(item => item.$id || (item as any).id || (item as any).tableId || item.name);
1418
1260
 
1419
1261
  // Determine selected table IDs
1420
1262
  let selectedTableIds: string[] = [];
@@ -1422,50 +1264,64 @@ async function main() {
1422
1264
  // Non-interactive: respect provided table IDs as-is (apply to each selected DB)
1423
1265
  selectedTableIds = parsedArgv.collectionIds.split(/[\,\s]+/).filter(Boolean);
1424
1266
  } else {
1425
- // If we have a previous selection, offer to reuse it
1267
+ const inquirer = (await import("inquirer")).default;
1268
+ const choices: Array<{ name: string; value: string }> = [];
1269
+
1426
1270
  if (lastSelectedTableIds && lastSelectedTableIds.length > 0) {
1427
- const inquirer = (await import("inquirer")).default;
1428
- const { reuseMode } = await inquirer.prompt([
1429
- {
1430
- type: "list",
1431
- name: "reuseMode",
1432
- message: `How do you want to select tables for ${db.name}?`,
1433
- choices: [
1434
- { name: `Use same selection as previous (${lastSelectedTableIds.length} items)`, value: "same" },
1435
- { name: `Filter by this database (manual select)`, value: "filter" },
1436
- { name: `Show all available in this database (manual select)`, value: "all" }
1437
- ],
1438
- default: "same"
1439
- }
1440
- ]);
1441
-
1442
- if (reuseMode === "same") {
1443
- selectedTableIds = [...lastSelectedTableIds];
1444
- } else if (reuseMode === "all") {
1445
- selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
1446
- dbId,
1447
- db.name,
1448
- availableTables,
1449
- allConfigItems as any[],
1450
- { showSelectAll: false, allowNewOnly: false, defaultSelected: lastSelectedTableIds }
1451
- );
1271
+ choices.push({
1272
+ name: `Use same selection as previous (${lastSelectedTableIds.length} items)`,
1273
+ value: "same"
1274
+ });
1275
+ }
1276
+
1277
+ if (localItemIds.length > 0) {
1278
+ choices.push({
1279
+ name: `Select all local items for ${db.name} (${localItemIds.length} items)`,
1280
+ value: "all_local"
1281
+ });
1282
+ }
1283
+
1284
+ if (localNewIds.length > 0) {
1285
+ choices.push({
1286
+ name: `Select only new local items (not on remote) (${localNewIds.length} items)`,
1287
+ value: "new_only"
1288
+ });
1289
+ }
1290
+
1291
+ choices.push({
1292
+ name: "Manual selection",
1293
+ value: "manual"
1294
+ });
1295
+
1296
+ const { selectionMode } = await inquirer.prompt([
1297
+ {
1298
+ type: "list",
1299
+ name: "selectionMode",
1300
+ message: `How do you want to select tables for ${db.name}?`,
1301
+ choices,
1302
+ default: choices[0]?.value || "manual"
1303
+ }
1304
+ ]);
1305
+
1306
+ if (selectionMode === "same") {
1307
+ selectedTableIds = [...(lastSelectedTableIds || [])];
1308
+ } else if (selectionMode === "all_local") {
1309
+ selectedTableIds = [...localItemIds];
1310
+ } else if (selectionMode === "new_only") {
1311
+ selectedTableIds = [...localNewIds];
1312
+ } else {
1313
+ if (localItems.length === 0) {
1314
+ MessageFormatter.warning(`No local tables/collections available for ${db.name}`, { prefix: "Push" });
1315
+ selectedTableIds = [];
1452
1316
  } else {
1453
1317
  selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
1454
1318
  dbId,
1455
1319
  db.name,
1456
- availableTables,
1457
- eligibleConfigItems,
1458
- { showSelectAll: false, allowNewOnly: true, defaultSelected: lastSelectedTableIds }
1320
+ localItems as any[],
1321
+ availableTables as any[],
1322
+ { showSelectAll: localItems.length > 1, allowNewOnly: false, defaultSelected: lastSelectedTableIds || [] }
1459
1323
  );
1460
1324
  }
1461
- } else {
1462
- selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
1463
- dbId,
1464
- db.name,
1465
- availableTables,
1466
- eligibleConfigItems,
1467
- { showSelectAll: false, allowNewOnly: true, defaultSelected: [] }
1468
- );
1469
1325
  }
1470
1326
  }
1471
1327
 
@@ -10,14 +10,13 @@ import { InputFile } from "node-appwrite/file";
10
10
  import path from "path";
11
11
  import fs from "fs";
12
12
  import os from "os";
13
- import { logger } from "../shared/logging.js";
13
+ import { logger, MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
14
14
  import {
15
15
  tryAwaitWithRetry,
16
16
  type AfterImportActions,
17
17
  type AppwriteConfig,
18
18
  } from "@njdamstra/appwrite-utils";
19
- import { getClientFromConfig } from "../utils/getClientFromConfig.js";
20
- import { MessageFormatter } from "../shared/messageFormatter.js";
19
+ import { getClientFromConfig } from "@njdamstra/appwrite-utils-helpers";
21
20
 
22
21
  export const getDatabaseFromConfig = (config: AppwriteConfig) => {
23
22
  getClientFromConfig(config); // Sets config.appwriteClient if missing
@@ -1,5 +1,4 @@
1
- import { SchemaGenerator } from "../shared/schemaGenerator.js";
2
- import { findYamlConfig } from "../config/yamlConfig.js";
1
+ import { SchemaGenerator, findYamlConfig } from "@njdamstra/appwrite-utils-helpers";
3
2
  import {
4
3
  Client,
5
4
  Compression,
@@ -26,12 +25,12 @@ import {
26
25
  type Specification,
27
26
  } from "@njdamstra/appwrite-utils";
28
27
  import { getDatabaseFromConfig } from "./afterImportActions.js";
29
- import { getAdapterFromConfig } from "../utils/getClientFromConfig.js";
28
+ import { getAdapterFromConfig } from "@njdamstra/appwrite-utils-helpers";
30
29
  import { listBuckets } from "../storage/methods.js";
31
30
  import { listFunctions, listFunctionDeployments, getFunction } from "../functions/methods.js";
32
- import { MessageFormatter } from "../shared/messageFormatter.js";
33
- import { isLegacyDatabases } from "../utils/typeGuards.js";
34
- import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
31
+ import { MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
32
+ import { isLegacyDatabases } from "@njdamstra/appwrite-utils-helpers";
33
+ import type { DatabaseAdapter } from "@njdamstra/appwrite-utils-helpers";
35
34
  import type { DatabaseSelection, BucketSelection } from "../shared/selectionDialogs.js";
36
35
 
37
36
  /**
@@ -121,8 +120,13 @@ export class AppwriteToX {
121
120
  const client = new Client();
122
121
  client
123
122
  .setEndpoint(this.config.appwriteEndpoint)
124
- .setProject(this.config.appwriteProject)
125
- .setKey(this.config.appwriteKey);
123
+ .setProject(this.config.appwriteProject);
124
+
125
+ // Only set API key if provided (session auth is alternative)
126
+ if (this.config.appwriteKey) {
127
+ client.setKey(this.config.appwriteKey);
128
+ }
129
+
126
130
  this.config.appwriteClient = client;
127
131
  }
128
132
  }
@@ -16,10 +16,9 @@ import {
16
16
  AppwriteException,
17
17
  } from "node-appwrite";
18
18
  import { InputFile } from "node-appwrite/file";
19
- import { MessageFormatter } from "../shared/messageFormatter.js";
19
+ import { MessageFormatter, getClient } from "@njdamstra/appwrite-utils-helpers";
20
20
  import { processQueue, queuedOperations } from "../shared/operationQueue.js";
21
21
  import { ProgressManager } from "../shared/progressManager.js";
22
- import { getClient } from "../utils/getClientFromConfig.js";
23
22
  import {
24
23
  transferDatabaseLocalToLocal,
25
24
  transferDatabaseLocalToRemote,
@@ -36,9 +35,8 @@ import pLimit from "p-limit";
36
35
  import chalk from "chalk";
37
36
  import { join } from "node:path";
38
37
  import fs from "node:fs";
39
- import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
40
- import { getAdapter } from "../utils/getClientFromConfig.js";
41
- import { mapToCreateAttributeParams } from "../shared/attributeMapper.js";
38
+ import type { DatabaseAdapter } from "@njdamstra/appwrite-utils-helpers";
39
+ import { getAdapter, mapToCreateAttributeParams } from "@njdamstra/appwrite-utils-helpers";
42
40
 
43
41
  export interface ComprehensiveTransferOptions {
44
42
  sourceEndpoint: string;
@@ -1277,7 +1275,9 @@ export class ComprehensiveTransfer {
1277
1275
  await deployLocalFunction(
1278
1276
  this.targetClient,
1279
1277
  func.name,
1280
- functionConfig
1278
+ functionConfig,
1279
+ undefined,
1280
+ this.tempDir
1281
1281
  );
1282
1282
 
1283
1283
  this.results.functions.transferred++;