feat(extensions): nativescript.commands map — per-command lazy loading for extensions

[edusperoni]

Stacked on #6101 (feat/define-command); #6099 (the DI foundation) is merged into main.

PR Checklist

• The PR title follows our guidelines: https://github.com/NativeScript/NativeScript/blob/master/tools/notes/CONTRIBUTING.md#commit-messages.
• There is an issue for the bug/feature this PR is for. To avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it.
• You have signed the CLA.
• All existing tests are passing: https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#contribute-to-the-code-base
• Tests for the changes are included.

What is the current behavior?

Every installed extension is eagerly require()d on every CLI invocation, before the command is even known — the extension's whole module tree loads so its top-level side effects can register commands against global.$injector. nativescript.commands in an extension's package.json is a string[] used only to suggest installs for unknown commands. Two extensions claiming the same command name crash at startup.

What is the new behavior?

nativescript.commands also accepts a map of command name → module path, which becomes authoritative:

"nativescript": {
	"commands": {
		"widget|add": "./dist/commands/widget-add.js",
		"widget|new": { "path": "./dist/commands/widget-add.js" }  // alias: same module, second entry
	}
}

• Per-command lazy loading: nothing from the extension loads until one of its commands actually executes; the extension main is never required, and map-manifest extensions are not flagged by the deprecation tracer (the legacy array/eager path keeps working verbatim, tracer included). Values accept string | { path } so the envelope can grow additively.
• The manifest key is authoritative: routing works before any module loads. If a loaded defineCommand definition's name disagrees with its manifest key, the CLI warns naming both and runs under the key. Aliases are duplicate manifest entries pointing at the same module.
• registerDeferredCommand on the CommandRegistry facet: claiming a name and loading its implementation are now separate registry operations. The registry builds the command record, the parent's subcommand list, and the parent dispatcher from the name alone — a sibling's dispatch never drags in the first claimant's module — and returns a structured DeferredCommandResult (claimed / built-in / subcommand-parent / invalid-name) instead of exception text callers must match on. This is what keeps the future registry extraction a provider swap.
• Failure UX: loader failures name the command, the owning extension, and the module path; a loader that runs but registers nothing fails the same way; non-lowercase manifest keys (permanently unreachable — dispatch lower-cases input) warn and are skipped without sinking the extension's other commands. Built-in conflicts say "already provided by the CLI", no internals.
• Deterministic defaults: *default entries sort first per parent in code — JSON key order carries no meaning. First-wins conflict resolution is defined in the docs (extension load order, alphabetical; the mid-load ns extension install exception documented). Re-declaring a command under the same owner is a no-op, so ns extension install <already-installed> no longer warns about conflicting with itself. "commands": {} opts out of loading entirely.
• A command module may self-register on load (legacy shape) or simply export a defineCommand definition — one registration code path (registerDefinitionAs) serves both the manifest loader and registerCommandDefinition.
• ILazyRequireProvider is no longer part of the exported Provider union (container-internal).
• New authoring guide: extensions.md — leads with the peerDependency + devDependency on nativescript and inject() from nativescript/contracts.

Public type names follow the new-API convention (no I prefix): DeferredCommandOptions, DeferredCommandResult, DeferredCommandRejection.

25 tests in test/extension-manifests.ts (lazy registration, eager-path preservation, malformed/conflict/self-conflict handling, both suggestion shapes, pure-definition modules incl. resolving the parent dispatcher before any child module has loaded, key-mismatch warning, alias entries, {} opt-out). Full stacked suite: 116 files, 1784 passed / 9 skipped; yok oracle, public-API test, and compat fixtures untouched.

Summary by CodeRabbit

• New Features

  • Extensions can declare CLI commands directly in their manifests.
  • Commands are loaded on demand, with support for command definitions and aliases.
  • Added validation and clear handling for naming conflicts, malformed entries, and loading failures.
  • Extension metadata now reports declared commands.
  • Added comprehensive documentation for CLI extensions and command configuration.

• Documentation

  • Added related-guide links and updated command declaration guidance.

