feat(commands): option groups, invocation scopes and the invocation record

- `defineOptions(name, schema)` declares an option group: a schema that is
  also an injection token typed as its parsed values. `options` takes a
  schema or a list of groups and schemas, and `ctx.options` is typed as the
  merged values. Spellings collide only with different specs; an alias may
  not equal another option's spelling.
- Every non-root group a command declares is provided in the invocation
  injector with its slice of the parsed values. `CliOptions` is the
  process-level group, provided at the root; the option table derives its
  global entries from it, and a command may list it but not redeclare its
  spellings. The built-ins that redeclared `--path` or `--help` list it.
- `OptionContributions` adds groups to a command by any of its names, own or
  registered, or to the root, ahead of the parse that targets them.
- `providedIn` on a provider, an implementation class (`@ProvidedIn`) or a
  contract puts the instance on the nearest injector of that scope in the
  resolving chain; the adapter opens each invocation's injector in the
  `invocation` scope and disposes it when the invocation ends. Resolving a
  scoped record from outside its scope is an error, `optional` or not.
- `currentInvocationInjector()` resolves the synchronous injection context,
  then the invocation's asynchronous flow, then the most recently opened
  invocation. Hooks resolve their by-name dependencies against it, and a
  definition run as given defaults its scope to it. An in-process dispatch
  closes the invocations it opened.

Author: edusperoni

lib/commands/create-project.ts

@@ -3,10 +3,12 @@ import { color } from "../color";
 import {
 	booleanOption,
 	Command,
+	CommandOptionsInput,
 	CommandOptionsSchema,
-	CommandOptionValues,
+	OptionValuesOf,
 	stringOption,
 } from "../common/define-command";
+import { CliOptions } from "../common/contracts/cli-options";
 import { inject } from "../common/di";
 import { isInteractive } from "../common/helpers";
 import * as constants from "../constants";
@@ -27,27 +29,29 @@ const TABS_TEMPLATE_KEY = "Tabs";
 const TABS_TEMPLATE_DESCRIPTION =
 	"An app with pre-built pages that uses tabs for navigation";
 
