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

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "@adobe/aio-cli-plugin-app-storage",
-  "version": "1.0.3",
+  "version": "1.2.0-pre.2025-11-18.sha-9c4079ac",
   "dependencies": {
     "@adobe/aio-lib-core-config": "^5",
     "@adobe/aio-lib-core-logging": "^3",
+    "@adobe/aio-lib-db": "^0.1.0-beta.2",
+    "@adobe/aio-lib-env": "^3.0.1",
     "@adobe/aio-lib-state": "^5",
     "@inquirer/prompts": "^5",
     "@oclif/core": "^4",
     "@oclif/plugin-help": "^6",
+    "@oclif/table": "^0.5.0",
     "chalk": "^5",
+    "dotenv": "^16.5.0",
     "semver": "^7.6.3"
   },
   "devDependencies": {
-    "@adobe/eslint-config-aio-lib-config": "^4",
+    "@adobe/eslint-config-aio-lib-config": "^4.0.0",
     "@jest/globals": "^29",
-    "eslint": "^8",
+    "eslint": "^8.57.1",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jest": "^27.9.0",
+    "eslint-plugin-jsdoc": "^48.11.0",
+    "eslint-plugin-n": "^15.7.0",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^6.6.0",
     "execa": "^8",
     "jest": "^29",
     "memfs": "^4.11.1",
@@ -39,6 +50,18 @@
     "topics": {
       "app:state": {
         "description": "Manage your App Builder State storage"
+      },
+      "app:db": {
+        "description": "Manage your App Builder Database storage"
+      },
+      "app:db:collection": {
+        "description": "Manage database collections, also available under 'aio app db col <command>'"
+      },
+      "app:db:document": {
+        "description": "Manage documents in a collection, also available under 'aio app db doc <command>'"
+      },
+      "app:db:index": {
+        "description": "Manage indexes on a collection, also available under 'aio app db idx <command>'"
       }
     },
     "bin": "aio",
@@ -64,6 +87,10 @@
   "jest": {
     "collectCoverage": true,
     "testEnvironment": "node",
-    "transform": {}
-  }
-}
+    "transform": {},
+    "setupFiles": [
+      "<rootDir>/test/jest.env.js"
+    ]
+  },
+  "prereleaseSha": "9c4079accc13a54a5b5c0229f13c35b5573123ab"
+}

package/src/BaseCommand.js

@@ -10,24 +10,19 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
-import { Command, Flags } from '@oclif/core'
-import config from '@adobe/aio-lib-core-config'
+import { Command } from '@oclif/core'
 import AioLogger from '@adobe/aio-lib-core-logging'
-
-import { CONFIG_STATE_REGION } from './constants.js'
 import chalk from 'chalk'
