nativescript 9.1.0-alpha.16 → 9.1.0-alpha.17

package/lib/common/contracts/command-registry.js

@@ -0,0 +1,16 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandRegistry = void 0;
+const contract_1 = require("../di/contract");
+let CommandRegistry = class CommandRegistry {
+};
+exports.CommandRegistry = CommandRegistry;
+exports.CommandRegistry = CommandRegistry = __decorate([
+    (0, contract_1.Contract)({ name: "commandRegistry" })
+], CommandRegistry);

package/lib/common/contracts/index.d.ts

@@ -0,0 +1,5 @@
+export { CommandRegistry } from "./command-registry";
+export type { DeferredCommandOptions, DeferredCommandRejection, DeferredCommandResult, } from "./command-registry";
+export { KeyCommandRegistry } from "./key-command-registry";
+export { ModuleRegistry } from "./module-registry";
+export { PublicApiBuilder } from "./public-api-builder";

package/lib/common/contracts/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicApiBuilder = exports.ModuleRegistry = exports.KeyCommandRegistry = exports.CommandRegistry = void 0;
+var command_registry_1 = require("./command-registry");
+Object.defineProperty(exports, "CommandRegistry", { enumerable: true, get: function () { return command_registry_1.CommandRegistry; } });
+var key_command_registry_1 = require("./key-command-registry");
+Object.defineProperty(exports, "KeyCommandRegistry", { enumerable: true, get: function () { return key_command_registry_1.KeyCommandRegistry; } });
+var module_registry_1 = require("./module-registry");
+Object.defineProperty(exports, "ModuleRegistry", { enumerable: true, get: function () { return module_registry_1.ModuleRegistry; } });
+var public_api_builder_1 = require("./public-api-builder");
+Object.defineProperty(exports, "PublicApiBuilder", { enumerable: true, get: function () { return public_api_builder_1.PublicApiBuilder; } });

package/lib/common/contracts/key-command-registry.d.ts

@@ -0,0 +1,7 @@
+import type { IKeyCommand, IValidKeyName } from "../definitions/key-commands";
+export declare abstract class KeyCommandRegistry {
+    abstract requireKeyCommand(name: IValidKeyName, file: string): void;
+    abstract registerKeyCommand(name: IValidKeyName, resolver: any): void;
+    abstract resolveKeyCommand(name: string): IKeyCommand;
+    abstract getRegisteredKeyCommandsNames(): string[];
+}

package/lib/common/contracts/key-command-registry.js

@@ -0,0 +1,16 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyCommandRegistry = void 0;
+const contract_1 = require("../di/contract");
+let KeyCommandRegistry = class KeyCommandRegistry {
+};
+exports.KeyCommandRegistry = KeyCommandRegistry;
+exports.KeyCommandRegistry = KeyCommandRegistry = __decorate([
+    (0, contract_1.Contract)({ name: "keyCommandRegistry" })
+], KeyCommandRegistry);

package/lib/common/contracts/module-registry.d.ts

@@ -0,0 +1,4 @@
+export declare abstract class ModuleRegistry {
+    abstract require(names: string | string[], file: string): void;
+    abstract overrideAlreadyRequiredModule: boolean;
+}

package/lib/common/contracts/module-registry.js

@@ -0,0 +1,16 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModuleRegistry = void 0;
+const contract_1 = require("../di/contract");
+let ModuleRegistry = class ModuleRegistry {
+};
+exports.ModuleRegistry = ModuleRegistry;
+exports.ModuleRegistry = ModuleRegistry = __decorate([
+    (0, contract_1.Contract)({ name: "moduleRegistry" })
+], ModuleRegistry);

package/lib/common/contracts/public-api-builder.d.ts

@@ -0,0 +1,5 @@
+export declare abstract class PublicApiBuilder {
+    abstract requirePublic(names: string | string[], file: string): void;
+    abstract requirePublicClass(names: string | string[], file: string): void;
+    abstract publicApi: any;
+}

package/lib/common/contracts/public-api-builder.js

