cdk8s-opinionated-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# cdk8s-opinionated-cli
+
+## 0.1.0
+
+### Minor Changes
+
+- 0fff51b: Initial release.
+
+### Patch Changes
+
+- Updated dependencies [0fff51b]
+  - cdk8s-kbld2@0.1.0
+  - cdk8s-local@0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# cdk8s-opinionated-cli
+
+**TLDR: A function to wrap your cdk8s app with a CLI interface that allows for passing custom command line arguments.**
+
+Whenever I use cdk8s, I find myself writing a simple CLI tool that runs a cdk8s synth but allows me to pass custom command line arguments to modify the behaviour of my app, such as passing a config file or environment name. So this package provides a function to do just that, with minimal boilerplate.
+
+In addition, the CLI wrapper includes support for [`cdk8s-local`](../cdk8s-local/README.md) and [`cdk8s-kbld2`](../cdk8s-kbld2/README.md) out of the box, so you can easily run your cdk8s apps locally or run your manifests through `kbld` after synth automatically.
+
+```sh
+# Note: only bun is currently supported as I use `bun` to run shell commands (`kbld`) internally.
+bun i cdk8s-opinionated-cli
+```
+
+```ts
+import { App } from "cdk8s";
+import { cdk8sOpinionatedCli } from "cdk8s-opinionated-cli";
+import { option, optional, string } from "cmd-ts";
+import { YourConstruct } from "./your-code";
+
+await cdk8sOpinionatedCli({
+	args: {
+		someCustomArg: option({
+			type: optional(string),
+			long: "some-custom-arg",
+			short: "a",
+			description: "a custom argument you can use for whatever you want, i usually use one to select a config file.",
+		}),
+	},
+	async synth({ args: { someCustomArg } }) {
+		// In this function, construct your app as usual, and return the final app instance.
+		const app = new App();
+
+		new YourConstruct(app, {
+			someCustomArg,
+		});
+
+		return app;
+	},
+});
+```
+
+You can then synthesise your cdk8s app like so:
+
+```
+bun cli.ts synth --some-custom-arg value
+```
+
+Or deploy it locally, with:
+
+```
+bun cli.ts local --some-custom-arg value
+```
+
+## cdk8s-kbld2 Integration
+
+If a `KbldConfig` construct is detected in your app, `kbld` will be automatically run against your app's generated manifests, and the resulting manifests will be dumped to stdout.
+
+## cdk8s-local Integration
+
+You can specify `cdk8s-local` configuration under `subcommands.local`. The configuration is the same as `cdk8s-local`'s, except you can omit the `synth` function from the `local` config. Alternatively, you can specify a `synth` function that is only to be used for local development. See [`cdk8s-local`](../cdk8s-local/README.md) for documentation.

package/dist/config.d.mts

