@adobe/aio-cli-plugin-app-storage 1.0.3 → 1.2.0-pre.2025-11-18.sha-9c4079ac

package/src/commands/app/db/index/create.js

@@ -0,0 +1,170 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { DBBaseCommand } from '../../../../DBBaseCommand.js'
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import { asObject, isNonEmptyString } from '../../../../utils/inputValidation.js'
+import { prettyJson } from '../../../../utils/output.js'
+
+// Regular expression to match the -s/--spec or -k/--key flags in <flag>=<value> format
+// if match.groups.spec is defined, it means the flag was -s or --spec
+// if match.groups.key is defined, it means the flag was -k or --key
+const specFlagMatch = /^((?<spec>-s|--spec)|(?<key>-k|--key))=(?<val>.+)/
+
+export class Create extends DBBaseCommand {
+  getOrderedSpecs () {
+    // Key/spec order matters when creating an index and both key and spec can be specified,
+    // so we need to parse argv to obtain the proper order since using this.flags loses the order between the two
+    const args = this.argv.slice(1) // Ignore the first element (collection name)
+    const fullSpec = []
+    let specOption = false
+    args.forEach((arg) => {
+      if (specOption === 'key') {
+        // Previous arg was -k or --key
+        fullSpec.push(arg)
+        specOption = false
+      } else if (specOption === 'spec') {
+        // Previous arg was -s or --spec
+        fullSpec.push(asObject(arg))
+        specOption = false
+      } else if (arg === '-k' || arg === '--key') {
+        // Next arg is a key
+        specOption = 'key'
+      } else if (arg === '-s' || arg === '--spec') {
+        // Next arg is a spec
+        specOption = 'spec'
+      } else {
+        // Check if the arg is in the form of -s=<val>/--spec=<val> or -k=<val>/--key=<val>
+        const specMatch = arg.match(specFlagMatch)
+        if (specMatch?.groups?.spec) {
+          // Spec is a JSON object
+          fullSpec.push(asObject(specMatch.groups.val))
+        } else if (specMatch?.groups?.key) {
+          // Key is a string
+          fullSpec.push(specMatch.groups.val)
+        }
+        specOption = false
+      }
+    })
+
+    return fullSpec
+  }
+
+  async run () {
+    const { collection } = this.args
+    const { name, unique } = this.flags
+
+    try {
+      const fullSpec = this.getOrderedSpecs()
+      const prettySpec = prettyJson(fullSpec)
+
+      this.log(chalk.blue(`Creating index ${name ? `'${name}' ` : ''}on collection '${collection}'...`))
+      this.log(chalk.dim(`   Specification:\n${prettySpec}`))
+      if (unique) this.log(chalk.dim(`   Unique index: ${unique}`))
+
+      const client = await this.db.connect()
+      const coll = await client.collection(collection)
+
+      // Build options
+      const options = {}
+      if (name) options.name = name
+      if (unique) options.unique = unique
+
+      const result = await coll.createIndex(fullSpec, options)
+
+      this.debugLogger?.info?.('Index created successfully:', result)
+
+      const response = {
+        collection,
+        indexName: result,
+        specification: fullSpec,
+        status: 'created',
+        namespace: this.rtNamespace,
+        timestamp: new Date().toISOString()
+      }
+
+      if (Object.keys(options).length > 0) response.options = options
+
+      this.log(chalk.green(`Index '${result}' created successfully in the '${collection}' collection`))
+      this.log(chalk.dim(`   Specification:\n${prettySpec}`))
+      if (unique) this.log(chalk.dim(`   Unique: ${unique}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Created: ${new Date().toLocaleString()}`))
+
+      return response
+    } catch (error) {
+      this.debugLogger?.error?.('Error creating index:', error)
+
+      this.log(chalk.red('Failed to create index'))
+      this.log(chalk.dim(`   Collection: ${collection}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+
+      this.error(`Failed to create index on collection '${collection}': ${error.message}`)
+    }
+  }
+}
+
+Create.description = 'Create a new index on a collection in the database'
+
+Create.examples = [
+  '$ aio app db index create users --spec \'{"name":1, "age":-1}\'',
+  '$ aio app db index create users -s \'{"name":1, "age":-1}\' --name "name_age_index"',
+  '$ aio app db index create students -s \'{"name":1}\' --key grade --unique',
+  '$ aio app db index create reviews -k sku -k rating',
+  '$ aio app db index create products -s \'{"name":"text", "category":"text"}\' --json',
+  '$ aio app db index create books -s \'{"author":1}\' -k year',
+  '$ aio app db idx create orders --spec \'{"customerId":1}\' --spec \'{"orderDate":-1}\' --name "customer_order_index" --unique'
+]
+
+Create.args = {
+  collection: Args.string({
+    name: 'collection',
+    description: 'The name of the collection to create the index on',
+    required: true,
+    parse: input => isNonEmptyString(input, 'Collection name')
+  })
+}
+
+Create.flags = {
+  ...DBBaseCommand.flags,
+  spec: Flags.string({
+    char: 's',
+    helpGroup: 'Requires at least one of the index definition',
+    description: 'Index specification as a JSON object (e.g., \'{"name":1, "age":-1}\')',
+    multiple: true,
+    atLeastOne: ['key', 'spec'],
+    parse: input => asObject(input, 'Index specification')
+  }),
+  key: Flags.string({
+    char: 'k',
+    helpGroup: 'Requires at least one of the index definition',
+    description: 'Index key to use with default specification',
+    multiple: true,
+    atLeastOne: ['key', 'spec'],
+    // Note: untrimmed whitespace input is allowed for index keys
+    parse: input => isNonEmptyString(input, 'Index key')
+  }),
+  name: Flags.string({
+    char: 'n',
+    description: 'A name that uniquely identifies the index',
+    // Note: untrimmed whitespace input is allowed for index names
+    parse: input => isNonEmptyString(input, 'Index name')
+  }),
+  unique: Flags.boolean({
+    char: 'u',
+    description: 'Creates a unique index so that the collection will not accept insertion or update of documents where the index key value matches an existing value in the index',
+    default: false
+  })
+}
+
+Create.aliases = ['app:db:idx:create']

package/src/commands/app/db/index/drop.js

@@ -0,0 +1,87 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { DBBaseCommand } from '../../../../DBBaseCommand.js'
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import { isNonEmptyString } from '../../../../utils/inputValidation.js'
+import { prettyJson } from '../../../../utils/output.js'
+
+export class Drop extends DBBaseCommand {
+  async run () {
+    const { collection, indexName } = this.args
+
+    try {
+      this.log(chalk.blue(`Dropping index '${indexName}' from collection '${collection}'...`))
+
+      const client = await this.db.connect()
+      const coll = await client.collection(collection)
+
+      const result = await coll.dropIndex(indexName)
+
+      this.debugLogger?.info?.('Index dropped successfully:', result)
+
+      const response = {
+        collection,
+        indexName,
+        status: 'dropped',
+        namespace: this.rtNamespace,
+        timestamp: new Date().toISOString(),
+        result
+      }
+
+      this.log(chalk.green(`Index '${indexName}' dropped successfully`))
+      this.log(chalk.dim(`   Details:\n${prettyJson(result)}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Dropped: ${new Date().toLocaleString()}`))
+
+      return response
+    } catch (error) {
+      this.debugLogger?.error?.('Error dropping index:', error)
+
+      this.log(chalk.red('Failed to drop index'))
+      this.log(chalk.dim(`   Collection: ${collection}`))
+      this.log(chalk.dim(`   Index: ${indexName}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Error: ${error.message}`))
+
+      this.error(`Failed to drop index '${indexName}' from collection '${collection}': ${error.message}`)
+    }
+  }
+}
+
+Drop.description = 'Drop an index from a collection in the database'
+
+Drop.examples = [
+  '$ aio app db index drop users name_age_index',
+  '$ aio app db index drop products category_1 --json',
+  '$ aio app db idx drop orders orderDate_index'
+]
+
+Drop.args = {
+  collection: Args.string({
+    name: 'collection',
+    description: 'The name of the collection to drop the index from',
+    required: true,
+    parse: input => isNonEmptyString(input, 'Collection name')
+  }),
+  indexName: Args.string({
+    name: 'indexName',
+    description: 'The name of the index to drop',
+    required: true,
+    parse: input => isNonEmptyString(input, 'Index name')
+  })
+}
+
+Drop.flags = DBBaseCommand.flags
+
+Drop.aliases = ['app:db:idx:drop']

package/src/commands/app/db/index/list.js

@@ -0,0 +1,82 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { DBBaseCommand } from '../../../../DBBaseCommand.js'
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import { isNonEmptyString } from '../../../../utils/inputValidation.js'
+import { prettyJson } from '../../../../utils/output.js'
+
+export class List extends DBBaseCommand {
+  async run () {
+    const { collection } = this.args
+
+    try {
+      this.log(chalk.blue(`Getting indexes from collection '${collection}'...`))
+
+      const client = await this.db.connect()
+      const coll = await client.collection(collection)
+
+      const result = await coll.getIndexes()
+
+      this.debugLogger?.info?.('Indexes retrieved successfully:', result)
+
+      const response = {
+        collection,
+        namespace: this.rtNamespace,
+        timestamp: new Date().toISOString(),
+        indexes: result
+      }
+
+      this.log(chalk.green('Indexes retrieved successfully'))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Retrieved: ${new Date().toLocaleString()}`))
+      if (result && Array.isArray(result) && result.length > 0) {
+        this.log(chalk.dim(`   Indexes:\n${prettyJson(result)}`))
+      } else {
+        this.log(chalk.dim('   No indexes found for this collection'))
+      }
+
+      return response
+    } catch (error) {
+      this.debugLogger?.error?.('Error getting indexes:', error)
+
+      this.log(chalk.red('Failed to retrieve indexes'))
+      this.log(chalk.dim(`   Collection: ${collection}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Error: ${error.message}`))
+
+      this.error(`Failed to retrieve indexes from collection '${collection}': ${error.message}`)
+    }
+  }
+}
+
+List.description = 'Get the list of indexes from a collection in the database'
+
+List.examples = [
+  '$ aio app db index list users',
+  '$ aio app db index list products --json',
+  '$ aio app db idx list orders'
+]
+
+List.args = {
+  collection: Args.string({
+    name: 'collection',
+    description: 'The name of the collection to retrieve indexes from',
+    required: true,
+    parse: input => isNonEmptyString(input, 'Collection name')
+  })
+}
+
+List.flags = DBBaseCommand.flags
+
+List.aliases = ['app:db:idx:list']