[coderabbitai]

📝 Walkthrough

Walkthrough

The CLI adds deferred command registration for extension manifest maps. It validates command names, resolves ownership conflicts, loads modules lazily, adapts exported command definitions, preserves legacy arrays, and documents the supported extension formats.

Changes

Declarative Extension Commands

Layer / File(s)	Summary
Command contracts and container providers lib/common/contracts/..., lib/common/di/..., lib/common/definitions/extensibility.d.ts	Adds deferred command contracts, internal provider types, resolver detection, and extension command metadata.
Deferred command registry lib/common/yok.ts	Adds name validation, ownership tracking, conflict handling, lazy loading, structured failures, and hierarchical command wiring.
Manifest command loading lib/common/services/command-definition-adapter.ts, lib/services/extensibility-service.ts	Registers command maps lazily, supports command definitions and legacy self-registration, preserves array manifests, and reports mismatches.
Validation and extension documentation test/extension-manifests.ts, extensions.md, defining-commands.md, dependency-injection.md	Adds manifest and loading tests and documents installation, command formats, conflicts, aliases, defaults, and command help configuration.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ExtensionManifest
  participant ExtensibilityService
  participant CommandRegistry
  participant LazyCommandModule
  participant CommandDefinitionAdapter
  ExtensionManifest->>ExtensibilityService: Declare nativescript.commands map
  ExtensibilityService->>CommandRegistry: Register deferred command
  CommandRegistry->>LazyCommandModule: Load command module on lookup
  LazyCommandModule->>CommandDefinitionAdapter: Adapt exported command definition
  CommandDefinitionAdapter->>CommandRegistry: Register definition under manifest name

Loading

Possibly related PRs

• NativeScript/nativescript-cli#6099: Adds DI and Yok registration mechanics used by deferred command registration.
• NativeScript/nativescript-cli#6101: Adds the declarative command system extended by manifest-based command definitions.

Suggested reviewers: nathanwalker

Poem

I’m a rabbit with commands in a map,
Loading each burrow only when tapped.
Conflicts are checked, aliases align,
Definitions register under each sign.
Lazy hops keep the CLI bright—
Tests guard every route just right.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies per-command lazy loading through the nativescript.commands map, which is the primary change.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[NathanWalker]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved and pushed in commit 6568c06 by merging origin/main into this branch and fixing the conflicts in defining-commands.md, lib/common/services/command-definition-adapter.ts, and lib/contracts/index.ts.

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

test/extension-manifests.ts (1)

592-619: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert the single module load in the alias test.

The test name states that the shared module is loaded once. The body does not assert that. Add an assertion on capture.loadedModules after both resolutions, so a regression that reloads the module per alias fails this test.

♻️ Proposed assertion

 			assert.isOk(testInjector.resolveCommand("nsmalias|run"));
 			const aliased = testInjector.resolveCommand("nsmalias|r");
 			assert.isOk(aliased);
+			assert.deepEqual(capture.loadedModules, ["alias-run"]);
 
 			await aliased.execute(["x"]);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/extension-manifests.ts` around lines 592 - 619, Add an assertion to the
alias test after resolving both commands in “routes two aliases of one command
to the same module” that verifies capture.loadedModules contains exactly one
load of the shared module; keep the existing command execution and
capture.executed assertions unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@extensions.md`:
- Line 18: Convert the section headings in extensions.md, including the heading
near “Depending on the CLI” and those at the referenced locations, from ATX
syntax to setext syntax consistent with the file and related documentation. Add
the text language identifier to the unlabeled fenced block near line 263 while
preserving its contents.

In `@lib/common/yok.ts`:
- Around line 159-233: Update registerDeferredCommand to reject a hierarchical
child when its direct parent command is already registered, before calling
super.register or mutating ownership/command state. Add a dedicated structured
reason to DeferredCommandRejection and handle it in describeRejection,
preserving existing behavior for valid parent-child registrations.
- Around line 107-108: Initialize deferredCommandOwners with a null-prototype
object via Object.create(null) instead of a normal object, so command names such
as constructor cannot resolve inherited Object.prototype properties during
ownership checks.