@@ -0,0 +1,86 @@
+import { Config } from "cdk8s-local";
+import { ArgTypes, Output } from "@repo/utils/cmd-ts-types";
+import { Awaitable } from "@repo/utils/awaitable";
+import { CommonContext, CommonStartupContext } from "@repo/utils/cli-contexts";
+import { PickPartial } from "@repo/utils/pick-partial";
+import { App } from "cdk8s";
+
+//#region src/config.d.ts
+type FeatureToggle<T extends object> = {
+  enabled: false;
+} | ({
+  enabled: true;
+} & T);
+interface SynthConfig {
+  /**
+   * Optional configuration for the generated `cmd-ts` subcommand.
+   */
+  command?: {
+    /**
+     * @default "synth"
+     */
+    name?: string;
+    /**
+     * @default "Synthesize the CDK8s app into K8s manifests."
+     */
+    description?: string;
+  };
+}
+interface Config$1<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes> {
+  /**
+   * `cmd-ts` argument definitions for the CLI. This will be merged with the default arguments provided by `cdk8s-opinionated-cli`,
+   * and passed to your hooks and synth function.
+   *
+   * You can use this to add your own CLI arguments to allow users to configure your CDK8s app generation.
+   *
+   * This can be overridden for local development (in case you need to pass custom configuration for running locally).
+   */
+  args?: Arguments;
+  /**
+   * A function which synthesizes your CDK8s app. Is expected to return an `App` instance.
+   */
+  synth: (ctx: CommonContext<Output<Arguments>, Data>) => Awaitable<App>;
+  /**
+   * Optional configuration for the generated `cmd-ts` command.
+   */
+  command?: {
+    /**
+     * @default "cdk8s-opinionated-cli"
+     */
+    name?: string;
+    /**
+     * @default "CLI for running CDK8s apps with opinionated defaults."
+     */
+    description?: string;
+  };
+  /**
+   * Configuration for the various subcommands of the CLI. All commands are enabled by default.
+   */
+  subcommands: {
+    /**
+     * Optional configuration for the `synth` subcommand.
+     */
+    synth?: FeatureToggle<SynthConfig>;
+    /**
+     * Optional configuration for the `local` command. `args` and `synth` are inherited from the main config,
+     * but can be extended here.
+     */
+    local?: FeatureToggle<PickPartial<Config<LocalArguments, Data, Arguments>, "synth">>;
+  };
+  /**
+   * These hooks run at various points and allow you to customize the CLI's behavior.
+   *
+   * These will be _replaced_ by any hooks provided for individual subcommands.
+   */
+  hooks?: {
+    /**
+     * A function that will run immediately on startup, but with access to the parsed CLI arguments.
+     *
+     * You can return custom data that will be passed to subsequent hooks and the synth function.
+     */
+    startup?: (ctx: CommonStartupContext<Output<Arguments>>) => Awaitable<Data | void>;
+  };
+}
+//#endregion
+export { Config$1 as Config };
+//# sourceMappingURL=config.d.mts.map

package/dist/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","names":[],"sources":["../src/config.ts"],"mappings":";;;;;;;;KAOK,aAAA;EAAoC,OAAA;AAAA;EAAsB,OAAA;AAAA,IAAkB,CAAA;AAAA,UAEhE,WAAA;EAFE;;;EAMlB,OAAA;IANiF;;AAElF;IAQE,IAAA;IAR0B;;;IAY1B,WAAA;EAAA;AAAA;AAAA,UAIe,QAAA,mBAAyB,QAAA,+BAAuC,QAAA;EAAhE;;;;;;;;EAShB,IAAA,GAAO,SAAA;EAIM;;;EAAb,KAAA,GAAQ,GAAA,EAAK,aAAA,CAAc,MAAA,CAAO,SAAA,GAAY,IAAA,MAAU,SAAA,CAAU,GAAA;EAuBzD;;;EAlBT,OAAA;IAuBmC;;;IAnBlC,IAAA;IAiCqC;;;IA7BrC,WAAA;EAAA;EA6BqE;;;EAvBtE,WAAA;IAhCyD;;;IAoCxD,KAAA,GAAQ,aAAA,CAAc,WAAA;IAvBvB;;;;IA4BC,KAAA,GAAQ,aAAA,CAAc,WAAA,CAAY,MAAA,CAAY,cAAA,EAAgB,IAAA,EAAM,SAAA;EAAA;EA5Bb;;;;;EAoCxD,KAAA;IAbC;;;;;IAmBA,OAAA,IAAW,GAAA,EAAK,oBAAA,CAAqB,MAAA,CAAO,SAAA,OAAgB,SAAA,CAAU,IAAA;EAAA;AAAA"}

package/dist/index.d.mts

