feat(sdk)!: retire v3 generation and let a publish record itself

.ai/plans/apimatic-config.md

@@ -151,6 +151,8 @@ Rejected:
   bundled SDK.
   `codegenVersion` stays, inside `publishing`, because the mismatch check
   in `PluginConfig.assertNoCodegenVersionMismatch` depends on it.
+  *(Superseded: the service decides the generator, so the field and its check
+  both left in the v3 retirement. An older file keeps it; nothing reads it.)*
   `packageConfiguration` and `source.repositoryType` from the design sketch are
   not modelled in this release. A hand-written file carrying `packageConfiguration`
   keeps it, because unknown fields in these blocks are preserved. A hand-written

.ai/plans/portal-config.md

@@ -550,8 +550,9 @@ Following `.ai/instructions.md` and the skills in `.ai/skills/`.
   `"typescript": {}` section 12 recommends validates. Inside `publishing`,
   `source`, `package` (per language, as `plugin-config.ts` types them) and
   `codegenVersion` (`v3`, `v4`) are typed and none is required, matching the
-  plugin path's leniency: `assertNoCodegenVersionMismatch` already reads a
-  missing `codegenVersion` as no mismatch. `languages` is optional in the schema: the "at least one"
+  plugin path's leniency: the mismatch check then read a missing
+  `codegenVersion` as no mismatch. *(Superseded: `codegenVersion` and its
+  check have both since left; the field is no longer typed in the schema.)* `languages` is optional in the schema: the "at least one"
   rule is the portal command's, and a file `sdk publish` alone created is
   valid. The `$schema` URL
   is `https://cdn.jsdelivr.net/npm/@apimatic/cli@2/apimatic.schema.json`.
@@ -745,8 +746,8 @@ verified to build 22 pages with this branch's CLI.
   entry (`"typescript": {}`) is enough, since the portal checks only the key.
   Today a `{}` entry is inert for the plugin commands: `hasPublishedSdks` needs
   `publishing.source` or `publishing.package`, so `plugin generate` still
-  reports no published SDKs, and `assertNoCodegenVersionMismatch` skips an
-  entry with no `publishing` record.
+  reports no published SDKs. *(The mismatch check that also skipped such an
+  entry has since been removed with `codegenVersion`.)*
 - **The hand-written entry is not inert for long.** Since #350 an entry with no
   `publishing` block means "this language is wanted, nothing is published
   yet", which is the state the coming bundling change turns into an SDK

.ai/skills/action.md

@@ -93,7 +93,7 @@ Use when creating a new Action class. Choose the variant that matches the action
 ### What to determine
 
 1. **Topic** — action group folder (e.g., `api`, `sdk`, `portal`). Can be nested: `sdk/publish`, `publishing/profile`
-2. **Action name** — file name, lowercase hyphenated (e.g., `validate`, `generate`, `save-changes`)
+2. **Action name** — file name, lowercase hyphenated (e.g., `validate`, `generate`, `record-sdk`)
 3. **Class name** — PascalCase with `Action` suffix (e.g., `ValidateAction`, `PortalNewTocAction`)
 4. **Variant** — one of:
    - `standard` — full constructor with configDir, commandMetadata, authKey; services, withDirPath, prompts

.ai/skills/event.md

@@ -7,7 +7,7 @@ Domain events live at `src/types/events/` and represent something that **already
 ### Naming
 
 - **Class name must be past tense** — the event describes something that occurred: `QuickstartCompleted`, `SdkChangesSaved`, `SdkConflictsResolved`. Never present tense (`SdkSaveChanges`) or imperative (`SaveChanges`).
-- **File name** — lowercase hyphenated, matching the class name: `quickstart-completed.ts`, `sdk-changes-saved.ts`.
+- **File name** — lowercase hyphenated, matching the class name: `quickstart-completed.ts`, `sdk-publish-validation-failed.ts`.
 - **Class name suffix** — always `Event`: `QuickstartCompletedEvent`, `SdkChangesSavedEvent`.
 
 ### Structure