In `@test/extension-manifests.ts`:
- Around line 462-479: Update the fixture generation logic around
definitionModule to resolve the contracts module through Vitest’s requireService
loader before constructing the generated JavaScript, instead of using plain
require.resolve. Ensure the generated fixture embeds the loader-resolved path so
its later plain require can load lib/contracts consistently.

---

Nitpick comments:
In `@test/extension-manifests.ts`:
- Around line 592-619: Add an assertion to the alias test after resolving both
commands in “routes two aliases of one command to the same module” that verifies
capture.loadedModules contains exactly one load of the shared module; keep the
existing command execution and capture.executed assertions unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7b8aebe3-5ac4-44bf-a4d4-08d2aba24c24

📥 Commits

Reviewing files that changed from the base of the PR and between 2f81d7f and 6568c06.

📒 Files selected for processing (13)

• defining-commands.md
• dependency-injection.md
• extensions.md
• lib/common/contracts/command-registry.ts
• lib/common/contracts/index.ts
• lib/common/definitions/extensibility.d.ts
• lib/common/di/index.ts
• lib/common/di/injector.ts
• lib/common/di/providers.ts
• lib/common/services/command-definition-adapter.ts
• lib/common/yok.ts
• lib/services/extensibility-service.ts
• test/extension-manifests.ts

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Match the repository heading style and label the output fence.

markdownlint reports MD003 for every ## heading in this file. The file itself opens with a setext heading at Lines 1-2, and defining-commands.md and dependency-injection.md use setext throughout. Convert the section headings to setext. Also add a language to the fenced block at Line 263 to clear MD040.

📝 Proposed fixes

-## Depending on the CLI
+Depending on the CLI
+--------------------

-```
+```text
 The command hello world is registered in extension nativescript-hello.
 You can install it by executing 'ns extension install nativescript-hello'

Apply the same setext conversion to the headings at Lines 66, 71, 142, 165, 205, 236, 250, and 268.
</details>


Also applies to: 263-263

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.23.2)</summary>

[warning] 18-18: Heading style
Expected: setext; Actual: atx

(MD003, heading-style)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @extensions.md at line 18, Convert the section headings in extensions.md,
including the heading near “Depending on the CLI” and those at the referenced
locations, from ATX syntax to setext syntax consistent with the file and related
documentation. Add the text language identifier to the unlabeled fenced block
near line 263 while preserving its contents.

</details>

<!-- fingerprinting:phantom:medusa:komodo -->

<!-- cr-indicator-types:potential_issue -->

<!-- cr-comment:v1:2480f365076ff0b80a97457f -->

_Source: Linters/SAST tools_

<!-- This is an auto-generated comment by CodeRabbit -->

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use a null-prototype map for deferred ownership.

A manifest can declare the lowercase command name constructor. Line 172 then reads the inherited Object.prototype.constructor value and returns a false "claimed" rejection. Initialize deferredCommandOwners with Object.create(null).

Proposed fix

- private deferredCommandOwners: IDictionary<string> = {};
+ private deferredCommandOwners: IDictionary<string> = Object.create(null);

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	/** Deferred command name -> the owner that claimed it first. */
	private deferredCommandOwners: IDictionary<string> = {};
	/** Deferred command name -> the owner that claimed it first. */
	private deferredCommandOwners: IDictionary<string> = Object.create(null);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/common/yok.ts` around lines 107 - 108, Initialize deferredCommandOwners
with a null-prototype object via Object.create(null) instead of a normal object,
so command names such as constructor cannot resolve inherited Object.prototype
properties during ownership checks.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Reject a child command when its direct parent already exists.

If a manifest declares foo before foo|bar, this method registers foo|bar and reports success. Lines 231-233 then call createHierarchicalCommand, which detects the direct foo command, logs that foo|bar cannot be reached, and does not install a dispatcher. Reject this conflict before registering the child. Add a structured rejection reason and update DeferredCommandRejection and describeRejection with the same reason.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/common/yok.ts` around lines 159 - 233, Update registerDeferredCommand to
reject a hierarchical child when its direct parent command is already
registered, before calling super.register or mutating ownership/command state.
Add a dedicated structured reason to DeferredCommandRejection and handle it in
describeRejection, preserving existing behavior for valid parent-child
registrations.

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Inspect how `lib/contracts` resolves and how tests are executed.
set -euo pipefail

