feat!: add upsert-actions app-scripts command [EXT-5979] (#2332)

* feat: add create-actions app-scripts command

* refactor: move resolveManifestFile() to shared utils

* docs

* refactor: pre validation for function and action IDs

* refactor: create-action -> upsert-action

* fix: create-actions -> upsert-actions leftovers

* fix: error handling + tests

* chore: use conventional-bump-prerelease for canary releases

* feat!: remove hosted app action functionality from app-scripts

BREAKING CHANGE: removes the ability to create hosted app actions from app-scripts

* feat!: [BREAKING CHANGE] bump node and npm engines

Author: t-col

package.json

@@ -14,8 +14,8 @@
     "lint": "lerna run lint",
     "build": "lerna run build",
     "version": "lerna version --no-private --conventional-commits --create-release github --yes --exact",
-    "publish-packages": "lerna publish from-git --yes",
-    "version:canary": "npm run version -- --conventional-prerelease",
+    "publish-packages": "lerna publish from-git --yes --conventional-commits",
+    "version:canary": "npm run version -- --conventional-prerelease --conventional-bump-prerelease --force-git-tag",
     "publish-packages:canary": "npm run publish-packages -- --canary",
     "pre-commit": "lerna run pre-commit",
     "prepare": "husky"

packages/contentful--app-scripts/README.md

@@ -310,3 +310,43 @@ Options:
 -m, --manifest-file <path> Contentful app manifest file path
 -w, --watch watch for changes
 -h, --help display help for command
+
+### Upsert App Actions
+
+Creates or updates Actions for an App using the configuration in a Contentful App Manifest file. Created resources will be synced back to your manifest file.
+
+#### Interactive mode:
+
+In the interactive mode, the CLI will ask for all required options.
+
+> **Example**
+>
+> ```shell
+> $ npx --no-install @contentful/app-scripts upsert-actions
+> ```
+
+#### Non-interactive mode:
+
+When passing the `--ci` argument adding all variables as arguments is required.
+
+> **Example**
+>
+> ```shell
+> $ npx --no-install @contentful/app-scripts upsert-actions --ci \
+>     --manifest-file path/to/contentful-app-manifest.json \
+>     --organization-id some-org-id \
+>     --definition-id some-app-def-id \
+>     --token $MY_CONTENTFUL_PAT
+> ```
+
+**Options:**
+
+| Argument            | Description                                                                                                                                | Default value                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
+| `--manifest-file`   | The path to the Contentful app manifest file                                                                                               | `contentful-app-manifest.json` |
+| `--organization-id` | The ID of the organization which the app is defined in                                                                                     |                                |
+| `--definition-id`   | The ID of the app to which to add the actions                                                                                              |                                |
+| `--token`           | A personal [access token](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/personal-access-tokens) |                                |
+| `--host`            | (optional) Contentful CMA-endpoint to use                                                                                                  | `api.contentful.com`           |
+
+**Note:** You can also pass all arguments in interactive mode to skip being asked for it.

packages/contentful--app-scripts/package.json

@@ -10,8 +10,8 @@
     "directory": "packages/contentful--app-scripts"
   },
   "engines": {
-    "node": ">=14",
-    "npm": ">=6"
+    "node": ">=18",
+    "npm": ">=9"
   },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

packages/contentful--app-scripts/src/bin.ts

@@ -12,6 +12,7 @@ import {
   install,
   buildFunctions,
   generateFunction,
+  upsertActions,
 } from './index';
 import { feedback } from './feedback';
 
@@ -23,7 +24,8 @@ type Command =
   | typeof open
   | typeof install
   | typeof buildFunctions