package/src/commands/app/db/ping.js

@@ -0,0 +1,77 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { DBBaseCommand } from '../../../DBBaseCommand.js'
+import chalk from 'chalk'
+
+export class Ping extends DBBaseCommand {
+  async run () {
+    try {
+      this.log(chalk.blue('Testing database connectivity...'))
+
+      const startTime = Date.now()
+      const pingResult = await this.db.ping()
+      const endTime = Date.now()
+      const responseTime = endTime - startTime
+
+      this.debugLogger?.info?.(`Database ping completed in ${responseTime}ms:`, pingResult)
+
+      this.log(chalk.green('Database connection successful'))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Response time: ${responseTime}ms`))
+
+      if (typeof pingResult === 'string') {
+        this.log(chalk.dim(`   Response: ${pingResult}`))
+      }
+
+      const result = {
+        status: 'success',
+        namespace: this.rtNamespace,
+        responseTime,
+        response: pingResult,
+        timestamp: new Date().toISOString()
+      }
+
+      this.log(chalk.dim('Database is ready for operations'))
+
+      return result
+    } catch (error) {
+      this.debugLogger?.error?.('Ping command error:', error)
+
+      this.log(chalk.red('Database connection failed'))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Error: ${error.message}`))
+
+      const result = {
+        status: 'failed',
+        namespace: this.rtNamespace,
+        error: error.message,
+        timestamp: new Date().toISOString()
+      }
+
+      return result
+    }
+  }
+}
+
+Ping.description = 'Test connectivity to your App Builder database'
+
+Ping.examples = [
+  '$ aio app db ping',
+  '$ aio app db ping --json'
+]
+
+Ping.flags = {
+  ...DBBaseCommand.flags
+}
+
+Ping.args = {}