@@ -102,9 +102,7 @@ export class {PascalName}Event extends DomainEvent {
 |---|---|
 | Self-contained success event (no payload) | `src/types/events/quickstart-completed.ts` |
 | Self-contained initiation event (no payload) | `src/types/events/quickstart-initiated.ts` |
-| Success event with payload (`language`) | `src/types/events/sdk-changes-saved.ts` |
-| Success event with payload (`language`) | `src/types/events/sdk-conflicts-resolved.ts` |
 | Failure event (dynamic message + flags) | `src/types/events/sdk-publish-validation-failed.ts` |
 | DomainEvent base class | `src/types/events/domain-event.ts` |
 | Firing from Command (success + failure) | `src/commands/quickstart.ts` |
-| Firing from Command (failure only) | `src/commands/sdk/save-changes.ts` |
+| Firing from Command (failure only) | `src/commands/sdk/publish.ts` |

.ai/skills/prompt.md

@@ -81,7 +81,7 @@ Use when creating a new Prompts class. Choose the variant that matches the comma
 ### What to determine
 
 1. **Topic** — folder path matching the action (e.g., `auth`, `api`, `sdk`, `portal`, `sdk/publish`)
-2. **Name** — file name, lowercase hyphenated (e.g., `login`, `generate`, `save-changes`)
+2. **Name** — file name, lowercase hyphenated (e.g., `login`, `generate`, `record-sdk`)
 3. **Class name** — PascalCase with `Prompts` suffix (e.g., `LoginPrompts`, `SdkGeneratePrompts`)
 4. **Variant** — one of:
    - `simple` — log methods and optional spinner; no interactive prompts

README.md

@@ -82,7 +82,6 @@ USAGE
 * [`apimatic quickstart`](#apimatic-quickstart)
 * [`apimatic sdk generate`](#apimatic-sdk-generate)
 * [`apimatic sdk publish`](#apimatic-sdk-publish)
-* [`apimatic sdk save-changes`](#apimatic-sdk-save-changes)
 
 ## `apimatic api transform`
 
@@ -426,9 +425,8 @@ Generate an SDK for your API
 
 ```
 USAGE
-  $ apimatic sdk generate -l csharp|java|php|python|ruby|typescript|go [-d <value>] [--skip-changes]
-    [--api-version <value>] [--zip] [--track-changes] [--codegen-version v3|v4] [--stability stable|beta] [-i <value>]
-    [-f] [-k <value>]
+  $ apimatic sdk generate -l csharp|java|php|python|ruby|typescript|go [-d <value>] [--api-version <value>]
+    [--zip] [--codegen-version v4] [--stability stable|beta] [-i <value>] [-f] [-k <value>]
 
 FLAGS
   -d, --destination=<value>       [default: <input>/sdk/<language> | <input>/sdk/<api-version>/<language>] path where
@@ -440,22 +438,20 @@ FLAGS
   -l, --language=<option>         (required) Programming language for SDK generation
                                   <options: csharp|java|php|python|ruby|typescript|go>
       --api-version=<value>       Version of the API to use for SDK generation (if multiple versions exist)
-      --codegen-version=<option>  [default: v3] Version of the code generator to use
-                                  <options: v3|v4>
-      --skip-changes              Do not apply the saved changes to the generated SDK
-      --stability=<option>        [default: stable] Stability level of the generated SDK
+      --codegen-version=<option>  [default: v4] Version of the code generator to use
+                                  <options: v4>
+      --stability=<option>        Stability level of the generated SDK. Defaults to the level the language offers.
                                   <options: stable|beta>
-      --track-changes             Enable change tracking for SDK generation (only required for initial setup)
       --zip                       Download the generated SDK as a .zip archive
 
 DESCRIPTION
   Generate an SDK for your API
 
-  Generate Software Development Kits (SDKs) from API specifications.
-  Supports multiple programming languages including Java, C#, Python, JavaScript, and more.
+  Generate a Software Development Kit (SDK) from an API specification.
+  C#, TypeScript and Python are available; Java, Ruby, Go and PHP are on their way.
 
 EXAMPLES
-  apimatic sdk generate --language=java
+  apimatic sdk generate --language=typescript
 
   apimatic sdk generate --language=csharp --input=./
 
@@ -470,29 +466,27 @@ Generate and publish an SDK to a package registry and/or source repository
 
 ```
 USAGE
-  $ apimatic sdk publish [-p <value>] [-v <value>] [-d <value>] [-l csharp|java|php|python|ruby|typescript] [-f]
-    [-i <value>] [--publish-type package|sourcecode...] [--dry-run] [--codegen-version v3|v4] [--stability stable|beta]
-    [--update-plugin-config]
+  $ apimatic sdk publish [-p <value>] [-v <value>] [-d <value>] [-l csharp|java|php|python|ruby|typescript|go]
+    [-f] [-i <value>] [--publish-type package|sourcecode...] [--dry-run] [--codegen-version v4] [--stability
+    stable|beta]
 
 FLAGS
   -d, --destination=<value>       [default: <input>/sdk] path where the sdk will be generated.
   -f, --force                     overwrite changes without asking for user consent.
   -i, --input=<value>             [default: ./] path to the parent directory containing the 'src' directory, which
                                   includes API specifications and configuration files.
   -l, --language=<option>         Language of the SDK to generate and publish.
-                                  <options: csharp|java|php|python|ruby|typescript>
+                                  <options: csharp|java|php|python|ruby|typescript|go>
   -p, --profile-id=<value>        Id of the publishing profile to use.
   -v, --version=<value>           Semantic version of the SDK to publish (e.g. 1.0.0).
-      --codegen-version=<option>  [default: v3] Version of the code generator to use
-                                  <options: v3|v4>
+      --codegen-version=<option>  [default: v4] Version of the code generator to use
+                                  <options: v4>
       --dry-run                   Generate the SDK locally for review without publishing.
       --publish-type=<option>...  One or more publishing targets: 'package' for a package registry, 'sourcecode' for a
                                   git repository.
                                   <options: package|sourcecode>
-      --stability=<option>        [default: stable] Stability level of the generated SDK
+      --stability=<option>        Stability level of the generated SDK. Defaults to the level the language offers.
                                   <options: stable|beta>
-      --update-plugin-config      Record the published SDK in 'src/apimatic.json', creating the file if it does not
-                                  exist. Interactive runs are asked instead.
 
 DESCRIPTION
   Generate and publish an SDK to a package registry and/or source repository
@@ -506,44 +500,10 @@ EXAMPLES
 
   apimatic sdk publish --profile-id=a1b2c3d4e5f6a1b2c3d4e5f6 --language=typescript --version=1.0.0 --publish-type=package --publish-type=sourcecode
 
-  apimatic sdk publish --profile-id=b2c3d4e5f6a1b2c3d4e5f6a1 --language=java --version=2.0.0 --publish-type=sourcecode
+  apimatic sdk publish --profile-id=b2c3d4e5f6a1b2c3d4e5f6a1 --language=csharp --version=2.0.0 --publish-type=sourcecode
 
   apimatic sdk publish --profile-id=c3d4e5f6a1b2c3d4e5f6a1b2 --language=python --version=1.0.0 --publish-type=package --dry-run
-
-  apimatic sdk publish --profile-id=d4e5f6a1b2c3d4e5f6a1b2c3 --language=csharp --version=1.0.0 --publish-type=package --codegen-version=v4 --stability=beta
 ```
 
 _See code: [src/commands/sdk/publish.ts](https://github.com/apimatic/apimatic-cli/blob/v1.3.1/src/commands/sdk/publish.ts)_
-
-## `apimatic sdk save-changes`
-
-Save customizations made to an auto-generated SDK
-
-```
-USAGE
-  $ apimatic sdk save-changes -l csharp|java|php|python|ruby|typescript|go [--sdk <value>] [--api-version <value>] [-i
-    <value>]
-
-FLAGS
-  -i, --input=<value>        [default: ./] path to the parent directory containing the 'src' directory, which includes
-                             API specifications and configuration files.
-  -l, --language=<option>    (required) Programming language of the SDK
-                             <options: csharp|java|php|python|ruby|typescript|go>
-      --api-version=<value>  Version of the API where changes should be saved (if multiple versions exist).
-      --sdk=<value>          [default: ./sdk/<language> | ./sdk/<api-version>/<language>] path to the folder containing
-                             the updated SDK.
-
-DESCRIPTION
-  Save customizations made to an auto-generated SDK
-
-  Requires an input directory with API specifications, a path to the updated SDK directory, and the programming
-  language.
-
-EXAMPLES
-  apimatic sdk save-changes --language=csharp
-
-  apimatic sdk save-changes --language=java --sdk=./sdk
-```
-
-_See code: [src/commands/sdk/save-changes.ts](https://github.com/apimatic/apimatic-cli/blob/v1.3.1/src/commands/sdk/save-changes.ts)_
 <!-- commandsstop -->

apimatic.schema.json

@@ -262,7 +262,7 @@
       "properties": {
         "publishing": {
           "type": "object",
-          "description": "Where the SDK is published, and which generator produced it.",
+          "description": "Where the SDK is published.",
           "additionalProperties": true,
           "properties": {
             "source": {
@@ -279,9 +279,6 @@
             },
             "package": {
               "type": "object"
-            },
-            "codegenVersion": {
-              "enum": ["v3", "v4"]
             }
           }
         }