fd -a 'contracts' lib --max-depth 2
fd -a 'index.ts' lib/contracts 2>/dev/null || true

# Test runner configuration and TS handling
fd -H -t f 'vitest.config.*|vite.config.*|tsconfig*.json' . --max-depth 2 --exec cat -n {}

# How the test script is invoked
rg -n '"(test|pretest|build)"\s*:' package.json -A2

Repository: NativeScript/nativescript-cli

Length of output: 2626

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate extension-manifests.ts and inspect the relevant fixture-generation snippet plus any build hooks.
fd -a 'extension-manifests.ts' test scripts --max-depth 3 --exec sh -c '
  echo "FILE: $1"
  wc -l "$1"
  sed -n "420,530p" "$1" | cat -n
' sh {}

# Check whether lib/contracts has a package.json or otherwise supports Node require from lib-relative paths.
if [ -f lib/contracts/package.json ]; then
  cat -n lib/contracts/package.json
else
  echo "NO_PACKAGE_JSON"
fi

# Show lockfile/package versions related to vitest/vite/ts to infer runtime support if needed.
for f in package-lock.json pnpm-lock.yaml yarn.lock bun.lock; do
  if [ -f "$f" ]; then
    echo "LOCKFILE: $f"
    rg -n "vitest|typescript|ts-node" "$f" -A2 -B2 | head -n 80 || true
  fi
done

# Behavioral probe from repository file contents using Node without running repository scripts:
# - Resolve the same path from the repo root using node's internal require.resolve semantics if available.
# - Check whether the target file exists at the TypeScript source vs package.json "main" vs compiled dist target.
node - <<'JS'
const fs = require('fs');
const path = require('path');

console.log('NODE_VERSION', process.version);
console.log('CWD', process.cwd());

const source = path.join(process.cwd(), 'lib/contracts/index.ts');
const dist = path.join(process.cwd(), 'dist/lib/contracts/index.js');
const pkg = path.join(process.cwd(), 'lib/contracts/package.json');

console.log('SOURCE_EXISTS', fs.existsSync(source));
console.log('SOURCE_REALPATH', fs.realpathSync(source));
console.log('DIST_EXISTS', fs.existsSync(dist));
console.log('PKG_EXISTS', fs.existsSync(pkg));
console.log('PKG_CONTENT', fs.existsSync(pkg) ? JSON.parse(fs.readFileSync(pkg, 'utf8')) : null);

try {
  const r = require.resolve('../lib/contracts');
  console.log('REQUIRE_RESOLVE', r);
  console.log('REQUIRE_RESOLVE_EXISTS', fs.existsSync(r) || fs.existsSync(r + '.js') || fs.existsSync(r + '.' + (path.extname(r) || '').slice(1)));
  console.log('FS_STAT', fs.statSync(r));
} catch (e) {
  console.log('REQUIRE_RESOLVE_ERROR', e.code || e.message);
}
JS

Repository: NativeScript/nativescript-cli

Length of output: 7774

---

Route requireService through Vitest’s module loader before using require.resolve.

require.resolve("../lib/contracts") resolves inside the test process, but the generated fixture is a compiled .js file that later runs with plain require. Since lib/contracts/index.ts is not a Node module, this can fail unless Vitest’s loader intercepts that load. Make the fixture generation path consistent with test execution.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/extension-manifests.ts` around lines 462 - 479, Update the fixture
generation logic around definitionModule to resolve the contracts module through
Vitest’s requireService loader before constructing the generated JavaScript,
instead of using plain require.resolve. Ensure the generated fixture embeds the
loader-resolved path so its later plain require can load lib/contracts
consistently.