-const createProjectCommandOptions = {
-	js: booleanOption(),
-	ng: booleanOption(),
-	react: booleanOption(),
-	solid: booleanOption(),
-	svelte: booleanOption(),
-	tsc: booleanOption(),
-	vue: booleanOption(),
-	vuejs: booleanOption(),
-	vision: booleanOption(),
-	"vision-ng": booleanOption(),
-	"vision-react": booleanOption(),
-	"vision-solid": booleanOption(),
-	"vision-svelte": booleanOption(),
-	"vision-vue": booleanOption(),
-	template: stringOption(),
-	appid: stringOption(),
-	path: stringOption(),
-	force: booleanOption(),
-	ignoreScripts: booleanOption(),
-} satisfies CommandOptionsSchema;
+const createProjectCommandOptions = [
+	CliOptions,
+	{
+		js: booleanOption(),
+		ng: booleanOption(),
+		react: booleanOption(),
+		solid: booleanOption(),
+		svelte: booleanOption(),
+		tsc: booleanOption(),
+		vue: booleanOption(),
+		vuejs: booleanOption(),
+		vision: booleanOption(),
+		"vision-ng": booleanOption(),
+		"vision-react": booleanOption(),
+		"vision-solid": booleanOption(),
+		"vision-svelte": booleanOption(),
+		"vision-vue": booleanOption(),
+		template: stringOption(),
+		appid: stringOption(),
+		force: booleanOption(),
+		ignoreScripts: booleanOption(),
+	} satisfies CommandOptionsSchema,
+] satisfies CommandOptionsInput;
 
 interface ITemplateChoice {
 	key?: string;
@@ -217,7 +221,7 @@ const flavorTemplates: { [flavorName: string]: () => ITemplateChoice[] } = {
 
 /** The template a flavor flag selects, without asking anything. */
 function selectTemplateFromOptions(
-	options: CommandOptionValues<typeof createProjectCommandOptions>,
+	options: OptionValuesOf<typeof createProjectCommandOptions>,
 ): string {
 	if (options["vision-ng"] || (options.vision && options.ng)) {
 		return constants.RESERVED_TEMPLATE_NAMES["vision-ng"];

lib/commands/install.ts

@@ -3,10 +3,12 @@ import { IFileSystem } from "../common/declarations";
 import {
 	booleanOption,
 	CommandContext,
+	CommandOptionsInput,
 	CommandOptionsSchema,
 	defineCommand,
 	stringOption,
 } from "../common/define-command";
+import { CliOptions } from "../common/contracts/cli-options";
 import { PlatformTypes } from "../constants";
 import {
 	INodePackageManager,
@@ -19,12 +21,14 @@ import { IProjectDataService } from "../definitions/project";
 import { ProjectData } from "../contracts/project-data";
 import { provideProject } from "./command-base";
 
-const installCommandOptions = {
-	frameworkPath: stringOption(),
-	disableNpmInstall: booleanOption(),
-	ignoreScripts: booleanOption(),
-	path: stringOption(),
-} satisfies CommandOptionsSchema;
+const installCommandOptions = [
+	CliOptions,
+	{
+		frameworkPath: stringOption(),
+		disableNpmInstall: booleanOption(),
+		ignoreScripts: booleanOption(),
+	} satisfies CommandOptionsSchema,
+] satisfies CommandOptionsInput;
 
 async function installProjectDependencies(
 	context: CommandContext<typeof installCommandOptions>,

lib/commands/plugin/build-plugin.ts

@@ -8,17 +8,21 @@ import {
 import { IFileSystem } from "../../common/declarations";
 import {
 	Command,
+	CommandOptionsInput,
 	CommandOptionsSchema,
 	stringOption,
 } from "../../common/define-command";
+import { CliOptions } from "../../common/contracts/cli-options";
 import { inject } from "../../common/di";
 import { ITempService } from "../../definitions/temp-service";
 
-const buildPluginCommandOptions = {
-	path: stringOption(),
-	gradlePath: stringOption(),
-	gradleArgs: stringOption(),
-} satisfies CommandOptionsSchema;
+const buildPluginCommandOptions = [
+	CliOptions,
+	{
+		gradlePath: stringOption(),
+		gradleArgs: stringOption(),
+	} satisfies CommandOptionsSchema,
+] satisfies CommandOptionsInput;
 
 export class BuildPluginCommand extends Command({
 	name: "plugin|build",

lib/commands/plugin/create-plugin.ts

@@ -4,9 +4,11 @@ import { INodePackageManager } from "../../declarations";
 import { IErrors, IFileSystem, IChildProcess } from "../../common/declarations";
 import {
 	Command,
+	CommandOptionsInput,
 	CommandOptionsSchema,
 	stringOption,
 } from "../../common/define-command";
+import { CliOptions } from "../../common/contracts/cli-options";
 import { inject } from "../../common/di";
 import { ITerminalSpinnerService } from "../../definitions/terminal-spinner-service";
 
@@ -21,14 +23,16 @@ export const INCLUDE_ANGULAR_DEMO_MESSAGE =
 export const PATH_ALREADY_EXISTS_MESSAGE_TEMPLATE =
 	"Path already exists and is not empty %s";
 
-const createPluginCommandOptions = {
-	path: stringOption(),
-	template: stringOption(),
-	username: stringOption(),
-	pluginName: stringOption(),
-	includeTypeScriptDemo: stringOption(),
-	includeAngularDemo: stringOption(),
-} satisfies CommandOptionsSchema;
+const createPluginCommandOptions = [
+	CliOptions,
+	{
+		template: stringOption(),
+		username: stringOption(),
+		pluginName: stringOption(),
+		includeTypeScriptDemo: stringOption(),
+		includeAngularDemo: stringOption(),
+	} satisfies CommandOptionsSchema,
+] satisfies CommandOptionsInput;
 
 export class CreatePluginCommand extends Command({
 	name: "plugin|create",

lib/commands/test-init.ts

@@ -7,10 +7,12 @@ import { INodePackageManager } from "../declarations";
 import { IPluginsService } from "../definitions/plugins";
 import {
 	Command,
+	CommandOptionsInput,
 	CommandOptionsSchema,
 	booleanOption,
 	stringOption,
 } from "../common/define-command";
+import { CliOptions } from "../common/contracts/cli-options";
 import { inject } from "../common/di";
 import {
 	IDictionary,
@@ -26,13 +28,15 @@ const karmaConfigAdditionalFrameworks: IDictionary<string[]> = {
 	mocha: ["chai"],
 };
 
-const testInitCommandOptions = {
-	framework: stringOption(),
-	disableNpmInstall: booleanOption(),
-	frameworkPath: stringOption(),
-	ignoreScripts: booleanOption(),
-	path: stringOption(),
-} satisfies CommandOptionsSchema;
+const testInitCommandOptions = [
+	CliOptions,
+	{
+		framework: stringOption(),
+		disableNpmInstall: booleanOption(),
+		frameworkPath: stringOption(),
+		ignoreScripts: booleanOption(),
+	} satisfies CommandOptionsSchema,
+] satisfies CommandOptionsInput;
 
 export class TestInitCommand extends Command({
 	name: "test|init",

lib/common/bootstrap.ts

@@ -23,6 +23,7 @@ injector.require("stringParameter", "./command-params");
 injector.require("stringParameterBuilder", "./command-params");
 
 injector.require("commandsService", "./services/commands-service");
+injector.require("optionContributions", "./services/option-contributions");
 
 injector.require("messagesService", "./services/messages-service");
 

lib/common/commands/help.ts

@@ -1,15 +1,14 @@
 import * as _ from "lodash";
 import { CommandRegistry } from "../contracts/command-registry";
 import { IHelpService } from "../declarations";
-import { booleanOption, defineCommand } from "../define-command";
+import { CliOptions } from "../contracts/cli-options";
+import { defineCommand } from "../define-command";
 import { inject } from "../di";
 
 export const helpCommandDefinition = defineCommand({
 	name: ["help", "/?"],
 	description: "Shows the help for a command.",
-	options: {
-		help: booleanOption(),
-	},
+	options: [CliOptions],
 	// The command names whatever command it explains, so every argument after
 	// the first is that command's own.
 	arguments: "any",

lib/common/contracts/cli-options.ts

@@ -0,0 +1,18 @@
+import { booleanOption, defineOptions, stringOption } from "../define-command";
+
+/**
+ * The process-level options: parsed once at startup, before a command is
+ * chosen, and read by the services that run for every command — the logger,
+ * analytics, project resolution. Provided at the root, so any service injects
+ * it. Its spellings are protected: a command may not redeclare one.
+ */
+export const CliOptions = defineOptions("cli", {
+	log: stringOption(),
+	verbose: booleanOption(),
+	version: booleanOption({ alias: "v" }),
+	help: booleanOption({ alias: "h" }),
+	profileDir: stringOption({ hasSensitiveValue: true }),
+	analyticsClient: stringOption(),
+	path: stringOption({ alias: "p", hasSensitiveValue: true }),
+	config: stringOption({ alias: "c", hasSensitiveValue: true }),
+});

lib/common/contracts/commands-service.ts

@@ -5,9 +5,11 @@ import type { CommandReference } from "../define-command";
 export interface CommandDispatchOptions {
 	/**
 	 * The injector a definition run as given is compiled against, the way
-	 * Angular's `createComponent` takes one. Omitted, the call's own injection
-	 * context is used, and the root when there is none. A registered name keeps
-	 * the scope it was registered under, so passing one with a name throws.
+	 * Angular's `createComponent` takes one. Omitted, the invocation running
+	 * now is used - the call's own injection context, else the invocation its
+	 * asynchronous flow belongs to, else the most recently opened one - and
+	 * the root when there is none. A registered name keeps the scope it was
+	 * registered under, so passing one with a name throws.
 	 */
 	injector?: Injector;
 }

lib/common/contracts/index.ts

@@ -19,5 +19,7 @@ export { COMMAND_PRECONDITIONS } from "./command-preconditions";
 export type { CommandPrecondition } from "./command-preconditions";
 export { CommandsService } from "./commands-service";
 export type { CommandDispatchOptions } from "./commands-service";
+export { CliOptions } from "./cli-options";
+export { OptionContributions } from "./option-contributions";
 export { ModuleRegistry } from "./module-registry";
 export { PublicApiBuilder } from "./public-api-builder";