-import semver from 'semver'
 
 export class BaseCommand extends Command {
   async init () {
     await super.init()
-    // eslint-disable-next-line node/no-unsupported-features/es-syntax
-    const { readFile } = await import('fs/promises') // dynamic import to be able to mock fs, ESM and Jest are not friends
 
     // setup debug logger
     const command = this.constructor.name.toLowerCase() // hacky but convenient
+    const serviceName = this.getServiceName() // Get service name dynamically
     this.debugLogger = AioLogger(
-      `aio:app:state:${command}`,
+      `aio:app:${serviceName}:${command}`,
       { provider: 'debug' }
     )
     // override warn to stderr
@@ -38,50 +33,14 @@ export class BaseCommand extends Command {
     this.flags = flags
     this.args = args
     this.debugLogger.debug(`${command} args=${JSON.stringify(this.args)} flags=${JSON.stringify(this.flags)}`)
+  }
 
-    // check application dependencies
-    let packageJson
-    try {
-      const file = await readFile('package.json')
-      packageJson = JSON.parse(file.toString())
-    } catch (e) {
-      this.debugLogger.debug('package.json not found, skipping dependency check')
-    }
-    if (packageJson) {
-      const aioLibStateVersion = packageJson.dependencies?.['@adobe/aio-lib-state']
-      const aioSdkVersion = packageJson.dependencies?.['@adobe/aio-sdk']
-      if ((aioLibStateVersion && semver.lt(semver.coerce(aioLibStateVersion), '4.0.0')) ||
-        (aioSdkVersion && semver.lt(semver.coerce(aioSdkVersion), '6.0.0'))) {
-        this.error('State commands are not available for legacy State, please migrate to the latest "@adobe/aio-lib-state" (or "@adobe/aio-sdk" >= 6.0.0).')
-      }
-    }
-
-    // init state client
-    const owOptions = {
-      namespace: config.get('runtime.namespace'),
-      auth: config.get('runtime.auth')
-    }
-    if (!(owOptions.namespace && owOptions.auth)) {
-      this.error(
-`This command is expected to be run in the root of a App Builder app project.
-  Please make sure the 'AIO_RUNTIME_NAMESPACE' and 'AIO_RUNTIME_AUTH' environment variables are configured.`
-      )
-    }
-    const region = flags.region || config.get(CONFIG_STATE_REGION) || 'amer'
-    this.debugLogger.info('using state region: %s', region)
-
-    if (config.get('state.endpoint')) {
-      process.env.AIO_STATE_ENDPOINT = config.get('state.endpoint')
-      this.debugLogger.info('using custom endpoint: %s', process.env.AIO_STATE_ENDPOINT)
-    }
-    // dynamic import to be able to reload the AIO_STATE_ENDPOINT var
-    // eslint-disable-next-line node/no-unsupported-features/es-syntax
-    const State = await import('@adobe/aio-lib-state')
-
-    /** @type {import('@adobe/aio-lib-state').AdobeState} */
-    this.state = await State.init({ region, ow: owOptions })
-
-    this.rtNamespace = owOptions.namespace
+  /**
+   * Get the service name for logging
+   * @returns {string} The service name
+   */
+  getServiceName () {
+    return 'app' // Default fallback
   }
 
   async catch (error) {
@@ -105,12 +64,6 @@ export class BaseCommand extends Command {
 // display the JSON returned by the command's run method.
 BaseCommand.enableJsonFlag = true
 
-BaseCommand.flags = {
-  region: Flags.string({
-    description: 'State region. Defaults to \'AIO_STATE_REGION\' env or \'amer\' if neither is set.',
-    required: false,
-    options: ['amer', 'emea']
-  })
-}
+BaseCommand.flags = {}
 
 BaseCommand.args = {}

package/src/DBBaseCommand.js

@@ -0,0 +1,112 @@
+/*
+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 { BaseCommand } from './BaseCommand.js'
+import config from '@adobe/aio-lib-core-config'
+import { CONFIG_RUNTIME_AUTH, CONFIG_RUNTIME_NAMESPACE } from './constants/global.js'
+import { AVAILABLE_REGIONS, CONFIG_DB_ENDPOINT, CONFIG_DB_REGION, DEFAULT_REGION } from './constants/db.js'
+import { Flags } from '@oclif/core'
+import { getCliEnv } from '@adobe/aio-lib-env'
+
+export class DBBaseCommand extends BaseCommand {
+  async init () {
+    await super.init()
+
+    // Initialize database client
+    await this.initializeDBClient()
+
+    this.debugLogger?.info?.('DBBaseCommand initialized with DB client')
+  }
+
+  /**
+   * Initialize the database client using aio-lib-db
+   */
+  async initializeDBClient () {
+    try {
+      const region = this.flags?.region || config.get(CONFIG_DB_REGION) || DEFAULT_REGION
+      // Get database configuration
+      const dbConfig = {
+        ow: {
+          namespace: config.get(CONFIG_RUNTIME_NAMESPACE),
+          auth: config.get(CONFIG_RUNTIME_AUTH)
+        },
+        region
+      }
+
+      // Validate region based on environment
+      const allowedRegions = AVAILABLE_REGIONS[getCliEnv()]
+      if (!allowedRegions.includes(region)) {
+        this.error(`Invalid region '${region}' for the ${getCliEnv()} environment, must be one of: ${allowedRegions.join(', ')}`)
+      }
+
+      // Validate required configuration
+      if (!(dbConfig.ow.namespace && dbConfig.ow.auth)) {
+        this.error(
+          `Database commands require App Builder project configuration.
+Please make sure the 'AIO_RUNTIME_NAMESPACE' and 'AIO_RUNTIME_AUTH' environment variables are configured.`
+        )
+      }
+
+      const endpointOverride = config.get(CONFIG_DB_ENDPOINT)
+      if (endpointOverride) {
+        process.env.AIO_DB_ENDPOINT = endpointOverride
+        this.debugLogger?.info?.('Using custom endpoint: %s', process.env.AIO_DB_ENDPOINT)
+      }
+
+      // Dynamic import to be able to reload the AIO_DB_ENDPOINT var
+      // eslint-disable-next-line node/no-unsupported-features/es-syntax
+      const aioLibDb = await import('@adobe/aio-lib-db')
+      const { init } = aioLibDb.default || aioLibDb
+
+      this.debugLogger?.info?.('Initializing DB client with config:', {
+        namespace: dbConfig.ow.namespace,
+        region: dbConfig.region,
+        hasAuth: !!dbConfig.ow.auth
+      })
+
+      // Initialize the database client
+      this.db = await init(dbConfig)
+      this.dbConfig = dbConfig
+      this.rtNamespace = dbConfig.ow.namespace
+
+      this.debugLogger?.info?.('DB client initialized successfully')
+    } catch (error) {
+      this.debugLogger?.error?.('Failed to initialize DB client:', error.message)
+      this.error(`Failed to initialize database client: ${error.message}`)
+    }
+  }
+
+  /**
+   * Get the service name for logging
+   * @returns {string} The service name
+   */
+  getServiceName () {
+    return 'db'
+  }
+}
+
+// Add json and region flags to GLOBAL FLAGS section in --help output
+DBBaseCommand.flags = {
+  ...BaseCommand.flags,
+  json: {
+    description: 'Format output as json.',
+    default: false,
+    required: false,
+    helpGroup: 'GLOBAL'
+  },
+  region: Flags.string({
+    description: `Database region. Defaults to 'AIO_DB_REGION' environment variable or '${DEFAULT_REGION}' if neither is set.\n<options: ${AVAILABLE_REGIONS.prod.join('|')}>`,
+    required: false,
+    helpGroup: 'GLOBAL'
+    // Don't set default here to let it load from the environment var if not passed as a flag
+  })
+}

package/src/StateBaseCommand.js

@@ -0,0 +1,87 @@
+/*
+Copyright 2024 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 { BaseCommand } from './BaseCommand.js'
+import config from '@adobe/aio-lib-core-config'
+import { AVAILABLE_REGIONS, CONFIG_STATE_REGION, DEFAULT_REGION } from './constants/state.js'
+import { CONFIG_RUNTIME_NAMESPACE, CONFIG_RUNTIME_AUTH } from './constants/global.js'
+
+import semver from 'semver'
+import { Flags } from '@oclif/core'
+
+export class StateBaseCommand extends BaseCommand {
+  async init () {
+    await super.init()
+    // check application dependencies
+    let packageJson
+    try {
+      // eslint-disable-next-line node/no-unsupported-features/es-syntax
+      const { readFile } = await import('fs/promises')
+      const file = await readFile('package.json')
+      packageJson = JSON.parse(file.toString())
+    } catch (e) {
+      this.debugLogger?.debug?.('package.json not found, skipping dependency check')
+    }
+    if (packageJson) {
+      const aioLibStateVersion = packageJson.dependencies?.['@adobe/aio-lib-state']
+      const aioSdkVersion = packageJson.dependencies?.['@adobe/aio-sdk']
+      if ((aioLibStateVersion && semver.lt(semver.coerce(aioLibStateVersion), '4.0.0')) ||
+        (aioSdkVersion && semver.lt(semver.coerce(aioSdkVersion), '6.0.0'))) {
+        this.error('State commands are not available for legacy State, please migrate to the latest "@adobe/aio-lib-state" (or "@adobe/aio-sdk" >= 6.0.0).')
+      }
+    }
+
+    // init state client
+    const owOptions = {
+      namespace: config.get(CONFIG_RUNTIME_NAMESPACE),
+      auth: config.get(CONFIG_RUNTIME_AUTH)
+    }
+    if (!(owOptions.namespace && owOptions.auth)) {
+      this.error(
+`This command is expected to be run in the root of a App Builder app project.
+  Please make sure the 'AIO_RUNTIME_NAMESPACE' and 'AIO_RUNTIME_AUTH' environment variables are configured.`
+      )
+    }
+    const region = this.flags.region || config.get(CONFIG_STATE_REGION) || DEFAULT_REGION
+    this.debugLogger?.info?.('using state region: %s', region)
+
+    if (config.get('state.endpoint')) {
+      process.env.AIO_STATE_ENDPOINT = config.get('state.endpoint')
+      this.debugLogger?.info?.('using custom endpoint: %s', process.env.AIO_STATE_ENDPOINT)
+    }
+    // dynamic import to be able to reload the AIO_STATE_ENDPOINT var
+    // eslint-disable-next-line node/no-unsupported-features/es-syntax
+    const aioLibState = await import('@adobe/aio-lib-state')
+
+    /** @type {import('@adobe/aio-lib-state').AdobeState} */
+    this.state = await aioLibState.init({ region, ow: owOptions })
+
+    this.rtNamespace = owOptions.namespace
+  }
+
+  /**
+   * Get the service name for logging
+   * @returns {string} The service name
+   */
+  getServiceName () {
+    return 'state'
+  }
+}
+
+StateBaseCommand.flags = {
+  ...BaseCommand.flags,
+  region: Flags.string({
+    description: 'State region. Defaults to \'AIO_STATE_REGION\' env or \'amer\' if neither is set.',
+    required: false,
+    options: AVAILABLE_REGIONS
+  })
+}

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

@@ -0,0 +1,20 @@
+/*
+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 { Provision } from '../db/provision.js'
+
+// 'aio app add db' is an alias for 'aio app db provision', but to have it show up in
+// help correctly it needs its own class instead of using Provision.aliases
+export class AddDb extends Provision {}
+
+// Update the examples for the help display
+AddDb.examples = Provision.examples.map(example => example.replace('$ aio app db provision', '$ aio app add db'))

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

@@ -0,0 +1,119 @@
+/*
+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'
+
+export class CreateCollection extends DBBaseCommand {
+  async run () {
+    const { collection } = this.args
+    const { validator } = this.flags
+
+    try {
+      this.log(chalk.blue(`Creating collection '${collection}'...`))
+
+      // Log flag values if set
+      if (validator) {
+        this.log(chalk.dim(`   Using validator: ${validator}`))
+      }
+
+      const client = await this.db.connect()
+
+      // Check if collection already exists
+      const existingCollections = await client.listCollections()
+      const collectionExists = existingCollections && existingCollections.some(col => col.name === collection)
+
+      if (collectionExists) {
+        const errorMessage = `Collection '${collection}' already exists`
+
+        this.log(chalk.red(errorMessage))
+        this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+
+        this.error(errorMessage)
+      }
+
+      // Build collection options
+      const options = {}
+      if (validator) {
+        options.validator = { $jsonSchema: validator }
+      }
+
+      // Create the collection
+      const result = await client.createCollection(collection, options)
+
+      this.debugLogger?.info?.('Collection created successfully:', result)
+
+      const response = {
+        collection,
+        status: 'created',
+        namespace: this.rtNamespace,
+        timestamp: new Date().toISOString(),
+        options
+      }
+
+      this.log(chalk.green(`Collection '${collection}' created successfully`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+
+      if (validator) {
+        // Display the final validator object (after parsing) in compact JSON format
+        const validatorDisplay = JSON.stringify(options.validator.$jsonSchema)
+        this.log(chalk.dim(`   Validator: ${validatorDisplay}`))
+      }
+
+      this.log(chalk.dim(`   Created: ${new Date().toLocaleString()}`))
+
+      return response
+    } catch (error) {
+      this.debugLogger?.error?.('Error creating collection:', error)
+
+      const errorMessage = `Failed to create collection '${collection}': ${error.message}`
+
+      this.log(chalk.red('Failed to create collection'))
+      this.log(chalk.dim(`   Collection: ${collection}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Error: ${error.message}`))
+
+      this.error(errorMessage)
+    }
+  }
+}
+
+CreateCollection.description = 'Create a new collection in the database'
+
+CreateCollection.examples = [
+  '$ aio app db collection create users',
+  '$ aio app db collection create inventory --validator \'{"type": "object", "required": ["id", "quantity"]}\' --json',
+  '$ aio app db col create products --json',
+  '$ aio app db col create products --validator \'{"type": "object", "properties": {"name": {"type": "string"}, "price": {"type": "number", "minimum": 0}}, "required": ["name", "price"]}\''
+]
+
+CreateCollection.args = {
+  collection: Args.string({
+    name: 'collection',
+    description: 'The name of the collection to create',
+    required: true,
+    parse: input => isNonEmptyString(input, 'Collection name')
+  })
+}
+
+CreateCollection.flags = {
+  ...DBBaseCommand.flags,
+  validator: Flags.string({
+    char: 'v',
+    description: 'JSON schema validator for document validation (JSON string)',
+    parse: input => asObject(input, 'Validator')
+  })
+}
+
+CreateCollection.aliases = ['app:db:col:create']

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

@@ -0,0 +1,90 @@
+/*
+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 DropCollection extends DBBaseCommand {
+  async run () {
+    const { collection } = this.args
+
+    try {
+      this.log(chalk.blue(`Dropping collection '${collection}'...`))
+
+      const client = await this.db.connect()
+
+      // Get the collection object
+      const coll = client.collection(collection)
+
+      // Drop collection
+      const result = await coll.drop()
+
+      this.debugLogger?.info?.('Collection dropped successfully:', result)
+
+      const response = {
+        collection,
+        status: 'dropped',
+        namespace: this.rtNamespace,
+        timestamp: new Date().toISOString(),
+        result
+      }
+
+      this.log(chalk.green(`Collection '${collection}' dropped successfully`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+
+      if (result && typeof result === 'object' && Object.keys(result).length > 0) {
+        this.log(chalk.dim(`   Details:\n${prettyJson(result)}`))
+      }
+
+      this.log(chalk.dim(`   Dropped: ${new Date().toLocaleString()}`))
+
+      return response
+    } catch (error) {
+      this.debugLogger?.error?.('Error dropping collection:', error)
+
+      const errorMessage = `Failed to drop collection '${collection}': ${error.message}`
+
+      this.log(chalk.red('Failed to drop collection'))
+      this.log(chalk.dim(`   Collection: ${collection}`))
+      this.log(chalk.dim(`   Namespace: ${this.rtNamespace}`))
+      this.log(chalk.dim(`   Error: ${error.message}`))
+
+      this.error(errorMessage)
+    }
+  }
+}
+
+DropCollection.description = 'Drop a collection from the database'
+
+DropCollection.examples = [
+  '$ aio app db collection drop users',
+  '$ aio app db collection drop products --json',
+  '$ aio app db col drop inventory'
+]
+
+DropCollection.args = {
+  collection: Args.string({
+    name: 'collection',
+    description: 'The name of the collection to drop',
+    required: true,
+    parse: input => isNonEmptyString(input, 'Collection name')
+  })
+}
+
+DropCollection.flags = {
+  ...DBBaseCommand.flags
+}
+
+DropCollection.aliases = ['app:db:col:drop']