@adobe/aio-cli-plugin-app-storage 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed 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 CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,55 @@
+# aio-cli-plugin-app-storage
+
+The CLI Plugin to manage your App Builder State storage.
+
+If you need to access State programmatically, check the
+[@adobe/aio-lib-state](https://github.com/adobe/aio-lib-state) library.
+
+---
+<!-- toc -->
+* [aio-cli-plugin-app-storage](#aio-cli-plugin-app-storage)
+* [Usage](#usage)
+* [Commands](#commands)
+<!-- tocstop -->
+
+# Usage
+
+```sh-session
+$ aio plugins:install @adobe/aio-cli-plugin-app-storage
+$ # OR
+$ aio discover -i
+$ aio app state --help
+```
+
+# Commands
+<!-- commands -->
+* [`aio help [COMMAND]`](#aio-help-command)
+
+## `aio help [COMMAND]`
+
+Display help for aio.
+
+```
+USAGE
+  $ aio help [COMMAND...] [-n]
+
+ARGUMENTS
+  COMMAND...  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for aio.
+```
+
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.8/src/commands/help.ts)_
+<!-- commandsstop -->
+
+## Contributing
+
+Contributions are welcomed! Read the [Contributing Guide](CONTRIBUTING.md) for more information.
+
+## Licensing
+
+This project is licensed under the Apache V2 License. See [LICENSE](LICENSE) for more information.

package/bin/run.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/* eslint-disable node/shebang */
+
+/*
+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 {execute} from '@oclif/core'
+await execute({dir: import.meta.url})

package/oclif.manifest.json

@@ -0,0 +1,316 @@
+{
+  "commands": {
+    "app:state:delete": {
+      "aliases": [
+        "app:state:delete"
+      ],
+      "args": {
+        "keys": {
+          "description": "keys to delete. Above 5 keys, you will be prompted for confirmation",
+          "name": "keys",
+          "required": false
+        }
+      },
+      "description": "Delete key-values",
+      "examples": [
+        "$ aio app state delete key",
+        "$ aio app state delete key1 key2 key3",
+        "$ aio app state delete --match 'gl*b'",
+        "$ aio app state delete --match 'gl*b' --json",
+        "$ aio app state delete --match 'be-carreful*' --force"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "region": {
+          "description": "State region. Defaults to 'AIO_STATE_REGION' env or 'amer' if neither is set.",
+          "name": "region",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "amer",
+            "emea"
+          ],
+          "type": "option"
+        },
+        "match": {
+          "description": "[use with caution!] deletes ALL key-values matching the provided glob-like pattern",
+          "name": "match",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "force": {
+          "description": "[use with caution!] force delete, no safety prompt",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [
+        "app:state:del",
+        "app:state:remove",
+        "app:state:rm"
+      ],
+      "id": "app:state:delete",
+      "pluginAlias": "@adobe/aio-cli-plugin-app-storage",
+      "pluginName": "@adobe/aio-cli-plugin-app-storage",
+      "pluginType": "core",
+      "strict": false,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "app",
+        "state",
+        "delete.js"
+      ]
+    },
+    "app:state:get": {
+      "aliases": [
+        "app:state:get"
+      ],
+      "args": {
+        "key": {
+          "description": "State key",
+          "name": "key",
+          "required": true
+        }
+      },
+      "description": "Get a key-value",
+      "examples": [
+        "$ aio app state get key",
+        "$ aio app state get key --json",
+        "$ aio app state get key | wc -c"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "region": {
+          "description": "State region. Defaults to 'AIO_STATE_REGION' env or 'amer' if neither is set.",
+          "name": "region",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "amer",
+            "emea"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "app:state:get",
+      "pluginAlias": "@adobe/aio-cli-plugin-app-storage",
+      "pluginName": "@adobe/aio-cli-plugin-app-storage",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "app",
+        "state",
+        "get.js"
+      ]
+    },
+    "app:state:list": {
+      "aliases": [
+        "app:state:list"
+      ],
+      "args": {},
+      "description": "List key-values",
+      "examples": [
+        "$ aio app state list",
+        "$ aio app state list --match 'gl*b'",
+        "$ aio app state list --json",
+        "$ aio app state list | less",
+        "$ aio app state list | wc -l"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "region": {
+          "description": "State region. Defaults to 'AIO_STATE_REGION' env or 'amer' if neither is set.",
+          "name": "region",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "amer",
+            "emea"
+          ],
+          "type": "option"
+        },
+        "match": {
+          "char": "m",
+          "description": "Glob-like pattern to filter keys",
+          "name": "match",
+          "required": false,
+          "default": "*",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [
+        "app:state:ls"
+      ],
+      "id": "app:state:list",
+      "pluginAlias": "@adobe/aio-cli-plugin-app-storage",
+      "pluginName": "@adobe/aio-cli-plugin-app-storage",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "app",
+        "state",
+        "list.js"
+      ]
+    },
+    "app:state:put": {
+      "aliases": [
+        "app:state:put"
+      ],
+      "args": {
+        "key": {
+          "description": "State key",
+          "name": "key",
+          "required": true
+        },
+        "value": {
+          "description": "State value",
+          "name": "value",
+          "required": true
+        }
+      },
+      "description": "Put a key-value",
+      "examples": [
+        "$ aio app state put key value",
+        "$ aio app state put key value --ttl 3600",
+        "$ aio app state put key value --json",
+        "$ cat value/from/file | xargs -0 ./bin/run.js app state put key"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "region": {
+          "description": "State region. Defaults to 'AIO_STATE_REGION' env or 'amer' if neither is set.",
+          "name": "region",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "amer",
+            "emea"
+          ],
+          "type": "option"
+        },
+        "ttl": {
+          "char": "t",
+          "description": "Time to live in seconds. Default is 86400 (24 hours), max is 31536000 (1 year).",
+          "name": "ttl",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "app:state:put",
+      "pluginAlias": "@adobe/aio-cli-plugin-app-storage",
+      "pluginName": "@adobe/aio-cli-plugin-app-storage",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "app",
+        "state",
+        "put.js"
+      ]
+    },
+    "app:state:stats": {
+      "aliases": [
+        "app:state:stats"
+      ],
+      "args": {},
+      "description": "Display stats",
+      "examples": [
+        "$ aio app state stats",
+        "$ aio app state stats --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "region": {
+          "description": "State region. Defaults to 'AIO_STATE_REGION' env or 'amer' if neither is set.",
+          "name": "region",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "amer",
+            "emea"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "app:state:stats",
+      "pluginAlias": "@adobe/aio-cli-plugin-app-storage",
+      "pluginName": "@adobe/aio-cli-plugin-app-storage",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "app",
+        "state",
+        "stats.js"
+      ]
+    }
+  },
+  "version": "1.0.0"
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@adobe/aio-cli-plugin-app-storage",
+  "version": "1.0.0",
+  "dependencies": {
+    "@adobe/aio-lib-core-config": "^5",
+    "@adobe/aio-lib-core-logging": "^3",
+    "@adobe/aio-lib-state": "^5",
+    "@inquirer/prompts": "^5",
+    "@oclif/core": "^4",
+    "@oclif/plugin-help": "^6",
+    "chalk": "^5"
+  },
+  "devDependencies": {
+    "@adobe/eslint-config-aio-lib-config": "^4",
+    "@jest/globals": "^29",
+    "eslint": "^8",
+    "execa": "^8",
+    "jest": "^29",
+    "oclif": "^4",
+    "stdout-stderr": "^0.1.9"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/run.js",
+    "oclif.manifest.json",
+    "src"
+  ],
+  "keywords": [
+    "oclif-plugin"
+  ],
+  "license": "Apache-2.0",
+  "oclif": {
+    "commands": "./src/commands",
+    "topics": {
+      "app:state": {
+        "description": "Manage your App Builder State storage"
+      }
+    },
+    "bin": "aio",
+    "topicSeparator": " ",
+    "repositoryPrefix": "<%- repo %>/blob/<%- version %>/<%- commandPath %>",
+    "plugins": [
+      "@oclif/plugin-help"
+    ]
+  },
+  "main": "src/commands/BaseCommand.js",
+  "scripts": {
+    "lint": "eslint src test e2e",
+    "unit-test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --setupFilesAfterEnv=./test/jest.setup.js --testMatch='**/*.test.js' --ci",
+    "test": "npm run unit-test && npm run lint",
+    "prepack": "oclif manifest && oclif readme --no-aliases",
+    "postpack": "rm -f oclif.manifest.json",
+    "version": "oclif readme && git add README.md",
+    "e2e": "node --experimental-vm-modules node_modules/jest/bin/jest.js --collectCoverage=false --testRegex 'e2e/e2e.js'"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "testEnvironment": "node"
+  }
+}

package/src/BaseCommand.js

@@ -0,0 +1,96 @@
+/*
+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 { Command, Flags } from '@oclif/core'
+import config from '@adobe/aio-lib-core-config'
+import AioLogger from '@adobe/aio-lib-core-logging'
+
+import { CONFIG_STATE_REGION } from './constants.js'
+import chalk from 'chalk'
+
+export class BaseCommand extends Command {
+  async init () {
+    await super.init()
+
+    // setup debug logger
+    const command = this.constructor.name.toLowerCase() // hacky but convenient
+    this.debugLogger = AioLogger(
+      `aio:app:state:${command}`,
+      { provider: 'debug' }
+    )
+    // override warn to stderr
+    this.warn = (msg) => process.stderr.write(chalk.yellow(`> Warning: ${msg.split('\n').join('\n> ')}\n`))
+
+    // parse flags and args
+    const { flags, args } = await this.parse(this.prototype)
+    this.flags = flags
+    this.args = args
+    this.debugLogger.debug(`${command} args=${JSON.stringify(this.args)} flags=${JSON.stringify(this.flags)}`)
+
+    // 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
+  }
+
+  async catch (error) {
+    this.debugLogger.error(error) // debug log with stack trace
+
+    if (error.message.includes('User force closed the prompt')) {
+      // CTRL +C on a prompt, do not log an error message
+      this.exit(2)
+    }
+
+    if (this.flags?.json) {
+      process.stderr.write(JSON.stringify(this.toErrorJson(error.message)) + '\n')
+      this.exit(2)
+    }
+    this.error(error.message)
+  }
+}
+
+// Set to true if you want to add the --json flag to your command.
+// oclif will automatically suppress logs (if you use this.log, this.warn, or this.error) and
+// 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.args = {}

package/src/commands/app/state/delete.js

@@ -0,0 +1,122 @@
+/*
+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 chalk from 'chalk'
+import { BaseCommand } from '../../../BaseCommand.js'
+import { Args, Flags } from '@oclif/core'
+
+const MAX_ARGV_NO_CONFIRM = 5
+
+export class Delete extends BaseCommand {
+  async run () {
+    const { match, force } = this.flags
+    const { argv: keysToDelete } = await this.parse(Delete)
+
+    // eslint-disable-next-line node/no-unsupported-features/es-syntax
+    const { input } = await import('@inquirer/prompts')
+
+    if (match && keysToDelete.length) {
+      return this.error('cannot use --match with args')
+    }
+
+    if (!(match || keysToDelete.length)) {
+      return this.error('please provide either keys args or --match')
+    }
+
+    const containerExists = await this.state.any()
+    if (!containerExists) {
+      this.error(`there are no keys stored in '${this.rtNamespace}'!`)
+    }
+
+    if (!force) {
+      // safeguards
+      let warning = null
+
+      if (keysToDelete.length > MAX_ARGV_NO_CONFIRM) {
+        warning = `❌ CAUTION, you specified ${keysToDelete.length} key-values to delete`
+      } else if (match) {
+        warning = ([...match].every(c => c === '*'))
+          ? '❌ CAUTION, this will delete ALL key-values!'
+          : `❌ CAUTION, this will delete key-values matching the pattern '${match}'`
+      }
+
+      if (warning) {
+        process.stderr.write(chalk.red(warning) + '\n') // console.error doesn't behave nicely with jest
+
+        const res = await input(
+          { message: `confirm deletion by typing: '${this.rtNamespace}'` },
+          // write prompt to stderr for clean --json output
+          { output: process.stderr }
+        )
+
+        if (res !== this.rtNamespace) {
+          return this.error('confirmation did not match, aborted')
+        }
+      }
+    }
+
+    let deletedKeys
+    if (keysToDelete.length) {
+      const ret = await Promise.all(keysToDelete.map(async key => {
+        const res = await this.state.delete(key)
+        return res ? 1 : 0
+      }))
+      deletedKeys = ret.reduce((sum, val) => sum + val, 0)
+    } else {
+      // ! here we go, deleting all the user's keys
+      const ret = await this.state.deleteAll({ match })
+      deletedKeys = ret.keys
+    }
+
+    this.log(`keys deleted: ${deletedKeys}`)
+    return { keys: deletedKeys } // --json
+  }
+}
+
+Delete.description = 'Delete key-values'
+Delete.examples = [
+  '$ aio app state delete key',
+  '$ aio app state delete key1 key2 key3',
+  '$ aio app state delete --match \'gl*b\'',
+  '$ aio app state delete --match \'gl*b\' --json',
+  '$ aio app state delete --match \'be-carreful*\' --force'
+]
+
+Delete.strict = false // allow for multiple args
+Delete.args = {
+  keys: Args.string({
+    name: 'keys',
+    description: `keys to delete. Above ${MAX_ARGV_NO_CONFIRM} keys, you will be prompted for confirmation`,
+    required: false
+  })
+}
+
+Delete.flags = {
+  ...BaseCommand.flags,
+  match: Flags.string({
+    description: '[use with caution!] deletes ALL key-values matching the provided glob-like pattern',
+    required: false
+  }),
+  force: Flags.boolean({
+    description: '[use with caution!] force delete, no safety prompt',
+    default: false
+  })
+}
+
+Delete.aliases = [
+  'app:state:delete'
+]
+
+Delete.hiddenAliases = [
+  'app:state:del',
+  'app:state:remove',
+  'app:state:rm'
+]

package/src/commands/app/state/get.js

@@ -0,0 +1,55 @@
+/*
+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 chalk from 'chalk'
+import { BaseCommand } from '../../../BaseCommand.js'
+import { Args } from '@oclif/core'
+
+export class Get extends BaseCommand {
+  async run () {
+    const ret = await this.state.get(this.args.key)
+
+    if (!ret) {
+      // and not value = key does not exist
+      this.error('key does not exist')
+    }
+
+    const { value, expiration } = ret
+
+    if (!this.flags.json) {
+      // we write ONLY the value to stdout for pipe-ability (no new line)
+      process.stdout.write(value)
+      // the rest goes to stderr
+      process.stderr.write(chalk.dim(`\n> expiration: ${(new Date(expiration)).toLocaleString()} (local time)\n`))
+    }
+
+    return { value, expiration } // --json { value, expiration UTC }
+  }
+}
+
+Get.description = 'Get a key-value'
+Get.examples = [
+  '$ aio app state get key',
+  '$ aio app state get key --json',
+  '$ aio app state get key | wc -c'
+]
+
+Get.args = {
+  key: Args.string({
+    name: 'key',
+    description: 'State key',
+    required: true
+  })
+}
+
+Get.aliases = [
+  'app:state:get'
+]

package/src/commands/app/state/list.js

@@ -0,0 +1,74 @@
+/*
+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 { Flags } from '@oclif/core'
+import chalk from 'chalk'
+
+const MAX_KEYS = 5000
+const COUNT_HINT = 500 // per iteration
+
+export class List extends BaseCommand {
+  async run () {
+    const allKeys = []
+
+    const { match } = this.flags
+
+    let truncatedKeys = null
+    for await (const { keys } of this.state.list({ match, countHint: COUNT_HINT })) {
+      if (keys.length + allKeys.length > MAX_KEYS) {
+        truncatedKeys = keys.slice(0, MAX_KEYS - allKeys.length)
+        break
+      }
+      allKeys.push(...keys)
+      this.logKeys(keys)
+    }
+    if (truncatedKeys) {
+      allKeys.push(...truncatedKeys)
+      this.logKeys(truncatedKeys)
+      this.warn(chalk.yellow(`Too many keys found, only the first ${MAX_KEYS} keys are displayed\nUse --match to filter keys`))
+    }
+    return allKeys // --json
+  }
+
+  logKeys (keys) {
+    // do not log unnecessary new lines
+    keys.length && this.log(keys.join('\n'))
+  }
+}
+
+List.description = 'List key-values'
+List.examples = [
+  '$ aio app state list',
+  '$ aio app state list --match \'gl*b\'',
+  '$ aio app state list --json',
+  '$ aio app state list | less',
+  '$ aio app state list | wc -l'
+]
+
+List.flags = {
+  ...BaseCommand.flags,
+  match: Flags.string({
+    name: 'match',
+    char: 'm',
+    description: 'Glob-like pattern to filter keys',
+    required: false,
+    default: '*'
+  })
+}
+
+List.aliases = [
+  'app:state:list'
+]
+// do not show in help
+List.hiddenAliases = [
+  'app:state:ls'
+]

package/src/commands/app/state/put.js

@@ -0,0 +1,68 @@
+/*
+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 { Args, Flags } from '@oclif/core'
+import { DEFAULT_TTL_SECONDS } from '../../../constants.js'
+import chalk from 'chalk'
+
+export class Put extends BaseCommand {
+  async run () {
+    const { key, value } = this.args
+    const { json, ttl } = this.flags
+    await this.state.put(key, value, { ttl })
+
+    const bytesValue = Buffer.from(value).length
+    const expirationDate = new Date(Date.now() + (ttl || DEFAULT_TTL_SECONDS) * 1000)
+    if (!json) {
+      process.stdout.write(key)
+      // stderr, be consistent with GET
+      process.stderr.write(chalk.dim(`\n> expiration:   ${new Date(expirationDate).toLocaleString()} (local time)\n`))
+      process.stderr.write(chalk.dim(`> bytes value:  ${bytesValue}\n`))
+    }
+
+    return { key, bytesValue, expiration: expirationDate.toISOString() } // --json
+  }
+}
+
+Put.description = 'Put a key-value'
+Put.examples = [
+  '$ aio app state put key value',
+  '$ aio app state put key value --ttl 3600',
+  '$ aio app state put key value --json',
+  '$ cat value/from/file | xargs -0 ./bin/run.js app state put key'
+]
+
+Put.args = {
+  key: Args.string({
+    name: 'key',
+    description: 'State key',
+    required: true
+  }),
+  value: Args.string({
+    name: 'value',
+    description: 'State value',
+    required: true
+  })
+}
+
+Put.flags = {
+  ...BaseCommand.flags,
+  ttl: Flags.integer({
+    char: 't',
+    description: 'Time to live in seconds. Default is 86400 (24 hours), max is 31536000 (1 year).',
+    required: false
+  })
+}
+
+Put.aliases = [
+  'app:state:put'
+]

package/src/commands/app/state/stats.js

@@ -0,0 +1,36 @@
+/*
+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'
+
+export class Stats extends BaseCommand {
+  async run () {
+    const ret = await this.state.stats()
+    this.log(
+`stored in '${this.rtNamespace}'
+  keys:          ${ret.keys}
+  bytes keys:    ${ret.bytesKeys}
+  bytes values:  ${ret.bytesValues}`
+    )
+
+    return ret // --json
+  }
+}
+
+Stats.description = 'Display stats'
+Stats.examples = [
+  '$ aio app state stats',
+  '$ aio app state stats --json'
+]
+
+Stats.aliases = [
+  'app:state:stats'
+]

package/src/constants.js

@@ -0,0 +1,16 @@
+/*
+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.
+*/
+
+// state.region is a new configuration (env=AIO_STATE_REGION)
+export const CONFIG_STATE_REGION = 'state.region'
+
+export const DEFAULT_TTL_SECONDS = 60 * 60 * 24 // 24 hours