package/src/commands/app/db/provision.js

@@ -0,0 +1,190 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { DBBaseCommand } from '../../../DBBaseCommand.js'
+import chalk from 'chalk'
+import { DB_STATUS } from '../../../constants/db.js'
+import { Flags } from '@oclif/core'
+
+export class Provision extends DBBaseCommand {
+  async run () {
+    const region = this.db.region
+
+    try {
+      // First check if database is already provisioned
+      this.log(chalk.blue('Checking current provisioning status...'))
+
+      let provisionStatusResponse
+      try {
+        provisionStatusResponse = await this.db.provisionStatus()
+        this.debugLogger?.info?.('Provision status:', provisionStatusResponse)
+      } catch (error) {
+        this.debugLogger?.info?.('No existing provisioning status found:', error.message)
+        provisionStatusResponse = null
+      }
+
+      if (provisionStatusResponse) {
+        const currentStatus = provisionStatusResponse.status.toUpperCase()
+        const statusRegion = provisionStatusResponse.region
+
+        if (currentStatus === DB_STATUS.PROVISIONED) {
+          this.log(chalk.green('Database is already provisioned and ready for use'))
+          this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+          this.log(chalk.dim(`   Region: ${statusRegion}`))
+          this.log(chalk.dim(`   Status: ${currentStatus}`))
+
+          return {
+            status: 'already_provisioned',
+            namespace: this.rtNamespace,
+            details: provisionStatusResponse
+          }
+        } else if (currentStatus === DB_STATUS.REQUESTED) {
+          this.log(chalk.yellow('Database provisioning request has been submitted and is pending'))
+          this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+          this.log(chalk.dim(`   Region: ${statusRegion}`))
+          this.log(chalk.dim(`   Status: ${currentStatus}`))
+          this.log(chalk.dim('\nUse "aio app db status --watch" to monitor progress'))
+
+          return {
+            status: 'in_progress',
+            namespace: this.rtNamespace,
+            details: provisionStatusResponse
+          }
+        } else if (currentStatus === DB_STATUS.PROCESSING) {
+          this.log(chalk.yellow('Database is currently being provisioned'))
+          this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+          this.log(chalk.dim(`   Region: ${statusRegion}`))
+          this.log(chalk.dim(`   Status: ${currentStatus}`))
+          this.log(chalk.dim('\nUse "aio app db status --watch" to monitor progress'))
+          this.log(chalk.red('If provisioning takes unusually long, please contact the App Builder team'))
+
+          return {
+            status: 'in_progress',
+            namespace: this.rtNamespace,
+            details: provisionStatusResponse
+          }
+        } else if (currentStatus === DB_STATUS.FAILED) {
+          this.log(chalk.red('Previous database provisioning failed'))
+          this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+          this.log(chalk.dim(`   Status: ${currentStatus}`))
+          this.log(chalk.yellow('\nAttempting to provision again...'))
+          this.log(chalk.red('If the problem persists, please contact the App Builder team'))
+        } else if (currentStatus === DB_STATUS.REJECTED) {
+          this.log(chalk.red('Previous database provisioning request was rejected'))
+          this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+          this.log(chalk.dim(`   Status: ${currentStatus}`))
+          this.log(chalk.yellow('\nAttempting to provision again...'))
+          this.log(chalk.red('If the problem persists, please contact the App Builder team for assistance'))
+        } else if (currentStatus !== DB_STATUS.NOT_PROVISIONED) {
+          this.log(chalk.yellow(`Database status is '${currentStatus}' - attempting to provision...`))
+          this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+          this.log(chalk.dim(`   Status: ${currentStatus}`))
+          this.log(chalk.red('If you encounter issues, please contact the App Builder team'))
+        }
+      }
+
+      // Create a new database if not yet provisioned
+      this.warn('Database provisioning will create new database resources')
+
+      // Skip confirmation prompt if --yes flag is used
+      if (!this.flags.yes) {
+        // eslint-disable-next-line node/no-unsupported-features/es-syntax
+        const { confirm } = await import('@inquirer/prompts')
+
+        const confirmed = await confirm({
+          message: `Provision database for namespace '${this.rtNamespace}'?`,
+          default: false
+        })
+
+        if (!confirmed) {
+          this.log('Database provisioning cancelled')
+          return { status: 'cancelled' }
+        }
+      }
+
+      // Start provisioning
+      this.log(chalk.blue(`Submitting a request for a database to be provisioned for the '${this.rtNamespace}' namespace...`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Region: ${region}`))
+
+      const provisionResult = await this.db.provisionRequest()
+      this.debugLogger?.info?.('Provision request result:', provisionResult)
+
+      // Handle different provision result statuses
+      const resultStatus = provisionResult?.status?.toUpperCase() || DB_STATUS.UNKNOWN
+
+      if (resultStatus === DB_STATUS.PROVISIONED) {
+        this.log(chalk.green('Database provisioned successfully and ready for use!'))
+      } else if (resultStatus === DB_STATUS.REQUESTED) {
+        this.log(chalk.blue('Database provisioning request submitted successfully'))
+        this.log(chalk.dim('Provisioning is now pending...'))
+      } else if (resultStatus === DB_STATUS.PROCESSING) {
+        this.log(chalk.yellow('Database is being provisioned...'))
+      } else if (resultStatus === DB_STATUS.FAILED) {
+        this.error(`Database provisioning failed: ${provisionResult.message || 'Unknown error'}`)
+      } else if (resultStatus === DB_STATUS.REJECTED) {
+        this.error(`Database provisioning request was rejected: ${provisionResult.message || 'Unknown reason'}`)
+      } else if (resultStatus === DB_STATUS.UNKNOWN) {
+        this.warn(`Database provisioning request returned unrecognized status '${provisionResult.status || 'undefined'}', an update to the aio cli tool may be necessary.`)
+        this.warn('If the issue persists, please contact the App Builder team.')
+      } else {
+        this.warn(`Database provisioning request returned unexpected status '${resultStatus}', an update to the aio cli tool may be necessary.`)
+        this.warn('If the issue persists, please contact the App Builder team.')
+      }
+
+      const result = {
+        status: resultStatus.toLowerCase(),
+        namespace: this.rtNamespace,
+        timestamp: new Date().toISOString(),
+        details: provisionResult
+      }
+
+      // If region was specified as a CLI flag, include it in the output for next steps
+      const { region: regionFlag } = this.flags
+      const regionFlagString = regionFlag ? ` --region ${regionFlag}` : ''
+
+      if (resultStatus !== DB_STATUS.PROVISIONED) {
+        this.log(chalk.dim('\nNext steps:'))
+        this.log(chalk.dim(`   - Monitor progress: aio app db status${regionFlagString} --watch`))
+        this.log(chalk.dim(`   - Check status: aio app db status${regionFlagString}`))
+      } else {
+        this.log(chalk.dim('\nNext steps:'))
+        this.log(chalk.dim(`   - Test connection: aio app db ping${regionFlagString}`))
+      }
+
+      return result
+    } catch (error) {
+      this.debugLogger?.error?.('Provision command error:', error)
+      this.error(`Database provisioning failed: ${error.message}`)
+    }
+  }
+}
+
+Provision.description = 'Provision a new database for your App Builder application'
+
+Provision.examples = [
+  '$ aio app db provision',
+  '$ aio app db provision --region amer',
+  '$ aio app db provision --json',
+  '$ aio app db provision --yes'
+]
+
+Provision.flags = {
+  ...DBBaseCommand.flags,
+  yes: Flags.boolean({
+    char: 'y',
+    description: 'Skip confirmation prompt and provision automatically',
+    default: false
+  })
+}
+
+Provision.args = {}