@@ -0,0 +1,32 @@
+import { Config } from "./config.mjs";
+import * as cmd_ts_dist_cjs_argparser0 from "cmd-ts/dist/cjs/argparser";
+import * as cmd_ts_dist_cjs_helpdoc0 from "cmd-ts/dist/cjs/helpdoc";
+import { Descriptive } from "cmd-ts/dist/cjs/helpdoc";
+import * as cmd_ts_dist_cjs_runner0 from "cmd-ts/dist/cjs/runner";
+import { ArgTypes } from "@repo/utils/cmd-ts-types";
+
+//#region src/index.d.ts
+declare function cdk8sOpinionatedCliCommand<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes>(config: Config<Arguments, Data, LocalArguments>): Promise<Partial<cmd_ts_dist_cjs_argparser0.Register> & {
+  parse(context: cmd_ts_dist_cjs_argparser0.ParseContext): Promise<cmd_ts_dist_cjs_argparser0.ParsingResult<{
+    command: string;
+    args: any;
+  }>>;
+} & cmd_ts_dist_cjs_helpdoc0.Named & Partial<Descriptive & cmd_ts_dist_cjs_helpdoc0.Versioned> & cmd_ts_dist_cjs_helpdoc0.PrintHelp & Partial<cmd_ts_dist_cjs_helpdoc0.Versioned> & cmd_ts_dist_cjs_argparser0.Register & cmd_ts_dist_cjs_runner0.Handling<{
+  command: string;
+  args: any;
+}, {
+  command: string;
+  value: any;
+}> & {
+  run(context: cmd_ts_dist_cjs_argparser0.ParseContext): Promise<cmd_ts_dist_cjs_argparser0.ParsingResult<{
+    command: string;
+    value: any;
+  }>>;
+}>;
+declare function cdk8sOpinionatedCli<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes>(config: Config<Arguments, Data, LocalArguments>): Promise<{
+  command: string;
+  value: any;
+}>;
+//#endregion
+export { type Config, cdk8sOpinionatedCli, cdk8sOpinionatedCliCommand };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;iBAcsB,0BAAA,mBAA6C,QAAA,+BAAuC,QAAA,CAAA,CACzG,MAAA,EAAQ,MAAA,CAAO,SAAA,EAAW,IAAA,EAAM,cAAA,IAAe,OAAA,CAAA,OAAA,CAAjC,0BAAA,CAAiC,QAAA;iBAAA,0BAAA,CAAA,YAAA;;;;;;;;;;;;;;;;iBA+E1B,mBAAA,mBAAsC,QAAA,+BAAuC,QAAA,CAAA,CAClG,MAAA,EAAQ,MAAA,CAAO,SAAA,EAAW,IAAA,EAAM,cAAA,IAAe,OAAA"}

package/dist/index.mjs

