[saeedjamshaid]

Summary

These are the pre-release fixes from the 2.0 release review, planned in .ai/plans/release-2.0-fixes.md (added here). The review found no must-fix defects, but it did find concepts living in more than one place, a duplicated gate, an unguarded contract, and one recovery path with no tests. There are six commits: one per batch, one for a decision made in review, and two that answer a review of this PR. Each builds and passes the suite on its own. The plan's §3.8, §4.6 and §5.6 record where each commit departed from the plan.

1. One home per concept (fec7109d)

• The languages block of apimatic.json now has one module, types/apimatic-config/languages-block.ts. It holds the types, the entry builder, the merge, isPublished, and the portal's lenient reader. That reader names every key against its type, so a rename fails tsc instead of making the portal read nothing without any error. language-entry.ts is gone, and record-published-sdk.ts is back to just the action class.
• TIMING_DEFAULTS / GenerationTimings are defined once, in the generation poller, instead of once per service.
• FileService.readFile is gone. It duplicated getContents, and its only caller, hasContent, was itself unused.
• Portal output file names: _shell.html, 404.html and portal.zip are each named once, in portal-context.ts.
• languageLabel: code-samples.ts uses the shared function.
• Registry package-name fields are typed against the package configurations.
• Prompts name apimatic.json and nav.json by their constants. DirectoryPath.fromUserInput() replaces three hand-rolled trim-and-unquote copies.

2. Portal flow polish (c1f95a9d)

• One gate for generate and serve: the runtime and authorization checks move into PreparePortalProjectAction, which both commands run, and the copies go. Serve now probes its port once the project is prepared, so no fallback-port message appears before an authorization refusal.
• portal.config.json is typed on both sides: PortalBuildPaths in the CLI, and BuildPaths in the template, which renames its PortalConfig. The same Equal<> test that guards the identity file now holds the two to one shape.
• validation-service: validateViaFile closes its stream in a finally.
• Dev server output is cleaned of colour codes with node:util's stripVTControlCharacters.
• PortalContext.save gets its first tests (10 cases). A staging failure keeps the previous portal; a failed swap keeps the staged copy and says where it is.

3. One place that knows a project's layout (c5c55c36)

This redoes the intent of #372 on current dev.

• ProjectContext absorbs BuildContext, which is deleted. ProjectContext.at(input) and ProjectContext.in(directory) are the only ways to get one. Commands and actions take the project, and no caller joins src, sdk, portal or plugin onto a path anymore.
• A versioned build narrows the project to one version. versionToBuild() returns either the project to build from or a problem for the prompts to name. It replaces the closure that returned { version, buildContext } or an ActionResult, and the three getters that shared one preamble are now a single walk.
• The layout's names live once, in types/project-layout.ts. GENERATED, the list of .gitignore entries, is derived from the output names.
• The portal test fixtures are real projects, with their contents under src/.
• Tests: ProjectContext has the unit tests BuildContext never had, covering the layout, the versioned walk and the destination overrides.

No behavior changes.

4. Drop the spec pruning nothing calls (7b7b7d82)

On main, quickstart used ValidationService.stripUnallowedFeatures to strip spec features the subscription doesn't allow. #363 removed that call, and review decided the pruning does not come back. This commit deletes the method, along with parseErrorResponse and FeaturesToRemove, which existed only for it. It also removes what only fed the pruning:

• validateViaFile no longer decodes the x-unallowed-features header;
• UnallowedFeaturesResponse, RemovableFeature and the ValidateApiResponse wrapper go;
• ValidateAction returns a plain ActionResult, since nothing read its value.

5. Only the comments the code cannot say (ba90b550)

The batches added multi-line doc blocks that restated the code or narrated its design, against the one-line-of-why rule. They are cut to one line or removed. What stays is a constraint the code cannot show, such as the server's 25-minute limit behind the 30-minute timeout, or why /plugin/ must stay untracked.

6. Delete quickstart's Project, and keep the source checks in ProjectContext (f22c2fc3)

• Quickstart's Project record is gone. This finishes refactor: one place that knows a project's layout #372's "Project and BuildContext need to be deleted". The wizard runs as its two flows, adopting a downloaded project or starting a new one, which finish the same way. Each flow makes its ProjectContext once.
• Checks against the source directory live in ProjectContext. isSourceDirectory() and isSourceWithin() replace six hand-written comparisons. sourceDirectory() now serves only prompts and services, and context.md's exception says so.
• SonarCloud's three findings: the version problems reach one prompt keyed by problem, which drops the non-Error throw. The two smaller findings are fixed too.
• validateViaFile opens its stream inside the try again. A path Node refuses outright, such as one containing a NUL byte, is reported instead of thrown.

No other behavior changes. Prompt text and order are the same, and a new test pins both version messages.

Decided in review

• The gitignore/--destination gap is deferred to its own ticket (plan §5.2, step 9). plugin generate --destination can write to a directory .gitignore doesn't list, and the git init that plugin publish then prints would nest one repository inside another. It isn't a regression, since main has no .gitignore handling at all, and the fix changes behavior, so it needs its own design.
• The spec pruning is dropped (commit 4).
• Left as is, pre-existing on main: SdkPublishAction zips outputDirectory/<language>, re-deriving SdkContext's layout, while a versioned project writes its SDK one level deeper.

Test plan

• pnpm build
• pnpm lint
• pnpm test: 1389 passing, 0 failing (38 pending, unchanged)
• APIMATIC_E2E=1 portal build: 37 passing, two real Vite builds on the moved fixtures
• Smoke: plugin publish --input <fixture> and sdk generate --input … --destination <src> resolve the project as before

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.7% 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 📦🚀