@@ -0,0 +1,16 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicApiBuilder = void 0;
+const contract_1 = require("../di/contract");
+let PublicApiBuilder = class PublicApiBuilder {
+};
+exports.PublicApiBuilder = PublicApiBuilder;
+exports.PublicApiBuilder = PublicApiBuilder = __decorate([
+    (0, contract_1.Contract)({ name: "publicApiBuilder" })
+], PublicApiBuilder);

package/lib/common/declarations.d.ts

@@ -824,12 +824,23 @@ interface IAutoCompletionService {
 	isObsoleteAutoCompletionEnabled(): boolean;
 }
 
+interface IHookExecutionOptions {
+	/**
+	 * Set by call sites that fold the returned middlewares around a method (the
+	 * `@hook` decorator). Where nothing consumes them, `ctx.wrap()` rejects
+	 * instead of registering a middleware that would never run.
+	 */
+	consumesMiddlewares?: boolean;
+}
+
 interface IHooksService {
 	hookArgsName: string;
+	/** Resolves with the middlewares hooks registered through `ctx.wrap()`. */
 	executeBeforeHooks(
 		commandName: string,
 		hookArguments?: IDictionary<any>,
-	): Promise<void>;
+		options?: IHookExecutionOptions,
+	): Promise<import("./define-hook").HookMiddleware[]>;
 	executeAfterHooks(
 		commandName: string,
 		hookArguments?: IDictionary<any>,

package/lib/common/decorators.d.ts

@@ -0,0 +1,13 @@
+import { IInjector } from "./definitions/yok";
+export declare function cache(): any;
+interface MemoizeOptions {
+    hashFn?: (...args: any[]) => any;
+    shouldCache?: (result: any) => boolean;
+}
+export declare function memoize(options: MemoizeOptions): any;
+export declare function invokeBefore(methodName: string, methodArgs?: any[]): any;
+export declare function invokeInit(): any;
+export declare function exported(moduleName: string): any;
+export declare function performanceLog(localInjector?: IInjector): any;
+export declare function deprecated(additionalInfo?: string, localInjector?: IInjector): any;
+export {};

package/lib/common/define-command.d.ts

@@ -0,0 +1,53 @@
+export declare const COMMAND_DEFINITION_MARKER: unique symbol;
+export type CommandOptionType = "boolean" | "string" | "number" | "array";
+export interface CommandOptionSpec<TValue = any> {
+    type: CommandOptionType;
+    default?: TValue;
+    alias?: string | string[];
+    hasSensitiveValue?: boolean;
+    description?: string;
+}
+export interface DefaultedCommandOptionSpec<TValue = any> extends CommandOptionSpec<TValue> {
+    default: TValue;
+}
+export type CommandOptionSpecInit<TValue = any> = Omit<CommandOptionSpec<TValue>, "type">;
+export interface CommandOptionsSchema {
+    [optionName: string]: CommandOptionSpec;
+}
+type CommandOptionValue<TSpec> = TSpec extends CommandOptionSpec<infer TValue> ? TSpec extends {
+    default: any;
+} ? TValue : TValue | undefined : any;
+export type CommandOptionValues<TSchema extends CommandOptionsSchema> = {
+    [K in keyof TSchema]: CommandOptionValue<TSchema[K]>;
+};
+export interface CommandContext<TSchema extends CommandOptionsSchema = {}> {
+    args: string[];
+    options: CommandOptionValues<TSchema>;
+    fail(message: string): never;
+}
+export interface CommandDefinition<TSchema extends CommandOptionsSchema = {}> {
+    name: string | string[];
+    description?: string;
+    options?: TSchema;
+    arguments?: "none" | "any";
+    canExecute?(context: CommandContext<TSchema>): Promise<boolean> | boolean;
+    disableAnalytics?: boolean;
+    enableHooks?: boolean;
+    run(context: CommandContext<TSchema>): Promise<void> | void;
+}
+export type DefinedCommand<TSchema extends CommandOptionsSchema = {}> = CommandDefinition<TSchema> & {
+    readonly [COMMAND_DEFINITION_MARKER]: true;
+};
+interface IOptionHelper<TValue> {
+    (init: CommandOptionSpecInit<TValue> & {
+        default: TValue;
+    }): DefaultedCommandOptionSpec<TValue>;
+    (init?: CommandOptionSpecInit<TValue>): CommandOptionSpec<TValue>;
+}
+export declare const booleanOption: IOptionHelper<boolean>;
+export declare const stringOption: IOptionHelper<string>;
+export declare const numberOption: IOptionHelper<number>;
+export declare const arrayOption: IOptionHelper<string[]>;
+export declare function defineCommand<TSchema extends CommandOptionsSchema = {}>(definition: CommandDefinition<TSchema>): DefinedCommand<TSchema>;
+export declare function isCommandDefinition(value: any): value is DefinedCommand;
+export {};

package/lib/common/define-command.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayOption = exports.numberOption = exports.stringOption = exports.booleanOption = exports.COMMAND_DEFINITION_MARKER = void 0;
+exports.defineCommand = defineCommand;
+exports.isCommandDefinition = isCommandDefinition;
+exports.COMMAND_DEFINITION_MARKER = Symbol.for("nativescript:cli:commandDefinition");
+const optionHelper = (type) => ((init = {}) => ({
+    ...init,
+    type,
+}));
+exports.booleanOption = optionHelper("boolean");
+exports.stringOption = optionHelper("string");
+exports.numberOption = optionHelper("number");
+exports.arrayOption = optionHelper("array");
+const DEFINITION_FIELDS = [
+    "name",
+    "description",
+    "options",
+    "arguments",
+    "canExecute",
+    "disableAnalytics",
+    "enableHooks",
+    "run",
+];
+const OPTION_SPEC_FIELDS = [
+    "type",
+    "default",
+    "alias",
+    "hasSensitiveValue",
+    "description",
+];
+const OPTION_TYPES = [
+    "boolean",
+    "string",
+    "number",
+    "array",
+];
+const ACCEPTED_FORM = 'defineCommand({ name: "widget|add", run(ctx) { ... } }) — with the ' +
+    "optional fields description, options, arguments, canExecute, " +
+    "disableAnalytics and enableHooks.";
+const describeDefinition = (definition) => {
+    const name = definition && definition.name;
+    if (typeof name === "string" && name.length) {
+        return `'${name}'`;
+    }
+    if (Array.isArray(name) && typeof name[0] === "string" && name[0].length) {
+        return `'${name[0]}'`;
+    }
+    return "an unnamed command";
+};
+const invalid = (definition, problem) => {
+    throw new Error(`Invalid command definition for ${describeDefinition(definition)}: ` +
+        `${problem}. Accepted form: ${ACCEPTED_FORM}`);
+};
+const isPlainObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const validateName = (definition) => {
+    const name = definition.name;
+    const isUsableName = (value) => typeof value === "string" && value.trim().length > 0;
+    if (isUsableName(name)) {
+        return;
+    }
+    if (Array.isArray(name) && name.length && name.every(isUsableName)) {
+        return;
+    }
+    invalid(definition, "'name' must be a non-empty string, or an array of non-empty strings for a command with aliases");
+};
+const validateOptionSpec = (definition, optionName, spec) => {
+    if (!isPlainObject(spec)) {
+        invalid(definition, `option '${optionName}' must be declared with one of booleanOption(), stringOption(), numberOption() or arrayOption()`);
+    }
+    if (OPTION_TYPES.indexOf(spec.type) === -1) {
+        invalid(definition, `option '${optionName}' has type '${spec.type}'; the supported types are ${OPTION_TYPES.join(", ")} — declare it with one of booleanOption(), stringOption(), numberOption() or arrayOption()`);
+    }
+    const unknownFields = Object.keys(spec).filter((field) => OPTION_SPEC_FIELDS.indexOf(field) === -1);
+    if (unknownFields.length) {
+        invalid(definition, `option '${optionName}' has unknown field(s) ${unknownFields
+            .map((field) => `'${field}'`)
+            .join(", ")}; an option spec accepts ${OPTION_SPEC_FIELDS.join(", ")}`);
+    }
+    const aliasIsUsable = spec.alias === undefined ||
+        typeof spec.alias === "string" ||
+        (Array.isArray(spec.alias) &&
+            spec.alias.length > 0 &&
+            spec.alias.every((entry) => typeof entry === "string"));
+    if (!aliasIsUsable) {
+        invalid(definition, `option '${optionName}' declares an 'alias' that is neither a string nor a non-empty array of strings`);
+    }
+    if (spec.hasSensitiveValue !== undefined &&
+        typeof spec.hasSensitiveValue !== "boolean") {
+        invalid(definition, `option '${optionName}' declares a non-boolean 'hasSensitiveValue'`);
+    }
+    if (spec.description !== undefined && typeof spec.description !== "string") {
+        invalid(definition, `option '${optionName}' declares a non-string 'description'`);
+    }
+};
+const validateDefinition = (definition) => {
+    if (!isPlainObject(definition)) {
+        invalid(definition, "expected an object");
+    }
+    const unknownFields = Object.keys(definition).filter((field) => DEFINITION_FIELDS.indexOf(field) === -1);
+    if (unknownFields.length) {
+        invalid(definition, `unknown field(s) ${unknownFields
+            .map((field) => `'${field}'`)
+            .join(", ")}; a definition accepts ${DEFINITION_FIELDS.join(", ")}`);
+    }
+    validateName(definition);
+    if (typeof definition.run !== "function") {
+        invalid(definition, "'run' must be a function");
+    }
+    if (definition.arguments !== undefined &&
+        definition.arguments !== "none" &&
+        definition.arguments !== "any") {
+        invalid(definition, `'arguments' is '${definition.arguments}'; it must be "none" or "any"`);
+    }
+    if (definition.canExecute !== undefined &&
+        typeof definition.canExecute !== "function") {
+        invalid(definition, "'canExecute' must be a function");
+    }
+    for (const flag of ["disableAnalytics", "enableHooks"]) {
+        if (definition[flag] !== undefined &&
+            typeof definition[flag] !== "boolean") {
+            invalid(definition, `'${flag}' must be a boolean`);
+        }
+    }
+    if (definition.description !== undefined) {
+        if (typeof definition.description !== "string") {
+            invalid(definition, "'description' must be a string");
+        }
+    }
+    if (definition.options !== undefined) {
+        if (!isPlainObject(definition.options)) {
+            invalid(definition, "'options' must be an object keyed by the long option name");
+        }
+        for (const optionName of Object.keys(definition.options)) {
+            validateOptionSpec(definition, optionName, definition.options[optionName]);
+        }
+    }
+};
+function defineCommand(definition) {
+    validateDefinition(definition);
+    const marked = { ...definition };
+    marked[exports.COMMAND_DEFINITION_MARKER] = true;
+    return marked;
+}
+function isCommandDefinition(value) {
+    return !!value && value[exports.COMMAND_DEFINITION_MARKER] === true;
+}

package/lib/common/define-hook.d.ts

@@ -0,0 +1,29 @@
+export declare const HOOK_DEFINITION_MARKER: unique symbol;
+export type HookMiddleware = (args: any[], next: (...args: any[]) => any) => any;
+export interface HookContext<TPayload = any> {
+    payload: TPayload | undefined;
+    wrap(middleware: HookMiddleware): void;
+    fail(message: string): never;
+    skip(message: string): never;
+}
+export type HookHandler<TPayload = any> = (ctx: HookContext<TPayload>) => void | Promise<void>;
+export interface HookDefinitionInput<TPayload = any> {
+    name: string;
+    run: HookHandler<TPayload>;
+}
+export interface HookDefinition<TPayload = any> {
+    readonly name: string;
+    readonly run: HookHandler<TPayload>;
+}
+export interface HookInvocation<TPayload = any> {
+    context: HookContext<TPayload>;
+    middlewares: HookMiddleware[];
+}
+export declare function defineHook<TPayload = any>(definition: HookDefinitionInput<TPayload>): HookDefinition<TPayload>;
+export declare function defineHook<TPayload = any>(name: string, run: HookHandler<TPayload>): HookDefinition<TPayload>;
+export declare function isHookDefinition<TPayload = any>(value: any): value is HookDefinition<TPayload>;
+export interface HookInvocationOptions {
+    hookName: string;
+    consumesMiddlewares?: boolean;
+}
+export declare function createHookInvocation<TPayload = any>(hookArguments: any, options: HookInvocationOptions): HookInvocation<TPayload>;

package/lib/common/define-hook.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_DEFINITION_MARKER = void 0;
+exports.defineHook = defineHook;
+exports.isHookDefinition = isHookDefinition;
+exports.createHookInvocation = createHookInvocation;
+exports.HOOK_DEFINITION_MARKER = Symbol.for("nativescript:cli:hookDefinition");
+const DEFINITION_FIELDS = ["name", "run"];
+const ACCEPTED_FORMS = 'defineHook({ name: "before-prepare", run: (ctx) => {} }) or ' +
+    'defineHook("before-prepare", (ctx) => {})';
+function describeDefinition(name) {
+    return typeof name === "string" && name.length
+        ? JSON.stringify(name)
+        : "<unnamed>";
+}
+function failToDefine(message) {
+    throw new Error(`${message} Accepted forms: ${ACCEPTED_FORMS}.`);
+}
+function defineHook(nameOrDefinition, run) {
+    const input = normalizeDefinitionInput(nameOrDefinition, run);
+    const definition = { name: input.name, run: input.run };
+    definition[exports.HOOK_DEFINITION_MARKER] = true;
+    return definition;
+}
+function normalizeDefinitionInput(nameOrDefinition, run) {
+    if (typeof nameOrDefinition === "string") {
+        if (!nameOrDefinition.length) {
+            failToDefine("defineHook() requires a non-empty hook point name.");
+        }
+        if (typeof run !== "function") {
+            failToDefine(`defineHook(${describeDefinition(nameOrDefinition)}) requires a handler function as its second argument.`);
+        }
+        return { name: nameOrDefinition, run };
+    }
+    if (!nameOrDefinition ||
+        typeof nameOrDefinition !== "object" ||
+        Array.isArray(nameOrDefinition)) {
+        failToDefine("defineHook() was called with an unsupported argument.");
+    }
+    const unknownFields = Object.keys(nameOrDefinition).filter((field) => DEFINITION_FIELDS.indexOf(field) === -1);
+    if (unknownFields.length) {
+        failToDefine(`defineHook(${describeDefinition(nameOrDefinition.name)}) received unknown ` +
+            `field${unknownFields.length > 1 ? "s" : ""} ` +
+            `${unknownFields.map((field) => JSON.stringify(field)).join(", ")}. ` +
+            `Supported fields: ${DEFINITION_FIELDS.map((field) => JSON.stringify(field)).join(", ")}.`);
+    }
+    if (typeof nameOrDefinition.name !== "string" || !nameOrDefinition.name) {
+        failToDefine('defineHook() requires a non-empty "name" naming the hook point.');
+    }
+    if (typeof nameOrDefinition.run !== "function") {
+        failToDefine(`defineHook(${describeDefinition(nameOrDefinition.name)}) requires "run" to be a function.`);
+    }
+    return { name: nameOrDefinition.name, run: nameOrDefinition.run };
+}
+function isHookDefinition(value) {
+    return (!!value &&
+        (typeof value === "object" || typeof value === "function") &&
+        value[exports.HOOK_DEFINITION_MARKER] === true &&
+        typeof value.run === "function" &&
+        typeof value.name === "string");
+}
+function createHookInvocation(hookArguments, options) {
+    const { hookName, consumesMiddlewares } = options;
+    const middlewares = [];
+    const context = {
+        payload: derivePayload(hookArguments),
+        wrap(middleware) {
+            if (!consumesMiddlewares) {
+                throw new Error(`ctx.wrap() is not available at the "${hookName}" hook point: nothing folds the middleware around a method there, so it would never run.`);
+            }
+            if (typeof middleware !== "function") {
+                throw new Error(`ctx.wrap() expects a function at the "${hookName}" hook point.`);
+            }
+            middlewares.push(middleware);
+        },
+        fail(message) {
+            throw new Error(hookMessage(message, hookName, "fail"));
+        },
+        skip(message) {
+            const error = new Error(hookMessage(message, hookName, "skip"));
+            error.stopExecution = false;
+            error.errorAsWarning = true;
+            throw error;
+        },
+    };
+    return { context, middlewares };
+}
+function hookMessage(message, hookName, method) {
+    return typeof message === "string" && message.trim().length
+        ? message
+        : `The "${hookName}" hook called ctx.${method}() without a message.`;
+}
+function derivePayload(hookArguments) {
+    if (!hookArguments || typeof hookArguments !== "object") {
+        return undefined;
+    }
+    if ("hookArgs" in hookArguments) {
+        return hookArguments["hookArgs"];
+    }
+    return Object.keys(hookArguments).length ? hookArguments : undefined;
+}

package/lib/common/definitions/commands.d.ts

@@ -16,6 +16,13 @@ interface ICommand extends ICommandOptions {
 	dashedOptions?: IDictionary<IDashedOption>;
 	isHierarchicalCommand?: boolean;
 
+	/**
+	 * Set on commands that forward their options to another CLI: the options
+	 * they accept are not knowable from this CLI's option dictionary, so
+	 * validating them here would reject the other CLI's flags.
+	 */
+	skipOptionsValidation?: boolean;
+
 	/**
 	 * Describes the action that will be executed after the command succeeds.
 	 * @param {string[]} args Arguments passed to the command.

package/lib/common/definitions/extensibility.d.ts

@@ -30,6 +30,13 @@ interface IExtensionData extends IExtensionName {
 	 * Full path to the directory of the installed extension.
 	 */
 	pathToExtension: string;
+
+	/**
+	 * Names of the commands the extension contributes, as declared in the commands key of the nativescript key of its package.json.
+	 * The key may be a map of command name to the module implementing it, in which case these are its keys, or the legacy array of command names, in which case these are its entries.
+	 * The property is not set when the extension declares no commands.
+	 */
+	commands?: string[];
 }
 
 /**

package/lib/common/definitions/key-commands.d.ts

@@ -0,0 +1,25 @@
+export type IKeyCommandPlatform = "Android" | "iOS" | "visionOS" | "all";
+export type IKeysLowerCase = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+export type IKeysUpperCase = Uppercase<IKeysLowerCase>;
+export declare enum SpecialKeys {
+    CtrlC = "\u0003",
+    QuestionMark = "?"
+}
+export type IKeysSpecial = `${SpecialKeys}`;
+export type IValidKeyName = IKeysLowerCase | IKeysUpperCase | IKeysSpecial;
+export interface IKeyCommandHelper {
+    attachKeyCommands: (platform: IKeyCommandPlatform, processType: SupportedProcessType) => void;
+    addOverride(key: IValidKeyName, execute: () => Promise<boolean>): void;
+    removeOverride(key: IValidKeyName): void;
+    printCommands(platform: IKeyCommandPlatform): void;
+}
+export type SupportedProcessType = "start" | "run";
+export interface IKeyCommand {
+    key: IValidKeyName;
+    platform: IKeyCommandPlatform;
+    description: string;
+    group: string;
+    willBlockKeyCommandExecution?: boolean;
+    execute(platform: string): Promise<void>;
+    canExecute?: (processType: SupportedProcessType) => boolean;
+}

package/lib/common/definitions/yok.d.ts

@@ -1,56 +1,64 @@
-import { IDisposable, IDictionary } from "../declarations";
-import { ICommand } from "./commands";
-import { IKeyCommand, IValidKeyName } from "./key-commands";
+import { IDictionary } from "../declarations";
+import { Injector } from "../di/injector";
+import { Provider } from "../di/providers";
+import { CommandRegistry } from "../contracts/command-registry";
+import { KeyCommandRegistry } from "../contracts/key-command-registry";
+import { ModuleRegistry } from "../contracts/module-registry";
+import { PublicApiBuilder } from "../contracts/public-api-builder";
 
-interface IInjector extends IDisposable {
-	require(name: string, file: string): void;
-	require(names: string[], file: string): void;
-	requirePublic(names: string | string[], file: string): void;
-	requirePublicClass(names: string | string[], file: string): void;
-	requireCommand(name: string, file: string): void;
-	requireCommand(names: string[], file: string): void;
-	requireKeyCommand(name: IValidKeyName, file: string): void;
+/**
+ * The legacy injector facade surface. It extends the token-based `Injector` —
+ * the facade IS an injector — and adds the legacy subsystems, whose members
+ * are individually @deprecated. Only the `Yok` class hierarchy implements
+ * this; the interface survives until the hook/extension deprecation completes.
+ */
+interface IInjector
+	extends
+		Injector,
+		CommandRegistry,
+		KeyCommandRegistry,
+		ModuleRegistry,
+		PublicApiBuilder {
 	/**
 	 * Resolves an implementation by constructor function.
 	 * The injector will create new instances for every call.
+	 * @deprecated Use Injector.createInstance.
 	 */
 	resolve(ctor: Function, ctorArguments?: { [key: string]: any }): any;
+	/**
+	 * @deprecated Use Injector.createInstance.
+	 */
 	resolve<T>(ctor: Function, ctorArguments?: { [key: string]: any }): T;
 	/**
 	 * Resolves an implementation by name.
 	 * The injector will create only one instance per name and return the same instance on subsequent calls.
+	 * @deprecated Use inject(Token) in an injection context, or Injector.get.
 	 */
 	resolve(name: string, ctorArguments?: IDictionary<any>): any;
+	/**
+	 * @deprecated Use inject(Token) in an injection context, or Injector.get.
+	 */
 	resolve<T>(name: string, ctorArguments?: IDictionary<any>): T;
 
-	resolveCommand(name: string): ICommand;
-	resolveKeyCommand(key: string): IKeyCommand;
+	/**
+	 * @deprecated Legacy name-based registration. Use the Provider overload or
+	 * provide(); a contract's token name keeps string spellings resolvable.
+	 */
 	register(name: string, resolver: any, shared?: boolean): void;
-	registerCommand(name: string, resolver: any): void;
-	registerCommand(names: string[], resolver: any): void;
-	registerKeyCommand(key: IValidKeyName, resolver: any): void;
-	getRegisteredCommandsNames(includeDev: boolean): string[];
-	getRegisteredKeyCommandsNames(): string[];
+	register(providers: Provider | Provider[]): void;
+	/**
+	 * @deprecated String-reflective help templating; removable only together
+	 * with the help-template pipeline.
+	 */
 	dynamicCallRegex: RegExp;
-	dynamicCall(call: string, args?: any[]): Promise<any>;
-	isDefaultCommand(commandName: string): boolean;
-	isValidHierarchicalCommand(
-		commandName: string,
-		commandArguments: string[]
-	): Promise<boolean>;
-	getChildrenCommandsNames(commandName: string): string[];
-	buildHierarchicalCommand(
-		parentCommandName: string,
-		commandLineArguments: string[]
-	): any;
-	publicApi: any;
-
 	/**
-	 * Defines if it's allowed to override already required module.
-	 * This can be used in order to allow redefinition of modules, for example $logger can be replaced by a plugin.
-	 * Default value is false.
+	 * @deprecated See dynamicCallRegex.
 	 */
-	overrideAlreadyRequiredModule: boolean;
+	dynamicCall(call: string, args?: any[]): Promise<any>;
 }
 
+/**
+ * @deprecated The process-wide legacy injector global. New code receives the
+ * container via inject(Injector) from lib/common/di.
+ */
 declare var $injector: IInjector;

package/lib/common/deprecation.d.ts

@@ -0,0 +1,12 @@
+interface IDeprecationLogger {
+    trace(...args: any[]): void;
+    warn(...args: any[]): void;
+}
+export interface IDeprecationReport {
+    api: string;
+    detail?: string;
+    logger?: IDeprecationLogger;
+}
+export declare function reportDeprecation(report: IDeprecationReport): void;
+export declare function clearReportedDeprecations(): void;
+export {};