-  | typeof generateFunction;
+  | typeof generateFunction
+  | typeof upsertActions;
 
 async function runCommand(command: Command, options?: any) {
   const { ci } = program.opts();
@@ -46,7 +48,7 @@ async function runCommand(command: Command, options?: any) {
     .description('Upload your build folder and create an AppBundle')
     .option('--bundle-dir [directory]', 'The directory of your build folder')
     .option('--organization-id [orgId]', 'The id of your organization')
-    .option('--definition-id [defId]', 'The id of your apps definition')
+    .option('--definition-id [defId]', 'The id of your app\'s definition')
     .option('--token [accessToken]', 'Your content management access token')
     .option('--comment [comment]', 'Optional comment for the created bundle')
     .option('--skip-activation', 'A Boolean flag to skip automatic activation')
@@ -60,7 +62,7 @@ async function runCommand(command: Command, options?: any) {
     .description('Mark an AppBundle as "active" for a given AppDefinition')
     .option('--bundle-id [bundleId]', 'The id of your bundle')
     .option('--organization-id [orgId]', 'The id of your organization')
-    .option('--definition-id  [defId]', 'The id of your apps definition')
+    .option('--definition-id  [defId]', 'The id of your app\'s definition')
     .option('--token [accessToken]', 'Your content management access token')
     .option('--host [host]', 'Contentful subdomain to use, e.g. "api.contentful.com"')
     .action(async (options) => {
@@ -70,7 +72,7 @@ async function runCommand(command: Command, options?: any) {
   program
     .command('open-settings')
     .description('Opens the app editor for a given AppDefinition')
-    .option('--definition-id  [defId]', 'The id of your apps definition')
+    .option('--definition-id  [defId]', 'The id of your app\'s definition')
     .option('--host [host]', 'Contentful subdomain to use, e.g. "api.contentful.com"')
     .action(async (options) => {
       await runCommand(open, options);
@@ -80,7 +82,7 @@ async function runCommand(command: Command, options?: any) {
     .command('bundle-cleanup')
     .description('Removes old, non-active bundles, only keeps the 50 most recent ones')
     .option('--organization-id [orgId]', 'The id of your organization')
-    .option('--definition-id  [defId]', 'The id of your apps definition')
+    .option('--definition-id  [defId]', 'The id of your app\'s definition')
     .option('--token [accessToken]', 'Your content management access token')
     .option('--keep [keepAmount]', 'The amount of bundles that should remain')
     .option('--host [host]', 'Contentful subdomain to use, e.g. "api.contentful.com"')
@@ -100,7 +102,7 @@ async function runCommand(command: Command, options?: any) {
     .description(
       'Opens a picker to select the space and environment for installing the app associated with a given AppDefinition'
     )
-    .option('--definition-id  [defId]', 'The id of your apps definition')
+    .option('--definition-id  [defId]', 'The id of your app\'s definition')
     .option('--host [host]', 'Contentful subdomain to use, e.g. "api.contentful.com"')
     .action(async (options) => {
       await runCommand(install, options);
@@ -127,6 +129,18 @@ async function runCommand(command: Command, options?: any) {
       await runCommand(generateFunction, options);
     });
 
+  program
+    .command('upsert-actions')
+    .description('Upsert Action(s) for an App')
+    .option('-m, --manifest-file <path>', 'Contentful app manifest file path')
+    .option('--organization-id [orgId]', 'The id of your organization')
+    .option('--definition-id  [defId]', 'The id of your app\'s definition')
+    .option('--token [accessToken]', 'Your content management access token')
+    .option('--host [host]', 'Contentful subdomain to use, e.g. "api.contentful.com"')
+    .action(async (options) => {
+      await runCommand(upsertActions, options);
+    });
+
   program.hook('preAction', (thisCommand) => {
     track({ command: thisCommand.args[0], ci: thisCommand.opts().ci });
   });

packages/contentful--app-scripts/src/build-functions/__tests__/build-functions.test.ts

@@ -1,8 +1,8 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
+import assert from 'assert';
 import path from 'path';
 import { type BuildFunctionsOptions } from '../../types';
-import { resolveEsBuildConfig, resolveManifestFile, validateFunctions } from '../build-functions';
-import assert from 'assert';
+import { resolveEsBuildConfig, validateFunctions } from '../build-functions';
 
 function assertPartialObject(actual: any, expected: any) {
   for (const key in expected) {
@@ -14,28 +14,6 @@ function assertPartialObject(actual: any, expected: any) {
   }
 }
 
-describe('resolveManifestFile', () => {
-  it('should resolve the default manifest file if none is provided', async () => {
-    const options: BuildFunctionsOptions = {};
-    const manifest = await resolveManifestFile(options, __dirname);
-    assert.strictEqual(Boolean(manifest), true);
-    assert.strictEqual('functions' in manifest, true);
-    assert.strictEqual(manifest.functions.length, 1);
-    assert.strictEqual(manifest.functions[0].name, 'default');
-  });
-
-  it('should resolve the manifest file at the provided path if present', async () => {
-    const options: BuildFunctionsOptions = {
-      manifestFile: 'fixtures/another-contentful-app-manifest.json',
-    };
-    const manifest = await resolveManifestFile(options, __dirname);
-    assert.strictEqual(Boolean(manifest), true);
-    assert.strictEqual('functions' in manifest, true);
-    assert.strictEqual(manifest.functions.length, 1);
-    assert.strictEqual(manifest.functions[0].name, 'custom');
-  });
-});
-
 describe('resolveEsBuildConfig', () => {
   it('should resolve the default esbuild config if none is provided', async () => {
     const options: BuildFunctionsOptions = {};
@@ -141,7 +119,7 @@ describe('validateFunctions', () => {
     const manifest = {
       functions: [
         {
-          id: 'an-id',
+          id: 'example',
           name: 'myFunc',
           entryFile: 'index.ts',
           description: 'My function',

packages/contentful--app-scripts/src/build-functions/build-functions.ts

@@ -5,6 +5,7 @@ import { NodeModulesPolyfillPlugin } from '@esbuild-plugins/node-modules-polyfil
 import { NodeGlobalsPolyfillPlugin } from '@esbuild-plugins/node-globals-polyfill';
 import { type BuildFunctionsOptions, type ContentfulFunction } from '../types';
 import { z } from 'zod';
+import { ID_REGEX, resolveManifestFile } from '../utils';
 
 type ContentfulFunctionToBuild = Omit<ContentfulFunction, 'entryFile'> & { entryFile: string };
 
@@ -13,12 +14,14 @@ const functionManifestSchema = z
     functions: z.array(
       z
         .object({
-          id: z.string(),
+          id: z.string().regex(ID_REGEX, 'Invalid "id" (must only contain alphanumeric characters)'),
           name: z.string(),
           description: z.string(),
           path: z.string(),
           entryFile: z.string(),
           accepts: z.array(z.string()),
+        }, {
+
         })
         .required()
     ),
@@ -58,12 +61,6 @@ export const validateFunctions = (manifest: Record<string, any>) => {
   });
 };
 
-export const resolveManifestFile = (options: BuildFunctionsOptions, cwd = process.cwd()) => {
-  return require(options.manifestFile
-    ? resolve(cwd, options.manifestFile)
-    : resolve(cwd, 'contentful-app-manifest.json'));
-};
-
 const getEntryPoints = (
   manifest: { functions: ContentfulFunctionToBuild[] },
   cwd = process.cwd()

packages/contentful--app-scripts/src/index.ts

@@ -8,3 +8,4 @@ export { feedback } from './feedback';
 export { install } from './install';
 export { buildFunctions } from './build-functions';
 export { generateFunction } from './generate-function';
+export { upsertActions } from './upsert-actions';

packages/contentful--app-scripts/src/types.ts

@@ -1,17 +1,6 @@
 import { Definition } from './definition-api';
 import { Organization } from './organization-api';
 
-export interface FunctionAppAction {
-  id: string;
-  name: string;
-  description: string;
-  category: 'Custom';
-  type: 'function';
-  path: string;
-  allowNetworks?: string[];
-  entryFile?: string;
-}
-
 export interface ContentfulFunction {
   id: string;
   name: string;
@@ -84,7 +73,6 @@ export interface UploadSettings {
   skipActivation?: boolean;
   userAgentApplication?: string;
   host?: string;
-  actions?: FunctionAppAction[];
   functions?: ContentfulFunction[];
 }
 

packages/contentful--app-scripts/src/upload/build-upload-settings.test.ts

@@ -10,12 +10,12 @@ import * as utilsModule from '../utils';
 describe('buildAppUploadSettings', () => {
   let promptStub;
   let getAppInfoStub;
-  let getEntityFromManifestStub;
+  let getFunctionsFromManifestStub;
 
   beforeEach(() => {
     promptStub = sinon.stub(inquirer, 'prompt');
     getAppInfoStub = sinon.stub(getAppInfoModule, 'getAppInfo');
-    getEntityFromManifestStub = sinon.stub(utilsModule, 'getEntityFromManifest');
+    getFunctionsFromManifestStub = sinon.stub(utilsModule, 'getFunctionsFromManifest');
   });
 
   afterEach(() => {
@@ -39,16 +39,14 @@ describe('buildAppUploadSettings', () => {
 
     getAppInfoStub.resolves({ appId: '123', appName: 'Test App' });
 
-    getEntityFromManifestStub.withArgs('actions').returns('actionsManifest');
-    getEntityFromManifestStub.withArgs('functions').returns('functionsManifest');
+    getFunctionsFromManifestStub.returns('functionsManifest');
 
     const result = await buildAppUploadSettings(options);
 
     assert.strictEqual(result.host, 'api.contentful.com', 'Protocol should be stripped from host');
     assert.strictEqual(result.bundleDirectory, './custom-build');
     assert.strictEqual(result.comment, 'Test comment');
     assert.strictEqual(result.skipActivation, false); // activateBundle is true, so skipActivation should be false
-    assert.strictEqual(result.actions, 'actionsManifest');
     assert.strictEqual(result.functions, 'functionsManifest');
   });
   }
@@ -64,8 +62,7 @@ describe('buildAppUploadSettings', () => {
 
     promptStub.resolves(prompts);
     getAppInfoStub.resolves({ appId: '123', appName: 'Test App' });
-    getEntityFromManifestStub.withArgs('actions').returns('actionsManifest');
-    getEntityFromManifestStub.withArgs('functions').returns('functionsManifest');
+    getFunctionsFromManifestStub.returns('functionsManifest');
 
     const result = await buildAppUploadSettings(options);
 
@@ -82,8 +79,7 @@ describe('buildAppUploadSettings', () => {
 
     promptStub.resolves({});
     getAppInfoStub.resolves({ appId: '123', appName: 'Test App' });
-    getEntityFromManifestStub.withArgs('actions').returns('actionsManifest');
-    getEntityFromManifestStub.withArgs('functions').returns('functionsManifest');
+    getFunctionsFromManifestStub.returns('functionsManifest');
 
     const result = await buildAppUploadSettings(options);
 
@@ -99,8 +95,7 @@ describe('buildAppUploadSettings', () => {
 
     promptStub.resolves(prompts);
     getAppInfoStub.resolves({ appId: '123', appName: 'Test App' });
-    getEntityFromManifestStub.withArgs('actions').returns('actionsManifest');
-    getEntityFromManifestStub.withArgs('functions').returns('functionsManifest');
+    getFunctionsFromManifestStub.returns('functionsManifest');
 
     const result = await buildAppUploadSettings(options);
 

packages/contentful--app-scripts/src/upload/build-upload-settings.ts

@@ -1,12 +1,11 @@
 import { prompt } from 'inquirer';
 import { getAppInfo } from '../get-app-info';
-import { getEntityFromManifest } from '../utils';
+import { getFunctionsFromManifest } from '../utils';
 import { DEFAULT_CONTENTFUL_API_HOST } from '../constants';
 import { UploadOptions, UploadSettings } from '../types';
 
 export async function buildAppUploadSettings(options: UploadOptions): Promise<UploadSettings> {
-  const actionsManifest = getEntityFromManifest('actions');
-  const functionManifest = getEntityFromManifest('functions');
+  const functionManifest = getFunctionsFromManifest();
   const prompts = [];
   const { bundleDir, comment, skipActivation, host } = options;
 
@@ -50,7 +49,6 @@ export async function buildAppUploadSettings(options: UploadOptions): Promise<Up
     skipActivation: skipActivation === undefined ? !activateBundle : skipActivation,
     comment,
     host: hostValue,
-    actions: actionsManifest,
     functions: functionManifest,
     ...appUploadSettings,
     ...appInfo,