feat: local plugin generation

[sohail2721]

No description provided.

[mrafnadeem-apimatic]

Review: conventions, single-use functions, cognitive complexity

Reviewed against dev's .ai/instructions.md (identical on this branch), plus two extra rules from the author:
no new function that has only one caller, and cognitive complexity must come down by design, not by splitting.
Each inline comment is a self-contained task. This comment has the overall picture and the order to do them in.

What is already right

Layering (Command → Action → Prompts/Context), ActionResult with no throws, withDirPath, private readonly arrow methods, .js imports, value-object paths at the Action boundary.

Cognitive complexity (Sonar rule, gate = 15)

Measured with eslint-plugin-sonarjs cognitive-complexity at threshold 0. It is the same metric SonarCloud gates on; there is no local rule.

	dev	this branch	prototype of the suggestions below
PluginGenerateAction: execute + helpers	12 + 1 = 13	13 + 3 + 1 + 2 = 19	15, one function, no helpers (at the gate, see below)
requestLanguages merge callback	—	4	2
ApimaticConfigContext.merge	6	8	7
selectLanguages	—	2	1

f2b34c9 extracted configWithMetadata, hasPublishingProfile and buildPlugin because inlining put execute at 21. That hid the growth from the per-function gate without reducing it. The inline comments show how to remove the points instead. The prototype passed tsc, ESLint, Prettier and the 193 tests in test/actions/plugin/*, test/types/plugin-config-context.test.ts and test/types/apimatic-config-context.test.ts. That was before the checkbox rule below, which changes behaviour and needs its own test changes.

To re-measure, from a scratch directory with eslint@9 eslint-plugin-sonarjs @typescript-eslint/parser typescript@5 installed:

// eslint.config.mjs
import sonarjs from 'eslint-plugin-sonarjs';
import parser from '@typescript-eslint/parser';
export default [{ files: ['**/*.ts'], languageOptions: { parser }, plugins: { sonarjs }, rules: { 'sonarjs/cognitive-complexity': ['error', 0] } }];

npx eslint --no-config-lookup -c eslint.config.mjs <copies of the changed files>: each message reads "from N to the 0 allowed".

Order of work

1. Checkbox rule (inline at src/prompts/plugin/generate.ts:119 and src/types/plugin-config-context.ts:193). Behaviour change; do it first because it removes code the other steps would otherwise refactor.
2. Inline the three action helpers using the design changes in the comments at src/actions/plugin/generate.ts:57, :77, :83, :145. Re-measure execute; it must stay ≤ 15.
3. Single-use functions in prompts/format/context (inline comments).
4. Validate once in PluginConfig (comment at src/types/plugin-config-context.ts:64).
5. Comments pass (list below).
6. pnpm build && pnpm test && pnpm lint. Do not commit or push without the author's go-ahead; the PR targets dev.

Comments are over the rule everywhere

The rule: a comment is a design smell; if unavoidable, one line of why; never restate the code, narrate a change, or address a reader. The branch deletes some old comments but adds ~18 multi-line blocks. Cut each to one line of why, or delete it once a better name carries it:

• src/actions/plugin/generate.ts: 75-76, 101-105, 125-131
• src/prompts/plugin/generate.ts: 13, 18-21, 26, 90-95, 122, 136-138, 150-154, 180-183, 188-196
• src/prompts/format.ts: 12-16, 23
• src/types/plugin-config-context.ts: 20, 48-53, 173-183
• src/types/apimatic-config-context.ts: 71-74
• src/types/sdk/generate.ts: 55-59

The one comment the branch should not have deleted is the getRelease() one (inline comment there).

Prototype of execute after steps 2-3, for reference. It predates the checkbox rule.

    const identified =
      configState.state === 'present' && configState.hasMetadata()
        ? ActionResult.success(configState)
        : await new PluginRecordMetadataAction(this.configDir, this.commandMetadata, this.authKey).execute(
            buildDirectory
          );
    if (!identified.isSuccess()) {
      return identified.discardValue();
    }

    const config = identified.getValue();
    const selection = await this.prompts.selectLanguages(config);
    if (!selection?.length) {
      this.prompts.noLanguagesSelected();
      return ActionResult.cancelled();
    }

    this.prompts.languagesNotIncluded(config.unsupportedLanguages());

    // Asked before the config is written, so a declined run leaves no languages claimed in it.
    const preview =
      selection.some((language) => !config.publishedLanguages().includes(language)) &&
      (
        await this.prompts.checkPublishingProfiles(
          this.publishingApiService.getPublishingProfiles(this.configDir, this.commandMetadata.shell)
        )
      )
        .andThen(PublishingProfiles.create)
        .map((profiles) => profiles.getActiveProfiles().length > 0)
        .unwrapOr(false);
    if (preview && !(await this.prompts.confirmLocalPlugin())) {
      this.prompts.localPluginCancelled();
      return ActionResult.cancelled();
    }

    const prepared = await configContext.prepareForUpload(selection);
    if (prepared.isErr()) {
      this.prompts.configNotPrepared(prepared.error, buildDirectory);
      return ActionResult.failed();
    }

    const generated = await withDirPath(async (tempDirectory) => {
      const tempContext = new TempContext(tempDirectory);
      const buildZipPath = await tempContext.zip(buildDirectory);
      const response = await this.prompts.generatePlugin(
        this.pluginService.generatePlugin(buildZipPath, this.configDir, this.commandMetadata, this.authKey)
      );
      return await response.asyncMap(async (stream) => pluginContext.save(await tempContext.save(stream)));
    });
    if (generated.isErr()) {
      this.prompts.pluginGenerationError(generated.error.errorMessage);
      return ActionResult.failed();
    }

    this.prompts.installPluginLocally(pluginDirectory);
    if (preview) {
      this.prompts.previewOnly();
    }
    return ActionResult.success();

Measured at 14 with preview passed into installPluginLocally. Per the author's own review comment (no boolean parameters that switch behaviour), previewOnly() stays a separate call made after generation, which makes it 15.
Test changes this needed: the metadataCancelled stubs in test/actions/plugin/generate.test.ts move to PluginRecordMetadataPrompts.prototype. In test/types/plugin-config-context.test.ts, requestLanguages → prepareForUpload and requestedLanguages() → initialLanguages().

15 is exactly at the gate. For headroom, the next thing to move is the three input guards at the top of execute (same directory, src exists, overwrite): they cost 4 points and predate this branch.

The author's own review comments on this PR take precedence wherever they overlap with these.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🎉 This PR is included in version 2.0.0-beta.1 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