@@ -0,0 +1,86 @@
+import { logger } from "@repo/utils/logger";
+import { $ } from "bun";
+import { KbldConfig } from "cdk8s-kbld2";
+import { binary, boolean, command, flag, run, subcommands } from "cmd-ts";
+import { ConstructOrder } from "constructs";
+import { rm } from "fs/promises";
+import path from "path";
+
+//#region src/index.ts
+async function cdk8sOpinionatedCliCommand(config) {
+	const cmds = {};
+	if (config.subcommands.local?.enabled !== false) {
+		const { cdk8sLocalCommand } = await import("cdk8s-local");
+		cmds["local"] = cdk8sLocalCommand({
+			synth: config.synth,
+			...config.subcommands.local,
+			args: {
+				...config.args,
+				...config.subcommands.local?.args
+			},
+			hooks: {
+				...config.hooks,
+				...config.subcommands.local?.hooks
+			}
+		});
+	}
+	if (config.subcommands.synth?.enabled !== false) cmds["synth"] = command({
+		name: config.subcommands.synth?.command?.name ?? "synth",
+		description: config.subcommands.synth?.command?.description ?? "Synthesize the CDK8s app into K8s manifests.",
+		args: {
+			noBuild: flag({
+				type: boolean,
+				long: "no-build",
+				description: "only synthesise the manifests, do not build resulting manifests with kbld"
+			}),
+			...config.args
+		},
+		async handler(args) {
+			const startupCtx = {
+				args,
+				command: "synth"
+			};
+			const ctx = {
+				...startupCtx,
+				data: await config.hooks?.startup?.(startupCtx) ?? {}
+			};
+			logger.info("Running synth (generating manifests)...");
+			const app = await config.synth(ctx);
+			await rm(app.outdir, {
+				recursive: true,
+				force: true
+			});
+			app.synth();
+			if (args.noBuild) {
+				logger.info("Synth complete, skipping build, find manifests in " + path.relative(process.cwd(), app.outdir));
+				return;
+			}
+			if (app.node.findAll(ConstructOrder.POSTORDER).find((c) => c instanceof KbldConfig)) {
+				logger.info("Detected kbld config construct, running kbld...");
+				try {
+					const buffer = await $`kbld -f ${app.outdir}`.arrayBuffer();
+					process.stdout.write(Buffer.from(buffer));
+				} catch (e) {
+					if (e instanceof $.ShellError) {
+						logger.error(e.stderr.toString("utf-8"));
+						logger.fatal("Failed to build images from manifests.");
+						return 1;
+					}
+					throw e;
+				}
+			}
+		}
+	});
+	return subcommands({
+		name: config.command?.name ?? "cdk8s-opinionated-cli",
+		description: config.command?.description ?? "CLI for running CDK8s apps with opinionated defaults.",
+		cmds
+	});
+}
+async function cdk8sOpinionatedCli(config) {
+	return await run(binary(await cdk8sOpinionatedCliCommand(config)), process.argv);
+}
+
+//#endregion
+export { cdk8sOpinionatedCli, cdk8sOpinionatedCliCommand };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { ArgTypes } from \"@repo/utils/cmd-ts-types\";\nimport { logger } from \"@repo/utils/logger\";\nimport { $ } from \"bun\";\nimport { KbldConfig } from \"cdk8s-kbld2\";\nimport { binary, boolean, command, flag, run, type Runner, subcommands } from \"cmd-ts\";\nimport type { ArgParser } from \"cmd-ts/dist/cjs/argparser\";\nimport type { Aliased, Descriptive } from \"cmd-ts/dist/cjs/helpdoc\";\nimport { ConstructOrder } from \"constructs\";\nimport { rm } from \"fs/promises\";\nimport path from \"path\";\nimport type { Config } from \"./config\";\n\nexport type { Config } from \"./config\";\n\nexport async function cdk8sOpinionatedCliCommand<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes>(\n\tconfig: Config<Arguments, Data, LocalArguments>,\n) {\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tconst cmds: Record<string, ArgParser<any> & Runner<any, any> & Partial<Descriptive & Aliased>> = {};\n\n\tif (config.subcommands.local?.enabled !== false) {\n\t\tconst { cdk8sLocalCommand } = await import(\"cdk8s-local\");\n\t\tconst cmd = cdk8sLocalCommand<Arguments & LocalArguments, Data>({\n\t\t\tsynth: config.synth,\n\t\t\t...config.subcommands.local,\n\t\t\targs: {\n\t\t\t\t// Spreading `undefined` is safe and results in no additional arguments, which is the expected behaviour.\n\t\t\t\t...config.args!,\n\t\t\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain\n\t\t\t\t...config.subcommands.local?.args!,\n\t\t\t},\n\t\t\thooks: {\n\t\t\t\t...config.hooks,\n\t\t\t\t...config.subcommands.local?.hooks,\n\t\t\t},\n\t\t});\n\t\tcmds[\"local\"] = cmd;\n\t}\n\n\tif (config.subcommands.synth?.enabled !== false) {\n\t\tcmds[\"synth\"] = command({\n\t\t\tname: config.subcommands.synth?.command?.name ?? \"synth\",\n\t\t\tdescription: config.subcommands.synth?.command?.description ?? \"Synthesize the CDK8s app into K8s manifests.\",\n\t\t\targs: {\n\t\t\t\tnoBuild: flag({\n\t\t\t\t\ttype: boolean,\n\t\t\t\t\tlong: \"no-build\",\n\t\t\t\t\tdescription: \"only synthesise the manifests, do not build resulting manifests with kbld\",\n\t\t\t\t}),\n\t\t\t\t...config.args!,\n\t\t\t},\n\t\t\tasync handler(args) {\n\t\t\t\tconst startupCtx = { args, command: \"synth\" as const };\n\t\t\t\tconst ctx = {\n\t\t\t\t\t...startupCtx,\n\t\t\t\t\tdata: (await config.hooks?.startup?.(startupCtx)) ?? ({} as Data),\n\t\t\t\t};\n\n\t\t\t\tlogger.info(\"Running synth (generating manifests)...\");\n\n\t\t\t\tconst app = await config.synth(ctx);\n\t\t\t\tawait rm(app.outdir, { recursive: true, force: true });\n\t\t\t\tapp.synth();\n\n\t\t\t\tif (args.noBuild) {\n\t\t\t\t\tlogger.info(\"Synth complete, skipping build, find manifests in \" + path.relative(process.cwd(), app.outdir));\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tif (app.node.findAll(ConstructOrder.POSTORDER).find((c) => c instanceof KbldConfig)) {\n\t\t\t\t\tlogger.info(\"Detected kbld config construct, running kbld...\");\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst buffer = await $`kbld -f ${app.outdir}`.arrayBuffer();\n\t\t\t\t\t\tprocess.stdout.write(Buffer.from(buffer));\n\t\t\t\t\t} catch (e) {\n\t\t\t\t\t\tif (e instanceof $.ShellError) {\n\t\t\t\t\t\t\tlogger.error(e.stderr.toString(\"utf-8\"));\n\t\t\t\t\t\t\tlogger.fatal(\"Failed to build images from manifests.\");\n\t\t\t\t\t\t\treturn 1;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tthrow e;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\t}\n\n\treturn subcommands({\n\t\tname: config.command?.name ?? \"cdk8s-opinionated-cli\",\n\t\tdescription: config.command?.description ?? \"CLI for running CDK8s apps with opinionated defaults.\",\n\t\tcmds,\n\t});\n}\n\nexport async function cdk8sOpinionatedCli<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes>(\n\tconfig: Config<Arguments, Data, LocalArguments>,\n) {\n\tconst cmd = await cdk8sOpinionatedCliCommand(config);\n\treturn await run(binary(cmd), process.argv);\n}\n"],"mappings":";;;;;;;;;AAcA,eAAsB,2BACrB,QACC;CAED,MAAM,OAA2F,EAAE;AAEnG,KAAI,OAAO,YAAY,OAAO,YAAY,OAAO;EAChD,MAAM,EAAE,sBAAsB,MAAM,OAAO;AAe3C,OAAK,WAdO,kBAAoD;GAC/D,OAAO,OAAO;GACd,GAAG,OAAO,YAAY;GACtB,MAAM;IAEL,GAAG,OAAO;IAEV,GAAG,OAAO,YAAY,OAAO;IAC7B;GACD,OAAO;IACN,GAAG,OAAO;IACV,GAAG,OAAO,YAAY,OAAO;IAC7B;GACD,CAAC;;AAIH,KAAI,OAAO,YAAY,OAAO,YAAY,MACzC,MAAK,WAAW,QAAQ;EACvB,MAAM,OAAO,YAAY,OAAO,SAAS,QAAQ;EACjD,aAAa,OAAO,YAAY,OAAO,SAAS,eAAe;EAC/D,MAAM;GACL,SAAS,KAAK;IACb,MAAM;IACN,MAAM;IACN,aAAa;IACb,CAAC;GACF,GAAG,OAAO;GACV;EACD,MAAM,QAAQ,MAAM;GACnB,MAAM,aAAa;IAAE;IAAM,SAAS;IAAkB;GACtD,MAAM,MAAM;IACX,GAAG;IACH,MAAO,MAAM,OAAO,OAAO,UAAU,WAAW,IAAM,EAAE;IACxD;AAED,UAAO,KAAK,0CAA0C;GAEtD,MAAM,MAAM,MAAM,OAAO,MAAM,IAAI;AACnC,SAAM,GAAG,IAAI,QAAQ;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC;AACtD,OAAI,OAAO;AAEX,OAAI,KAAK,SAAS;AACjB,WAAO,KAAK,uDAAuD,KAAK,SAAS,QAAQ,KAAK,EAAE,IAAI,OAAO,CAAC;AAC5G;;AAGD,OAAI,IAAI,KAAK,QAAQ,eAAe,UAAU,CAAC,MAAM,MAAM,aAAa,WAAW,EAAE;AACpF,WAAO,KAAK,kDAAkD;AAC9D,QAAI;KACH,MAAM,SAAS,MAAM,CAAC,WAAW,IAAI,SAAS,aAAa;AAC3D,aAAQ,OAAO,MAAM,OAAO,KAAK,OAAO,CAAC;aACjC,GAAG;AACX,SAAI,aAAa,EAAE,YAAY;AAC9B,aAAO,MAAM,EAAE,OAAO,SAAS,QAAQ,CAAC;AACxC,aAAO,MAAM,yCAAyC;AACtD,aAAO;;AAER,WAAM;;;;EAIT,CAAC;AAGH,QAAO,YAAY;EAClB,MAAM,OAAO,SAAS,QAAQ;EAC9B,aAAa,OAAO,SAAS,eAAe;EAC5C;EACA,CAAC;;AAGH,eAAsB,oBACrB,QACC;AAED,QAAO,MAAM,IAAI,OADL,MAAM,2BAA2B,OAAO,CACxB,EAAE,QAAQ,KAAK"}

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "cdk8s-opinionated-cli",
+	"version": "0.1.0",
+	"private": false,
+	"type": "module",
+	"scripts": {
+		"lint": "eslint . --max-warnings 0",
+		"typecheck": "tsc --noEmit",
+		"dist": "bun --bun tsdown",
+		"publish-pkg": "bun publish --tolerate-republish"
+	},
+	"dependencies": {
+		"cdk8s": "^2.70.28",
+		"cdk8s-kbld2": "0.1.0",
+		"cdk8s-local": "0.1.0",
+		"cmd-ts": "^0.14.3",
+		"constructs": "^10.4.3",
+		"@repo/utils": "0.0.0"
+	},
+	"devDependencies": {
+		"@repo/eslint-config": "0.0.0",
+		"@repo/typescript-config": "0.0.0",
+		"@types/bun": "^1.3.8",
+		"eslint": "^9.34.0",
+		"tsdown": "^0.20.2",
+		"typescript": "^5.9.3"
+	},
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"default": "./dist/index.mjs"
+		},
+		"./package.json": "./package.json"
+	}
+}

