fix(cli-lib-alpha): deprecate package (#500)

Deprecated in favor of @aws-cdk/toolkit-lib, a newer approach providing
similar functionality to this package. Please migrate.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: mrgrain

.projenrc.ts

@@ -1293,7 +1293,7 @@ const CLI_LIB_EXCLUDE_PATTERNS = [
   'lib/init-templates/*/typescript/*/*.template.ts',
 ];
 
-const cliLib = configureProject(
+const cliLibAlpha = configureProject(
   new yarn.TypeScriptWorkspace({
     ...genericCdkProps(),
     parent: repo,
@@ -1329,20 +1329,20 @@ const cliLib = configureProject(
 );
 
 // Do include all .ts files inside init-templates
-cliLib.npmignore?.addPatterns(
+cliLibAlpha.npmignore?.addPatterns(
   '!lib/init-templates/**/*.ts',
   '!lib/api/bootstrap/bootstrap-template.yaml',
 );
 
-cliLib.gitignore.addPatterns(
+cliLibAlpha.gitignore.addPatterns(
   ...ADDITIONAL_CLI_IGNORE_PATTERNS,
   'lib/**/*.yaml',
   'lib/**/*.yml',
   'lib/init-templates/**',
   'cdk.out',
 );
 
-new JsiiBuild(cliLib, {
+new JsiiBuild(cliLibAlpha, {
   jsiiVersion: TYPESCRIPT_VERSION,
   publishToNuget: {
     dotNetNamespace: 'Amazon.CDK.Cli.Lib.Alpha',
@@ -1362,29 +1362,33 @@ new JsiiBuild(cliLib, {
   pypiClassifiers: [
     'Framework :: AWS CDK',
     'Framework :: AWS CDK :: 2',
+    'Development Status :: 7 - Inactive',
   ],
   publishToGo: {
     moduleName: 'github.com/aws/aws-cdk-go',
     packageName: 'awscdkclilibalpha',
   },
   rosettaStrict: true,
-  stability: Stability.EXPERIMENTAL,
+  stability: Stability.DEPRECATED,
   composite: true,
   excludeTypescript: CLI_LIB_EXCLUDE_PATTERNS,
 });
 
+// the package is deprecated
+cliLibAlpha.package.addField('deprecated', 'Deprecated in favor of @aws-cdk/toolkit-lib, a newer approach providing similar functionality to this package. Please migrate.');
+
 // clilib needs to bundle some resources, same as the CLI
-cliLib.postCompileTask.exec('node-bundle validate --external=fsevents:optional --entrypoint=lib/index.js --fix --dont-attribute "^@aws-cdk/|^cdk-assets$|^cdk-cli-wrapper$|^aws-cdk$"');
-cliLib.postCompileTask.exec('mkdir -p ./lib/api/bootstrap/ && cp ../../aws-cdk/lib/api/bootstrap/bootstrap-template.yaml ./lib/api/bootstrap/');
+cliLibAlpha.postCompileTask.exec('node-bundle validate --external=fsevents:optional --entrypoint=lib/index.js --fix --dont-attribute "^@aws-cdk/|^cdk-assets$|^cdk-cli-wrapper$|^aws-cdk$"');
+cliLibAlpha.postCompileTask.exec('mkdir -p ./lib/api/bootstrap/ && cp ../../aws-cdk/lib/api/bootstrap/bootstrap-template.yaml ./lib/api/bootstrap/');
 for (const resourceCommand of includeCliResourcesCommands) {
-  cliLib.postCompileTask.exec(resourceCommand);
+  cliLibAlpha.postCompileTask.exec(resourceCommand);
 }
-cliLib.postCompileTask.exec('cp $(node -p \'require.resolve("aws-cdk/build-info.json")\') .');
-cliLib.postCompileTask.exec('esbuild --bundle lib/index.ts --target=node18 --platform=node --external:fsevents --minify-whitespace --outfile=lib/main.js');
-cliLib.postCompileTask.exec('node ./lib/main.js >/dev/null </dev/null'); // Smoke test
+cliLibAlpha.postCompileTask.exec('cp $(node -p \'require.resolve("aws-cdk/build-info.json")\') .');
+cliLibAlpha.postCompileTask.exec('esbuild --bundle lib/index.ts --target=node18 --platform=node --external:fsevents --minify-whitespace --outfile=lib/main.js');
+cliLibAlpha.postCompileTask.exec('node ./lib/main.js >/dev/null </dev/null'); // Smoke test
 
 // Exclude takes precedence over include
-for (const tsconfig of [cliLib.tsconfigDev]) {
+for (const tsconfig of [cliLibAlpha.tsconfigDev]) {
   for (const pat of CLI_LIB_EXCLUDE_PATTERNS) {
     tsconfig?.addExclude(pat);
   }
@@ -1698,7 +1702,7 @@ new CdkCliIntegTestsWorkflow(repo, {
     cloudFormationDiff.name,
     cdkAssets.name,
     cli.name,
-    cliLib.name,
+    cliLibAlpha.name,
     cdkAliasPackage.name,
     cliInteg.name,
     toolkitLib.name,

README.md

@@ -52,7 +52,7 @@ Here are the packages in this repository. See the README of each package for mor
 | [@aws-cdk/cloud-assembly-schema](./packages/@aws-cdk//cloud-assembly-schema/) | The contract between the CDK construct library and the CDK toolkit | Yes | Yes |
 | [@aws-cdk/cloudformation-diff](./packages/@aws-cdk/cloudformation-diff/) | CLI component for diffing CloudFormation templates | Yes | Yes |
 | [@aws-cdk/cli-lib-alpha](./packages/@aws-cdk/cli-lib-alpha/) | A deprecated attempt at building a programmatic interface for the CLI | Yes | No |
-| [@aws-cdk/toolkit-lib](./packages/@aws-cdk/toolkit-lib/) | A work-in-progress programmatic interface for the CLI | No | Yes |
+| [@aws-cdk/toolkit-lib](./packages/@aws-cdk/toolkit-lib/) | A programmatic interface for the CDK Toolkit | Yes | Yes |
 | [@aws-cdk/cli-plugin-contract](./packages/@aws-cdk/cli-plugin-contract/) | TypeScript types for CLI plugins. | No | Yes |
 | [@aws-cdk/cdk-cli-wrapper](./packages/@aws-cdk/cdk-cli-wrapper/) | A deprecated attempt at building a programmatic interface for the CLI | No | No |
 | [@aws-cdk/node-bundle](./packages/@aws-cdk/node-bundle/) | A tool to build CLI bundles that include license attributions. | No | Yes |

packages/@aws-cdk-testing/cli-integ/lib/package-sources/cli-npm-source.ts

@@ -18,6 +18,7 @@ export class RunnerCliNpmSource implements IRunnerSource<ITestCliSource> {
 
     await shell(['node', require.resolve('npm'), 'install', `aws-cdk@${this.range}`], {
       cwd: tempDir,
+      show: 'error',
     });
     const installedVersion = await npmQueryInstalledVersion('aws-cdk', tempDir);
 

packages/@aws-cdk-testing/cli-integ/lib/package-sources/library-globalinstall-source.ts

@@ -23,6 +23,7 @@ export class RunnerLibraryGlobalInstallSource implements IRunnerSource<ITestLibr
 
     await shell(['node', require.resolve('npm'), 'install', `${this.packageName}@${this.range}`], {
       cwd: tempDir,
+      show: 'error',
     });
 
     const symlinkPath = path.join(__dirname, '..', '..', 'node_modules', this.packageName);

packages/@aws-cdk/cli-lib-alpha/README.md

@@ -1,31 +1,27 @@
-# AWS CDK CLI Library
+# AWS CDK CLI Library (deprecated)
+
 <!--BEGIN STABILITY BANNER-->
 
 ---
 
-![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
+![@aws-cdk/cli-lib-lpha: Deprecated](https://img.shields.io/badge/@aws--cdk/cli--lib--alpha-deprectated-red.svg?style=for-the-badge)
 
-> The APIs of higher level constructs in this module are experimental and under active development.
-> They are subject to non-backward compatible changes or removal in any future version. These are
-> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
-> announced in the release notes. This means that while you may use them, you may need to update
-> your source code when upgrading to a newer version of this package.
+> This package has been deprecated in favor of [@aws-cdk/toolkit-lib](https://github.com/aws/aws-cdk-cli/issues/155),
+> a newer approach providing similar functionality to what this package offered.
+> Please migrate as soon as possible.
+> For any migration problems, please open [an issue](https://github.com/aws/aws-cdk-cli/issues/new/choose).
+> We are committed to supporting the same feature set that this package offered.
 
 ---
 
 <!--END STABILITY BANNER-->
 
-## ⚠️ Experimental module
+## ⚠️ Deprecated module
 
-This package is highly experimental. Expect frequent API changes and incomplete features.
-Known issues include:
+This package is has been deprecated.
+Already published versions can be used, but no support is provided whatsoever and we will soon stop publishing new versions.
 
-- **JavaScript/TypeScript only**\
-  The jsii packages are currently not in a working state.
-- **No useful return values**\
-  All output is currently printed to stdout/stderr
-- **Missing or Broken options**\
-  Some CLI options might not be available in this package or broken
+Instead, please use [@aws-cdk/toolkit-lib](https://github.com/aws/aws-cdk-cli/issues/155).
 
 ## Overview
 
@@ -38,6 +34,17 @@ Currently the package includes implementations for:
 - `cdk destroy`
 - `cdk list`
 
+## Known issues
+
+- **JavaScript/TypeScript only**\
+  The jsii packages are currently not in a working state.
+- **No useful return values**\
+  All output is currently printed to stdout/stderr
+- **Missing or Broken options**\
+  Some CLI options might not be available in this package or broken
+
+Due to the deprecation of the package, this issues will not be resolved.
+
 ## Setup
 
 ### AWS CDK app directory