package/src/config.ts

@@ -0,0 +1,83 @@
+import type { Awaitable } from "@repo/utils/awaitable";
+import type { CommonContext, CommonStartupContext } from "@repo/utils/cli-contexts";
+import type { ArgTypes, Output } from "@repo/utils/cmd-ts-types";
+import type { PickPartial } from "@repo/utils/pick-partial";
+import type { App } from "cdk8s";
+import { Config as LocalConfig } from "cdk8s-local";
+
+type FeatureToggle<T extends object> = { enabled: false } | ({ enabled: true } & T);
+
+export interface SynthConfig {
+	/**
+	 * Optional configuration for the generated `cmd-ts` subcommand.
+	 */
+	command?: {
+		/**
+		 * @default "synth"
+		 */
+		name?: string;
+		/**
+		 * @default "Synthesize the CDK8s app into K8s manifests."
+		 */
+		description?: string;
+	};
+}
+
+export interface Config<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes> {
+	/**
+	 * `cmd-ts` argument definitions for the CLI. This will be merged with the default arguments provided by `cdk8s-opinionated-cli`,
+	 * and passed to your hooks and synth function.
+	 *
+	 * You can use this to add your own CLI arguments to allow users to configure your CDK8s app generation.
+	 *
+	 * This can be overridden for local development (in case you need to pass custom configuration for running locally).
+	 */
+	args?: Arguments;
+	/**
+	 * A function which synthesizes your CDK8s app. Is expected to return an `App` instance.
+	 */
+	synth: (ctx: CommonContext<Output<Arguments>, Data>) => Awaitable<App>;
+
+	/**
+	 * Optional configuration for the generated `cmd-ts` command.
+	 */
+	command?: {
+		/**
+		 * @default "cdk8s-opinionated-cli"
+		 */
+		name?: string;
+		/**
+		 * @default "CLI for running CDK8s apps with opinionated defaults."
+		 */
+		description?: string;
+	};
+
+	/**
+	 * Configuration for the various subcommands of the CLI. All commands are enabled by default.
+	 */
+	subcommands: {
+		/**
+		 * Optional configuration for the `synth` subcommand.
+		 */
+		synth?: FeatureToggle<SynthConfig>;
+		/**
+		 * Optional configuration for the `local` command. `args` and `synth` are inherited from the main config,
+		 * but can be extended here.
+		 */
+		local?: FeatureToggle<PickPartial<LocalConfig<LocalArguments, Data, Arguments>, "synth">>;
+	};
+
+	/**
+	 * These hooks run at various points and allow you to customize the CLI's behavior.
+	 *
+	 * These will be _replaced_ by any hooks provided for individual subcommands.
+	 */
+	hooks?: {
+		/**
+		 * A function that will run immediately on startup, but with access to the parsed CLI arguments.
+		 *
+		 * You can return custom data that will be passed to subsequent hooks and the synth function.
+		 */
+		startup?: (ctx: CommonStartupContext<Output<Arguments>>) => Awaitable<Data | void>;
+	};
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+import type { ArgTypes } from "@repo/utils/cmd-ts-types";
+import { logger } from "@repo/utils/logger";
+import { $ } from "bun";
+import { KbldConfig } from "cdk8s-kbld2";
+import { binary, boolean, command, flag, run, type Runner, subcommands } from "cmd-ts";
+import type { ArgParser } from "cmd-ts/dist/cjs/argparser";
+import type { Aliased, Descriptive } from "cmd-ts/dist/cjs/helpdoc";
+import { ConstructOrder } from "constructs";
+import { rm } from "fs/promises";
+import path from "path";
+import type { Config } from "./config";
+
+export type { Config } from "./config";
+
+export async function cdk8sOpinionatedCliCommand<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes>(
+	config: Config<Arguments, Data, LocalArguments>,
+) {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const cmds: Record<string, ArgParser<any> & Runner<any, any> & Partial<Descriptive & Aliased>> = {};
+
+	if (config.subcommands.local?.enabled !== false) {
+		const { cdk8sLocalCommand } = await import("cdk8s-local");
+		const cmd = cdk8sLocalCommand<Arguments & LocalArguments, Data>({
+			synth: config.synth,
+			...config.subcommands.local,
+			args: {
+				// Spreading `undefined` is safe and results in no additional arguments, which is the expected behaviour.
+				...config.args!,
+				// eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain
+				...config.subcommands.local?.args!,
+			},
+			hooks: {
+				...config.hooks,
+				...config.subcommands.local?.hooks,
+			},
+		});
+		cmds["local"] = cmd;
+	}
+
+	if (config.subcommands.synth?.enabled !== false) {
+		cmds["synth"] = command({
+			name: config.subcommands.synth?.command?.name ?? "synth",
+			description: config.subcommands.synth?.command?.description ?? "Synthesize the CDK8s app into K8s manifests.",
+			args: {
+				noBuild: flag({
+					type: boolean,
+					long: "no-build",
+					description: "only synthesise the manifests, do not build resulting manifests with kbld",
+				}),
+				...config.args!,
+			},
+			async handler(args) {
+				const startupCtx = { args, command: "synth" as const };
+				const ctx = {
+					...startupCtx,
+					data: (await config.hooks?.startup?.(startupCtx)) ?? ({} as Data),
+				};
+
+				logger.info("Running synth (generating manifests)...");
+
+				const app = await config.synth(ctx);
+				await rm(app.outdir, { recursive: true, force: true });
+				app.synth();
+
+				if (args.noBuild) {
+					logger.info("Synth complete, skipping build, find manifests in " + path.relative(process.cwd(), app.outdir));
+					return;
+				}
+
+				if (app.node.findAll(ConstructOrder.POSTORDER).find((c) => c instanceof KbldConfig)) {
+					logger.info("Detected kbld config construct, running kbld...");
+					try {
+						const buffer = await $`kbld -f ${app.outdir}`.arrayBuffer();
+						process.stdout.write(Buffer.from(buffer));
+					} catch (e) {
+						if (e instanceof $.ShellError) {
+							logger.error(e.stderr.toString("utf-8"));
+							logger.fatal("Failed to build images from manifests.");
+							return 1;
+						}
+						throw e;
+					}
+				}
+			},
+		});
+	}
+
+	return subcommands({
+		name: config.command?.name ?? "cdk8s-opinionated-cli",
+		description: config.command?.description ?? "CLI for running CDK8s apps with opinionated defaults.",
+		cmds,
+	});
+}
+
+export async function cdk8sOpinionatedCli<Arguments extends ArgTypes, Data, LocalArguments extends ArgTypes>(
+	config: Config<Arguments, Data, LocalArguments>,
+) {
+	const cmd = await cdk8sOpinionatedCliCommand(config);
+	return await run(binary(cmd), process.argv);
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "@repo/typescript-config/tsconfig.base.json",
+	"include": ["src", "tsdown.config.ts"]
+}