Apimatic plugin generate

[MuHamza30]

Add apimatic plugin generate and the pluginconfig.json lifecycle

Prerequisite: #311 (v4 codegen support in apimatic sdk publish).
Languages.<lang>.version records the codegen version an SDK was published with. While
sdk publish hardcodes CodeGenerationVersion.V3, that field can only ever be "v3", so a
v4 plugin is unreachable — a plugin cannot reference a v4 SDK that was never published as
v4. #311 adds --codegen-version (and --stability) to sdk publish and threads both through to
GenerateAction. A4 depends on it directly; A1, A2 and A3 do not and can proceed in parallel.

The dependency is on #311's PR 1 (non-interactive) only. #311 ships in two PRs — PR 1 threads
the flags through the non-interactive path, PR 2 adds a codegen prompt to the interactive wizard.
A4 is itself non-interactive-only (see Deferred), so it never reads a codegen version from the
wizard. A4 is unblocked the moment PR 1 lands; #311 PR 2 proceeds in parallel with the rest of
this issue.

Summary

Introduce a new command, apimatic plugin generate, that produces a plugin/ directory the
same way apimatic sdk generate produces sdk/ and apimatic portal generate produces
portal/. The command's input is not the src/ build directory but a new config file,
src/pluginconfig.json, which is sent to APIMatic; the CLI then polls for completion and
unpacks the returned artifacts into the plugin directory.

The distinguishing feature of this work is that pluginconfig.json is assembled across two
commands. plugin generate owns the plugin's identity (id, name, Copilot key, language
selection); sdk publish owns each language's publishing details (source repository, package
identity, codegen version). Either command may create the file; each fills in the parts it owns
and leaves the rest alone. plugin generate only performs a generation once the file is
complete — otherwise it writes what it can and directs the user to sdk publish.

Background

• apimatic sdk publish already resolves a publishing profile and publishes to a package
  registry and/or a git repository. It knows, per language, the package identity and the git
  repository/branch. Today it discards that knowledge after the run.
• apimatic portal copilot already resolves an API Copilot key from
  SubscriptionInfo.ApiCopilotKeys and writes it into APIMATIC-BUILD.json. The plugin config
  needs the same key under a different name (pluginKey), so that resolution logic is reused.
• Contents of the generated plugin/ directory are produced server-side and are out of scope
  here.

The config file

Path: src/pluginconfig.json — inside the build directory, alongside APIMATIC-BUILD.json.

{
  "schemaVersion": 1,
  "pluginId": "acme-payments",
  "pluginName": "Acme Payments",
  "pluginVersion": "0.1.0",
  "pluginKey": "8f3a91c2-4b7e-11ef-9c3d-0242ac120002",
  "author": { "name": "Acme", "email": "developers@acme.com" },
  "license": "MIT",
  "Languages": {
    "python": {
      "source":  { "repository": "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/acme/acme-python", "branch": "main" },
      "package": { "packageId": "acme-checkout-sdk", "registry": "pypi" },
      "version": "v3"
    },
    "csharp": {
      "source":  { "repository": "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/acme/acme-csharp", "branch": "main" },
      "package": { "packageId": "Acme.Checkout.Sdk", "registry": "nuget" },
      "version": "v4"
    }
  }
}

Field ownership

Field	Written by	Source	Required
schemaVersion	whichever command creates the file	constant 1	yes
pluginId	plugin generate	prompted (or --plugin-id)	yes
pluginName	plugin generate	prompted (or --plugin-name)	no
pluginVersion	creator	default 0.1.0	no
pluginKey	plugin generate	SubscriptionInfo.ApiCopilotKeys	yes
author	creator	account info (FullName, Email)	no
license	—	not written by the CLI	no
Languages.<lang> (key)	plugin generate (multiselect) or sdk publish (the language it published)		yes, ≥1
Languages.<lang>.source	sdk publish	profile git config	yes
Languages.<lang>.package	sdk publish	profile package config	yes
Languages.<lang>.version	sdk publish	codegen version	yes

A config is complete when pluginId, pluginKey, and at least one language are present,
and every language entry has source, package and version.

---

Flows

Flow 1 — plugin-first

apimatic auth login
apimatic plugin generate

1. No pluginconfig.json, or one missing plugin-level fields.
2. Prompt for pluginId (required) and pluginName (optional, skippable).
3. Resolve the API Copilot key → pluginKey.
4. Multiselect languages → create Languages entries with source/package/version absent.
5. Write the file.
6. Config is incomplete → print next steps naming apimatic sdk publish → exit 130.

apimatic sdk publish …        # fills source + package + version for the published language
apimatic plugin generate      # now complete → generates

Flow 2 — publish-first

apimatic auth login
apimatic sdk publish …

1. No pluginconfig.json → sdk publish creates one.
2. Adds/updates the Languages entry for the language it published, with source, package
   and version filled.
3. Plugin-level fields (pluginId, pluginKey) remain absent.

apimatic plugin generate

4. Prompts for pluginId/pluginName, resolves pluginKey.
5. Languages is already populated and complete → does not prompt for languages.
6. Generates.

Notes on both flows

• sdk publish handles one language per invocation, so Languages accumulates over
  repeated runs. Re-publishing an existing language overwrites that entry only.
• If the user has no publishing profile, sdk publish behaves exactly as it does today
  (directing them to create one in the App). No change.
• The two flows converge on the same file; neither command clobbers fields it doesn't own.

---

Scope

A1 — Config model and context (unblocked)

• src/types/plugin/plugin-config.ts — PluginConfig rich class mirroring BuildConfig:
  static parse(content), static createEmpty(), immutable with* methods
  (withIdentity, withPluginKey, withLanguages, withLanguagePublishing), and
  predicates (isComplete(), missingLanguages(): Language[], hasLanguages(),
  getPluginId()).
• src/types/plugin/plugin-id.ts — PluginId value object following ProfileId:
  private field, static tryCreate(value): Result<PluginId, string>, isEqual, toString.
• src/types/plugin-config-context.ts — PluginConfigContext, constructed with the
  build directory (like BuildContext). Derives pluginconfig.json internally as a
  private get. Public surface is behavioural only:
  exists(), read(), save(config), isComplete(), missingLanguages().
  Reads must tolerate a missing file by returning an empty config.

A2 — plugin generate command triple (unblocked apart from the API call)

• src/commands/plugin/generate.ts — export default class PluginGenerate extends Command
  - flags: --plugin-id, --plugin-name, --language (multiple), then
  ...FlagsProvider.input → ...FlagsProvider.destination("plugin", "plugin") →
  ...FlagsProvider.force → ...FlagsProvider.authKey (last)
  - static readonly cmdTxt = format.cmd("apimatic", "plugin", "generate")
  - run(): parse → type-convert → CommandMetadata → intro("Generate Plugin") →
  action.execute(...) → outro(result)
  - default destination <input>/plugin
• src/actions/plugin/generate.ts — PluginGenerateAction, standard variant
  (configDir, commandMetadata, authKey: string | null = null)
• src/prompts/plugin/generate.ts — PluginGeneratePrompts

A3 — Plugin generation service (scaffold; blocked on API contract)

• src/infrastructure/services/plugin-service.ts — PluginService, modelled on
  PortalService.generatePortal: submit → poll every 3s → map Failed /
  ValidationError / SubscriptionError onto ServiceError → download → Result.
• Endpoint, request encoding and response shape are not yet defined. Implement against
  the portal-generation shape and keep the URL in a single as const constant with a
  TODO so it is a one-line change later.

A4 — sdk publish write hook (blocked on #311, plus open questions)

• After a successful publish, write the language entry into src/pluginconfig.json,
  creating the file if absent.
• Non-interactive path only for now (see Deferred).
• version ← the codegen version actually used for the run, i.e. the value threaded from
  --codegen-version by Implementation: v4 codegen support in apimatic sdk publish #311. Do not hardcode "v3". Landing A4 before Implementation: v4 codegen support in apimatic sdk publish #311 would bake
  in a constant that makes v4 plugins unreachable, which is the whole reason Implementation: v4 codegen support in apimatic sdk publish #311 is a
  prerequisite rather than a follow-up.
• source.repository ← https://github.com/${repositoryName}, source.branch ←
  branch, both from the profile's GitConfiguration. Isolate the URL construction in
  one named function — it hardcodes GitHub and will need revisiting for other hosts.
• package ← per-language mapper. Shape pending (see Open questions); land the mapper
  with a single language wired and the rest throwing a clear TODO until the shape is
  confirmed.
• A language published with --publish-type sourcecode only has no package config, and
  vice versa. Such an entry is incomplete and will block plugin generate until the
  other half is published.

---

Behaviour matrix — plugin generate

#	Precondition	Behaviour	Exit
1	Not logged in	unauthorizedWithHint message	1
2	No config file	create it, prompt id/name, resolve key, multiselect languages, write, redirect to sdk publish	130
3	Config exists, no pluginId	prompt for it, write	continues
4	Config exists, no pluginKey	resolve Copilot key, write	continues
5	Config exists, Languages empty	multiselect languages, write, redirect	130
6	Config exists, Languages populated	do not prompt for languages	continues
7	One or more languages missing source/package/version	name the incomplete languages, redirect to sdk publish	130
8	Account has zero Copilot keys	error, direct to support (same message as portal copilot)	1
9	Account has one Copilot key	use it; confirm unless --force	continues
10	Account has many Copilot keys	select prompt	continues
11	Config complete, plugin dir non-empty, no --force	confirm overwrite; decline → Please enter a different destination folder…	130
12	Config complete	submit, poll, unpack into <destination>, report path	0
13	Generation service error	surface ServiceError message	1
14	Any prompt cancelled (Ctrl+C)	specific message per step	130

Adopted defaults (flag now if any is wrong)

• Incomplete config exits 130 (cancelled) — the command did useful work but generated
  nothing; failed overstates it and success would mislead CI.
• Copilot key resolution mirrors portal copilot exactly, including the
  "only active on one Portal at a time" caution and the support-contact message on zero keys.
• An existing pluginKey in the config is trusted — not re-prompted, not re-validated.
• Partial languages block the whole run rather than generating a subset.
• author auto-filled from account info (already fetched for the Copilot key, so free).
• license never written by the CLI.
• pluginVersion defaults to 0.1.0 on creation and is never auto-bumped.
• schemaVersion written as 1 on creation, never prompted.

---

Open questions

Blocking sub-parts of A3/A4 only; A1 and A2 can proceed.

1. repositoryName format. Is it owner/repo or the bare repo name? GitConfiguration
   carries { isEnabled, credentialsId, repositoryName, branch } — no host, no owner. If it is
   bare, the owner lives with the credentials server-side and source.repository cannot be
   constructed; we would need sourceUrl from the publish log instead.
2. package object shape per registry — to be supplied. The sample uses
   { packageId, registry }, but package identity differs by language: C# packageId,
   Python/Ruby/TypeScript name, Go packageName, Java groupId + artifactId,
   PHP vendorName + projectName. Also confirm the exact registry strings
   (pypi, nuget, npm, maven, packagist, rubygems, and Go).
3. Languages capitalisation. Every other key is camelCase; the sample uses a capital L.
   Confirm this is the real wire format — a mismatch here fails server-side, not locally.
4. Plugin generation API contract — endpoint, request encoding (multipart, as the other
   generators use, or JSON?), whether the whole src/ build is uploaded or only
   pluginconfig.json, poll endpoint, terminal statuses, response body.
5. Does sdk publish write the plugin config unconditionally? This is a behaviour change
   on a shipped command: a user publishing an SDK with no interest in plugins would find a new
   src/pluginconfig.json in their repo. Alternatives: only update when the file already
   exists, or gate behind a --plugin flag. Flow 2 implies unconditional.

---

Deferred / follow-ups

• Interactive sdk publish does not update the plugin config. Interactive mode never polls
  the publish log — it prints the log URL and exits as soon as publishing is initiated. Only
  the non-interactive path runs to completion. Explicitly out of scope for now.
• v4 publishing support — tracked separately. No longer deferred — promoted to a
  prerequisite, Implementation: v4 codegen support in apimatic sdk publish #311. The earlier scoping treated this as an optional follow-up with
  Languages.<lang>.version pinned to "v3" in the meantime. That was wrong: a v4 plugin
  cannot exist unless a v4 SDK can be published, so pinning the field would have shipped a
  schema whose v4 case was permanently unreachable. Implementation: v4 codegen support in apimatic sdk publish #311 covers the flag and the threading;
  of the three gaps originally listed here, its current state resolves the first two and leaves
  the third open:
  1. generateV4Sdk(buildPath, language, stability, configDir, commandMetadata, authKey) takes
     no packageVersion, while the v3 generateSdk does. Confirmed to be a real defect, not
     a redundancy: the CLI's publish endpoint (POST /publish/{profileId}/{language} →
     PublishGeneratedSdk) uploads the SDK zip verbatim and never calls the transforming
     GeneratePublishReadySdk path, and the worker packs the generated project file unmodified
     (dotnet pack /sdk/*.Standard/*.Standard.csproj, no version override). So the published version
     is whatever the generator baked in; --version reaches only the publish log, the tracking event
     and the constructed package URL. v3 is correct today solely because the CLI passes the version
     to the generator (portal-service.ts:133). The fix belongs in Implementation: v4 codegen support in apimatic sdk publish #311 — send the version to the v4
     endpoint as v3 does; a TODO marks the call site until the generated client exposes the
     parameter.
  2. The v4 branch returns before MergeSourceTreeAction, so SDK customizations are silently
     skipped. Implementation: v4 codegen support in apimatic sdk publish #311 accepts this as a documented known limitation of the v4 path and adds no
     guard; the warning sdkCustomizationsNotSupportedForV4() surfaces during publish.
  3. Confirmed: the v4 generator does not consume package-settings/ at all. The CLI does
     ship it on the v4 path — getBuildZipPath(tempDirectory, packageSettingsDirectory) is called
     at generate.ts:106, before the v4/v3 branch — but the generator ignores it, and per (1)
     publishing does not compensate. The file carries package identity only, not the version
     (package-settings-context.ts:17-22), so a v4 publish gets both the wrong package name and the
     wrong version, from two independent causes. This half needs a generator-side fix and is not
     resolvable in the CLI.
• sdk quickstart is v3-only (actions/sdk/quickstart.ts:204, hardcoded V3 + STABLE).
  Not changed here. portal quickstart does not generate SDKs at all.

---

Acceptance criteria

• apimatic plugin generate appears in --help under a plugin topic, space-separated.
• Running it with no pluginconfig.json creates src/pluginconfig.json containing
  schemaVersion, pluginId, pluginKey, author, pluginVersion and the selected
  languages as empty entries, then exits 130 with next steps naming apimatic sdk publish.
• Running it again after sdk publish has filled a language does not re-prompt for
  languages and proceeds to generation.
• Generation writes artifacts into <input>/plugin by default and honours --destination.
• The overwrite guard behaves as in portal generate / sdk generate.
• sdk publish (non-interactive) adds or updates exactly one language entry and leaves all
  plugin-level fields untouched.
• Neither command discards fields written by the other; round-tripping the file is lossless.
• All output goes through the Prompts layer; no console.log; no raw string paths.
• Exit codes: 0 success, 1 failure, 130 cancelled/incomplete.

Testing

Mirroring source paths under test/:

• test/types/plugin-config-context.test.ts — create/read/merge/save, missing file, malformed
  JSON, completeness and missingLanguages() across partial states (use mock-fs).
• test/actions/plugin/generate.test.ts — the behaviour matrix above; stub the service with
  sinon, assert ActionResult variants and the written config.
• test/commands/plugin/generate.test.ts — flag parsing, defaults, interactive/non-interactive
  split.
• test/actions/sdk/publish/non-interactive.test.ts — extend for the config write hook,
  including round-trip preservation of plugin-level fields.
• nock for the generation and polling endpoints once the contract is known.

Conventions

Follow .ai/instructions.md and the skills in .ai/skills/:
command.md (Command + Action + Prompts triple), action.md, prompt.md,
context.md (no public path getters; behavioural methods only), value-object.md
(PluginId), and service.md (PluginService returning Result<T, ServiceError>).

[MuHamza30]

Flags — apimatic plugin generate

Flag	Short	Type	Default	Description
--input	-i	string	./	Path to the parent directory containing the src directory, which includes API specifications and configuration files.
--destination	-d	string	<input>/plugin	Path where the plugin will be generated.
--force	-f	boolean	false	Overwrite changes without asking for user consent.
--auth-key	-k	string	—	Override current authentication state with an authentication key.

No new flags are added to apimatic sdk publish. Updating pluginconfig.json after a
successful publish is automatic.

---

Prompts

Prompt	Type	Message	Placeholder	When it appears	On Ctrl+C
Plugin id	text	Enter an id for your plugin:	acme-payments	Only when pluginconfig.json has no plugin id yet.	Command exits as cancelled
Overwrite	confirm	The destination `'./plugin'` is not empty, do you want to overwrite?	defaults to No	Only when the destination directory is non-empty and --force was not passed.	Treated as "No"

---

Spinners

Stage	In progress	Success	Failure
Account lookup	Fetching account information	Account information retrieved.	Failed to fetch account information.
Generation	Generating Plugin	Plugin generated successfully.	Plugin generation failed.

The account lookup only runs when the plugin key is missing from the config — it is skipped
on subsequent runs.

---

Messages

Errors

When	Message
src and destination resolve to the same directory	The 'src' and 'plugin' directories must be different. Current value: '<path>'
src is missing or has no APIMATIC-BUILD.json	The 'src' directory is either empty or invalid: '<path>'
pluginconfig.json exists but is not valid JSON	'pluginconfig.json' could not be read: <reason>. Fix or delete the file at '<path>' and try again.
The plugin id prompt was cancelled	A plugin id is required to generate a plugin.
Account lookup failed (401 / 403 / network / server)	(the resolved service error message — same text portal generate shows for the same failure)
Subscription has no API Copilot key	No API Copilot key was found on your subscription. A plugin requires one.
pluginconfig.json has no published languages	No published SDKs were found in 'pluginconfig.json'.
Destination not empty and overwrite declined	Please enter a different destination folder or remove the existing files and try again.
Generation failed (validation, subscription, server)	(the resolved service error message — identical handling to portal generate)
Generation failed with a downloadable report	An error occurred during plugin generation. A report has been written at the destination path '<path>'

Info

When	Message
Config file created by this command	Created '<path>/pluginconfig.json'.
Config file updated by this command	Updated '<path>/pluginconfig.json'.
Generation succeeded	Plugin artifacts can be found at '<path>'.

"Next Steps" note

Shown when pluginconfig.json has no published languages yet — the most common first-run
outcome, since a plugin cannot be generated until at least one SDK has been published.

─ Next Steps ────────────────────────────────────────────────

Publish an SDK for each language you want a plugin for:

  apimatic sdk publish --language <language>

Each successful publish records that language in 'pluginconfig.json'.
Once at least one language is recorded, re-run:

  apimatic plugin generate

---

New messages on apimatic sdk publish

After a successful publish, sdk publish records the published language in
src/pluginconfig.json, creating the file if it does not exist. One of these two messages
is shown. Neither appears on a --dry-run, since nothing was actually published.

When	Level	Message
The config file did not exist and was created	info	Created 'pluginconfig.json' and recorded the published <language> SDK.
The config file already existed	info	Recorded the published <language> SDK in 'pluginconfig.json'.

Only what was actually published is recorded: a --publish-type=sourcecode run writes the
source repository and branch, a --publish-type=package run writes the package id and
registry, and running both over time merges into a single complete entry for that language.

[sohaibtariq]

Spinners

Account lookup — this call already has one label in portal/copilot.ts, auth/status.ts and auth/login.ts.

- Fetching account information / Account information retrieved. / Failed to fetch account information.
+ Retrieving your subscription info / Subscription info retrieved / Subscription info retrieval failed

Generation — matches Generating API Portal.

- Generating Plugin
+ Generating Context Plugin

Success and failure strings are fine as written.

Prompt

Plugin ID — ID is uppercase everywhere else (Copilot ID:, Select the ID for the API Copilot…, the ID column in profile/list.ts).

- Enter an id for your plugin:
+ Enter an ID for your plugin:

Row label becomes "Plugin ID" too.

Errors

Plugin ID prompt cancelled — cancels are log.warn and use the "Exiting without…" shape.

- (error) A plugin id is required to generate a plugin.
+ (warn)  A plugin ID is required. Exiting without generating a plugin.

No API Copilot key — reuse the existing string; it comes free with the shared selectCopilotKey helper. The current one leaves the user with no way forward.

- No API Copilot key was found on your subscription. A plugin requires one.
+ No copilot key found for the current subscription. Please contact support at 'support@apimatic.io'.

No published SDKs — active voice, and the file holds SDK coordinates rather than SDKs.

- No published SDKs were found in 'pluginconfig.json'.
+ 'plugin-config.json' has no published SDKs yet.

Malformed config — names the file and its path twice.

- 'pluginconfig.json' could not be read: <reason>. Fix or delete the file at '<path>' and try again.
+ 'plugin-config.json' could not be read: <reason>. Fix or delete it at '<path>' and try again.

Next Steps

Commands are wrapped as '${f.cmdAlt(...)}' everywhere, and flags render through f.flag() with an =.

-   apimatic sdk publish --language <language>
-   apimatic plugin generate
+   'apimatic sdk publish --language=<language>'
+   'apimatic plugin generate'

Filename

It's plugin-config.json, not pluginconfig.json — also in the Info messages, the sdk publish messages and the Next Steps note.

[MuHamza30]

apimatic plugin generate — CLI implementation plan

Context

APIMatic is adding a Claude Code context plugin artifact: a bundle of skills and agents that teaches an AI
coding assistant how to use a customer's SDKs. Issue
#2190 defines the experience; the CLI uploads a build
zip, a codegen backend produces the plugin zip, and the CLI polls until it can download it.

The work spans three repos. This plan covers the apimatic-cli slice only (Hamza), written against the
contracts already implemented on the other two branches:

Repo	Branch	Owner	State
apimatic-cli	(new, from dev)	Hamza	not started — this plan
apimatic-io	feat/context-plugin-standalone-gen	Mahnoor	3 routes implemented (111bafec9)
codegen-v2	sohail/context-plugin-generate	Sohail	functions, validator and renderers implemented

Two user journeys:

1. apimatic plugin generate — creates src/plugin-config.json with metadata if absent, otherwise
   uploads the build and downloads the generated plugin into plugin/.
2. apimatic sdk publish — after a successful publish, offers to record that language into
   src/plugin-config.json, so the config accretes languages instead of being written speculatively.

A hand-written plugin-config.json must work unchanged.

---

1. Verified wire contract

Traced end-to-end; this is the section to share with Mahnoor, Sohail and Rafay for sign-off.

CLI ──► apimatic-io (api.apimatic.io)  ──►  codegen-v2 (func-codegenv4)
        thin forwarder                      durable orchestration
        owns 401 + 400(zip) + 403           owns everything else

CLI call	io route	Backend route
POST /plugin?origin=<cmd> multipart file	api/plugin	api/context-plugins/generate
GET /plugin/{id}/status	api/plugin/{id}/status	api/context-plugins/generate/{id}/status
GET /plugin/{id}/download	api/plugin/{id}/download	api/context-plugins/generate/{id}/download

Sources: apimatic-io/.../APIControllers/ContextPlugin/ContextPluginApiController.cs,
apimatic-io/docs/context-plugin-io-plan.md, codegen-v2/src/CodegenV2.Func/Functions/ContextPlugin/*.cs.

1.1 Differences from portal generate — these drive the design

	portal generate	plugin generate
Completion signal	302 redirect to download	{"status":"Completed"} — no redirect
Status vocabulary	Completed / InProgress / ValidationError / SubscriptionError / Failed	Queued / ExecutionStarted / GeneratingArtifacts / Completed / Failed / ValidationError / Unknown
SubscriptionError status	yes	no — entitlement is a 403 on POST instead
Partial-success signal	none	deferred[] — languages skipped, generation still Completed
Poll timeout	none (infinite)	5 minutes, per the io plan
Transport	@apimatic/sdk controller	raw axios (SDK not regenerated yet)

The installed @apimatic/sdk Status enum (node_modules/@apimatic/sdk/dist/cjs/models/status.js) does
not contain the four new values, so the CLI defines its own status type rather than reusing Status.

1.2 Status response

GET /plugin/{id}/status  ->  200
{
  "status": "GeneratingArtifacts",
  "errors":   { "pluginConfig": ["'plugin-config.json' was not found beside the spec directory"] },  // optional
  "deferred": [ { "language": "python", "reason": "NoPluginGenerator" } ]                            // optional
}

Terminal: Completed (→ download), Failed, ValidationError, Unknown.
Non-terminal: Queued, ExecutionStarted, GeneratingArtifacts.
Defined in codegen-v2/.../Domain/Models/GenerationStatus.cs and
.../Application/Features/GetGenerationStatus.cs.

1.3 Error surfaces

ProblemDetails bodies carry the specific text in detail, which
src/infrastructure/service-error.ts:72-98 ignores — it renders title plus the first message of the
first errors key.

Origin	Status	Wire body	CLI rendering
io WebApiAuthorizeAttribute	401	bare, no body	unauthorizedWithHint(null) → "Authorization has been denied… run apimatic auth login"
io controller (.cs:46-68)	400	title: "One or more validation errors occurred.", errors.file	title + "build file should be in valid zip format"
io SubscriptionManager.CanGenerateContextPlugin	403	title: "Access denied to resource.", errors[""]	title + "Context plugin generation is not allowed on your subscription"
codegen-v2 GenerateFunction	400 / 415	problem+json, relayed verbatim	mapped by handleServiceError
codegen-v2 orchestrator	200 ValidationError	errors map	all messages listed — see §6
codegen-v2 StatusFunction	404	unknown id	ServiceError.NotFound

Raise with Mahnoor: io's 401 has no problem+json body (a deliberate deviation flagged in her plan). The
CLI keys on the status code, so this is fine.

1.4 plugin-config.json — the real schema

Parsed by codegen-v2/.../Domain/Models/PluginConfig.cs, validated by
.../Domain/Validators/PluginConfigValidator.cs, located via GenerateWorkspace.GetPluginConfigPath() =
root of the extracted build zip, beside spec/ — i.e. <input>/src/plugin-config.json.

This supersedes the draft shape in the feature description. Corrections: the filename is
plugin-config.json (hyphenated); the languages key is sdkRepos, not Languages; each entry uses
sourceCode.srcCodeUrl, not source.repository; package fields are language-specific, not
{packageId, registry}.

{
  "schemaVersion": 1,                       // required, must equal 1
  "pluginId": "acme-payments",              // required, lower-kebab-case
  "pluginName": "Acme Payments",            // required, non-empty
  "pluginVersion": "0.1.0",                 // optional, three-part
  "pluginKey": "8f3a91c2-…",                // optional, non-empty when present
  "author": { "name": "Acme", "email": "developers@acme.com" },  // email validated when present
  "license": "MIT",                         // optional, non-empty when present
  "homepage": "https://…",                  // optional, absolute http(s)
  "repository": "https://…",                // optional, absolute http(s)
  "sdkRepos": {                             // required, >= 1 entry, each needs sourceCode.srcCodeUrl
    "csharp": {
      "sourceCode": { "srcCodeUrl": "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/acme/acme-csharp", "branch": "main" },
      "package":    { "packageId": "Acme.Checkout.Sdk" },
      "version":    "v3"
    }
  }
}

Per-language package shape (Domain/Models/Package.cs) and the publishing-profile field that feeds it:

Language	Required package fields	Publishing-profile source
csharp	packageId	cSharpConfiguration.packageId
typescript	name	typeScriptConfiguration.name
python	name	pythonConfiguration.name
ruby	name	rubyConfiguration.name
java	groupId, artifactId	javaConfiguration.groupId / .artifactId
php	vendorName, projectName	phpConfiguration.vendorName / .projectName
go	packageName	goConfiguration.packageName

All accept an optional packageUrl. A string shorthand is also accepted
("csharp": "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/acme/acme-csharp" expands to sourceCode.srcCodeUrl) — the CLI reads
configs that use it but always writes the canonical form.

1.5 What actually builds today

SdkLanguage.EmitsContextPlugin (codegen-v2/.../Domain/Enums/SdkLanguage.cs:42) is true for C# only;
TypeScript and Python are false, and no other language is in the enum. Any entry with version: "v3" is
deferred as TargetsV3. If nothing is buildable the run ends in ValidationError with errors.sdkRepos,
not a partial plugin.

version defaults to "v3"; Rafay's forthcoming --codegen-version v4 flag is what flips an entry to
"v4". Until a user opts into v4, every entry is legitimately deferred — so the CLI must present deferrals
clearly rather than as a failure.

---

2. Output — what lands on disk

The backend returns a single zip (Content-Disposition: attachment; filename=context-plugin.zip). The CLI
never inspects or repacks it; it streams to a temp file and then expands it into the destination.

POST /plugin ──► id ──► poll ──► GET /plugin/{id}/download  (stream)
                                        │
                        TempContext.save(stream)  ──►  <os-temp>/<uuid>
                                        │
                        PluginContext.save(tempZip, zipPlugin)
                                        │
                   ┌────────────────────┴────────────────────┐
          default (unzip)                              --zip (copy)
     <input>/plugin/**  (tree below)               <input>/plugin/plugin.zip

PluginContext.save cleans the destination first, exactly as PortalContext.save does — so a re-run never
leaves stale artifacts from a previous language set. The overwrite guard in §5 step 6 is what protects a
non-empty destination before this point.

2.1 The artifact tree

Contracted by codegen-v2/tests/CodegenV2.Func.Tests/ContextPlugin/PluginTreeContractTests.cs — the backend
asserts that nothing outside .claude-plugin/plugin.json, README.md, skills/ and agents/ is
emitted. Ten entries per buildable language; <prefix> is dotnet for C#, <slug> is the kebab-cased API
name.

plugin/
├── .claude-plugin/
│   └── plugin.json                                  "name" == pluginId
├── README.md
├── agents/
│   └── dotnet-<slug>-sdk.md
└── skills/
    ├── dotnet-integrate-<slug>/SKILL.md
    ├── dotnet-<slug>-getting-started/SKILL.md
    └── dotnet/
        ├── dotnet-authentication/SKILL.md
        ├── dotnet-calling-endpoints/SKILL.md
        ├── dotnet-client-initialization/SKILL.md
        ├── dotnet-configuration-resilience/SKILL.md
        ├── dotnet-error-handling/SKILL.md
        ├── dotnet-models/SKILL.md   (+ reference.md)
        └── dotnet-testing/SKILL.md

Every SKILL.md and every file under agents/ opens with YAML frontmatter carrying a non-empty
description — enforced by the same contract test.

Languages that were deferred contribute nothing to this tree. With version defaulting to "v3", a
first run commonly produces a C#-only tree plus a deferred[] list. That asymmetry is the single most
important thing the CLI's messaging has to make obvious, or users will read a correct result as a broken one.

---

3. CLI file map

New files unless marked. Paths mirror across commands/ ↔ actions/ ↔ prompts/.

src/commands/plugin/generate.ts               export default class PluginGenerate
src/actions/plugin/generate.ts                export class PluginGenerateAction
src/actions/plugin/record-sdk.ts              export class PluginRecordSdkAction     (sdk publish write-back)
src/prompts/plugin/generate.ts                export class PluginGeneratePrompts
src/prompts/plugin/record-sdk.ts              export class PluginRecordSdkPrompts
src/types/plugin/plugin-config.ts             PluginConfigData, SdkRepoEntry, package shapes
src/types/plugin/generation-status.ts         PluginGenerationStatus, PluginGenerationStatusResponse
src/types/plugin-config-context.ts            export class PluginConfigContext        (input variant)
src/types/plugin-context.ts                   export class PluginContext              (output variant)
src/infrastructure/services/plugin-service.ts export class PluginService              (axios-auth variant)
src/infrastructure/services/generation-polling.ts   extracted + generalised poll loop
src/types/events/plugin-generation-failed.ts  export class PluginGenerationFailedEvent

MODIFIED
package.json                                  oclif topics: add "plugin"
src/infrastructure/services/portal-service.ts import the extracted poll loop
src/types/publish/publishing-profile.ts       add getGitConfigurationForLanguage()
src/actions/sdk/publish/interactive.ts        call PluginRecordSdkAction after successful publish
src/actions/sdk/publish/non-interactive.ts    same

src/actions/plugin/, src/prompts/plugin/ and src/types/plugin/ already exist as empty directories.

---

4. Command layer — src/commands/plugin/generate.ts

Mirrors src/commands/portal/generate.ts, correcting the two deviations that file is flagged for in the
conventions doc (named export, missing readonly on statics — do not copy those).

export default class PluginGenerate extends Command {
  static readonly summary = "Generate a Claude Code context plugin for your published SDKs.";
  static readonly description = `…requires an input directory containing 'src' with a plugin-config.json…`;
  static readonly cmdTxt = format.cmd("apimatic", "plugin", "generate");
  static readonly examples = [
    PluginGenerate.cmdTxt,
    `${PluginGenerate.cmdTxt} ${format.flag("input", '"./"')} ${format.flag("destination", '"./plugin"')}`
  ];

  static flags = {
    zip: Flags.boolean({ default: false, description: "Download the generated plugin as a .zip archive" }),
    ...FlagsProvider.input,
    ...FlagsProvider.destination("plugin", "plugin"),
    ...FlagsProvider.force,
    ...FlagsProvider.authKey
  };
}

run() follows the fixed 5-step order: parse → convert to DirectoryPath (buildDirectory =
<input>/src, pluginDirectory = --destination ?? <input>/plugin) → build CommandMetadata →
intro("Generate Context Plugin") + action.execute(...) → outro(result), then a
result.mapAll(noop, trackPluginGenerationFailed, noop) telemetry tail.

Add "plugin": { "description": "Generate context plugins for AI coding assistants." } to oclif.topics in
package.json — without it the topic renders with no help text.

---

5. Action layer — src/actions/plugin/generate.ts

Standard constructor variant: (configDir, commandMetadata, authKey: string | null = null).

execute(buildDirectory, pluginDirectory, force, zipPlugin, displayMessages = true)

1  buildDirectory.isEqual(pluginDirectory)      -> prompts.directoryCannotBeSame + failed()
2  new BuildContext(buildDirectory).validate()  -> prompts.srcDirectoryEmpty     + failed()   [reused as-is]
3  const pluginConfig = new PluginConfigContext(buildDirectory)

4  if (!await pluginConfig.exists())            ── CASE 1: bootstrap ─────────────────
       account = prompts.spinnerAccountInfo(apiService.getAccountInfo(...))
       if isErr                            -> prompts.serviceError + failed()
       key = account.ApiCopilotKeys?.[0]
       if (!key)                           -> prompts.noCopilotKeyFound() + failed()
       metadata = await prompts.inputPluginMetadata(defaults)   // cancel -> prompts.pluginIdRequired() + cancelled()
       await pluginConfig.create(metadata, key, account)
       prompts.pluginConfigCreated(...) ; prompts.nextStepsPublishSdks()
       return ActionResult.success()

5  if (!await pluginConfig.hasSdkRepos())       ── CASE 3: exists but empty ──────────
       prompts.noPublishedSdks()
       prompts.nextStepsPublishSdks()
       return ActionResult.failed()

6  const pluginContext = new PluginContext(pluginDirectory)      ── CASE 2: generate ──
   if (!force && await pluginContext.exists() && !await prompts.overwritePlugin(pluginDirectory))
       prompts.pluginDirectoryNotEmpty() ; return ActionResult.cancelled()

7  return await withDirPath(async (tempDirectory) => {
       const tempContext = new TempContext(tempDirectory);
       const buildZipPath = await tempContext.zip(buildDirectory);
       const response = await prompts.generatePlugin(
         pluginService.generatePlugin(buildZipPath, configDir, commandMetadata, authKey));
       if (response.isErr()) { …see §6… ; return ActionResult.failed(); }
       const tempZip = await tempContext.save(response.value.plugin);
       await pluginContext.save(tempZip, zipPlugin);
       if (response.value.deferred.length) prompts.languagesDeferred(response.value.deferred);
       if (displayMessages) prompts.pluginGenerated(pluginDirectory);
       return ActionResult.success();
     });

Result-code rationale. Step 4 returns success() — the requested side effect (creating the config)
happened. Step 5 returns failed() — the user asked to generate and nothing can be generated. Both print
the same Next Steps note.

Why step 5 exists: an empty sdkRepos is a guaranteed backend ValidationError. Short-circuiting saves
a full upload plus a 3-second poll and produces a far better message than
'sdkRepos' must list at least one language.

displayMessages is carried for the same reason GenerateAction has it — so a future plugin quickstart
or portal serve-style caller can reuse this action quietly.

---

6. Copy deck

Applying Sohaib's review verbatim. Filename is plugin-config.json everywhere — Info messages, the
sdk publish messages and the Next Steps note included.

Spinners

Purpose	Strings	Note
Account lookup	Retrieving your subscription info / Subscription info retrieved / Subscription info retrieval failed	Already exists as spinnerAccountInfo in src/prompts/portal/copilot.ts:69 — reuse it rather than re-writing
Generation	Generating Context Plugin / Plugin generated successfully. / Plugin Generation failed.	Matches the Generating API Portal shape

Prompt

Enter an ID for your plugin:

ID is uppercase, consistent with Copilot ID: and the ID column in profile/list.ts. The summary row
label is Plugin ID too.

Errors and warnings

Condition	Level	String
Plugin ID prompt cancelled	log.warn	A plugin ID is required. Exiting without generating a plugin.
No API Copilot key	log.error	No copilot key found for the current subscription. Please contact support at 'support@apimatic.io'. — reuse noCopilotKeyFound() from portal/copilot.ts:105
No published SDKs	log.error	'plugin-config.json' has no published SDKs yet.
Malformed config	log.error	'plugin-config.json' could not be read: <reason>. Fix or delete it at '<path>' and try again.

The cancel path uses the existing "Exiting without…" shape (copilot.ts:98 — cancelled()), so a Ctrl+C is
a warning, not an error.

Next Steps

Commands wrap as '${f.cmdAlt(...)}'; flags render through f.flag(), which already emits --name=value.

noteWrapped(
  `Publish an SDK for each language you want in the plugin:\n` +
  `'${f.cmdAlt("apimatic", "sdk", "publish")}' ${f.flag("language", "<language>")}\n` +
  `Then run '${f.cmdAlt("apimatic", "plugin", "generate")}'.`,
  "Next Steps"
);

Renders as 'apimatic sdk publish --language=<language>' and 'apimatic plugin generate'.

Service-error rendering

Condition	Detection	Output
401	handleServiceError → unauthorizedWithHint	existing "run apimatic auth login" hint
400 invalid zip	ServiceError.BadRequest	title + first errors.file message
403 not entitled	ServiceError.Forbidden	title + subscription message
ValidationError + errors.pluginConfig	error.getError("pluginConfig")	dedicated block naming plugin-config.json, listing every message
ValidationError + errors.sdkRepos	error.getError("sdkRepos")	"No language in sdkRepos can be built yet" + per-language reasons + Next Steps
ValidationError, other keys	fallback	all messages flattened
Failed	ServiceError.ServerError	generic support message
Unknown	new ServiceError	Unable to determine generation status. Please try again.
5-minute timeout	new ServiceError	Plugin generation timed out after 5 minutes.
Completed + deferred[]	response.value.deferred	log.info, not an error — Skipped 'python' — has no context plugin generator.

The pluginConfig / sdkRepos split follows existing precedent: GenerateAction inspects
error.getError("sdkMergeFailed") to render a specialised message (src/actions/portal/generate.ts:62).

---

7. Contexts

src/types/plugin-config-context.ts — input variant, over the build directory

Owns the filename and location entirely; nothing else in the codebase learns that it is
plugin-config.json or that it sits beside spec/.

export class PluginConfigContext {
  private readonly fileService = new FileService();
  constructor(private readonly buildDirectory: DirectoryPath) {}
  private get configPath(): FilePath        // private — conventions forbid exposing derived paths

  public async exists(): Promise<boolean>
  public async hasSdkRepos(): Promise<boolean>
  public async read(): Promise<PluginConfigData>
  public async create(metadata, pluginKey, account): Promise<void>
  public async upsertSdkRepo(language: Language, entry: SdkRepoEntry): Promise<void>   // read-merge-write
  public async listSdkRepoLanguages(): Promise<Language[]>
}

upsertSdkRepo merges rather than overwrites, so publishing a second language never drops the first and a
hand-written config keeps its unknown fields (JSON.parse → mutate one key → JSON.stringify(…, null, 2),
matching BuildContext.updateBuildFileContents).

The malformed-config message in §6 needs the path, which the context must not expose as a getter — return it
from the failing read as an operation result instead.

src/types/plugin-context.ts — output variant

A near-copy of PortalContext: exists() (negated directoryEmpty) and save(tempZipPath, zipPlugin)
(clean directory, then copy as plugin.zip or unarchive). No saveError — the plugin trio has no 422
error-report path.

---

8. Service — src/infrastructure/services/plugin-service.ts

axios-auth variant, modelled on api-service.ts plus the multipart upload in publishing-api-service.ts.
Raw axios now; swap generate/download to the regenerated SDK controller when Rafay ships it. The status
poll stays on axios either way, exactly as portal does today.

export class PluginService {
  private readonly apiBaseUrl = "https://api.apimatic.io" as const;   // envInfo.getBaseUrl() takes precedence

  public async generatePlugin(buildPath, configDir, commandMetadata, authKey)
    : Promise<Result<{ plugin: NodeJS.ReadableStream; deferred: DeferredLanguage[] }, ServiceError>>
}

Sequence, mirroring PortalService.generatePortal:

1. fileService.getStream(buildPath) → FormData field file → POST /plugin?origin=APIMATIC CLI <cmd>.
   Close the stream in finally — non-negotiable.
2. Capture id from the 202 body.
3. pollUntilCompleted(3000, fetchStatus, classifyPluginStatus, 5 * 60 * 1000).
4. GET /plugin/{id}/download with responseType: "stream"; return the stream plus the deferred array
   captured from the terminal status response.

Auth resolution is the standard chain: getAuthInfo(configDir.toString()) → authKey || authInfo?.authKey
→ Authorization: X-Auth-Key <key> (space, not colon), plus envInfo.getUserAgent(shell). Pre-check
if (authInfo === null && !authKey) return err(ServiceError.UnAuthorized).

8.1 Polling refactor

pollUntilCompleted is currently a private module function in portal-service.ts:319. Extract it to
src/infrastructure/services/generation-polling.ts, generic over the status payload:

export type PollDecision =
  | { kind: "continue" } | { kind: "done" } | { kind: "error"; error: ServiceError };

export async function pollUntilCompleted<T>(
  pollIntervalMs: number,
  fetchStatus: () => Promise<Result<T, ServiceError>>,
  classify: (value: T) => PollDecision,
  maxDurationMs?: number
): Promise<Result<T, ServiceError>>

Portal and SDK pass a classify reproducing today's switch verbatim and omit maxDurationMs, so their
behaviour is bit-for-bit unchanged; plugin passes its own classifier and 5 minutes. This is the only change
to shipped code paths in the whole plan.

---

9. sdk publish write-back

Triggered from both publish actions after pollPublishingStatus reports success — not from
SdkPublishAction, which returns as soon as publishing is initiated. Both callers already have
buildDirectory, language, publishingProfile and semVersion in scope
(non-interactive.ts:130-141, interactive.ts:102-110).

// src/actions/plugin/record-sdk.ts
export class PluginRecordSdkAction {
  public readonly execute = async (
    buildDirectory: DirectoryPath,
    language: Language,
    publishingProfile: PublishingProfile,
    codegenVersion: CodeGenerationVersion   // "v3" today; Rafay's flag supplies "v4"
  ): Promise<void> => { … }
}

1. Build the SdkRepoEntry (§9.1). If the repo URL cannot be derived, return silently — never fail a
   successful publish over an optional side effect.
2. exists = await pluginConfigContext.exists()
3. confirm({ message: "Add this SDK to 'plugin-config.json'?", initialValue: true }), worded as create
   vs update. isCancel → false → skip. This is what stops the file being created unconditionally.
4. If creating: resolve metadata exactly as §5 case 1 (Copilot key + prompted Plugin ID / name / version).
5. await pluginConfigContext.upsertSdkRepo(language, entry) → confirmation naming plugin-config.json and
   pointing at 'apimatic plugin generate'.

Returns void, not ActionResult — the publish result must not change.

9.1 Building the entry

sourceCode — GitHub-only assumption. PublishingProfile keeps gitConfigs private with no accessor,
so add:

public getGitConfigurationForLanguage(language: Language): GitConfiguration | undefined

Then normalise defensively, since the publishing-profile API is a separate service
(api.package-publishing.apimatic.io) not present in any repo we hold:

repositoryName looks like	Result
absolute URL	use verbatim
owner/repo	https://github.com/${repositoryName}
bare repo	cannot build a valid URL → skip the write-back

branch comes from gitConfiguration.branch. package comes from
publishingProfile.getPackageConfigurationDataForLanguage(language), mapped per the §1.4 table. version
is the codegen version used for the publish.

Open item (one API call settles it): whether GitConfigurationItem.repositoryName includes the owner.
Hit GET https://api.package-publishing.apimatic.io/api/publishing-profile/user with a real auth key and
inspect one *GitConfiguration.repositoryName. If it is a bare repo name we need the owner from
somewhere — most likely a small addition to that API. The normalisation degrades safely either way, but
the bare-repo branch means no write-back at all.

---

10. Cross-repo coordination

Item	Owner	Why it matters to the CLI
Spec update for the 3 plugin routes	Mahnoor	needed before the SDK can be regenerated
Regenerate + publish @apimatic/sdk	Rafay	lets us swap §8's axios calls to a controller
Add Queued / ExecutionStarted / GeneratingArtifacts / Unknown to the spec's status enum	Mahnoor	otherwise the regenerated SDK still can't type plugin status
--codegen-version / --stability on sdk publish	Rafay	supplies version in §9; until then the CLI writes "v3"
Confirm repositoryName shape	Hamza → publishing API owner	§9.1 open item
Confirm the 401-without-body deviation is permanent	Mahnoor	already flagged in her plan

Worth raising with the wider team, not blocking: ProblemDetails.detail is dropped by
service-error.ts — every specific backend message must live in errors, or the CLI shows only the generic
title. This already bites today: PortalArtifactNotFound → NotFoundException →
provider.BadRequest(message) with no errors, so a bad portal id renders as the bare string
"One or more validation errors occurred."

pnpm-workspace.yaml sets minimumReleaseAge: 10080, but @apimatic/* is in
minimumReleaseAgeExclude, so the regenerated SDK installs immediately.

---

11. Sequenced tasks

1. Branch from origin/dev (never main; PR targets dev).
2. src/types/plugin/* — config + status types. No behaviour, unblocks everything else.
3. PluginConfigContext + PluginContext + unit tests with mock-fs.
4. Extract generation-polling.ts; repoint portal-service.ts; run the existing portal/SDK tests before
   adding plugin code, to prove the refactor is inert.
5. PluginService + nock tests for the trio and every §6 error branch.
6. PluginGeneratePrompts (copy deck §6), then PluginGenerateAction, then the command + package.json
   topic.
7. PublishingProfile.getGitConfigurationForLanguage + PluginRecordSdkAction + wire into both publish
   actions.
8. PluginGenerationFailedEvent + the telemetry tail on the command.
9. pnpm lint && pnpm build && pnpm test.

---

12. Verification

Unit — mocha + chai + sinon + nock + mock-fs, mirroring source paths under test/:

• test/types/plugin-config-context.test.ts — create; upsert preserving an existing language; upsert
  preserving unknown hand-written fields; shorthand-string config reads correctly.
• test/infrastructure/services/plugin-service.test.ts — nock the trio; assert each row of §6; assert the
  5-minute timeout with faked timers; assert the upload stream closes on the error path.
• test/actions/plugin/generate.test.ts — all three cases in §5, plus the deferred notice.
• test/infrastructure/services/generation-polling.test.ts — portal/SDK classifiers unchanged; the timeout
  fires only when maxDurationMs is passed.

End-to-end, against a local apimatic-io on feat/context-plugin-standalone-gen with
ApimaticCodegenV2Api_Url pointed at a local codegen-v2:

pnpm build:watch                       # separate terminal
pnpm apimatic plugin generate -i <dir> # case 1: creates src/plugin-config.json, prints Next Steps
pnpm apimatic sdk publish              # case 2: publish C#, accept the write-back prompt
pnpm apimatic plugin generate -i <dir> # case 3: uploads, polls, downloads into <dir>/plugin

Assertions: the created config passes PluginConfigValidator; the expanded tree matches §2.1 exactly;
.claude-plugin/plugin.json has "name" equal to the pluginId entered at the prompt; a v3-only config
surfaces the sdkRepos message rather than a generic error; a hand-written config generates without the CLI
rewriting it; --zip yields plugin/plugin.zip; Ctrl+C at the Plugin ID prompt warns and exits 130.

The postman collection at Apimatic-io.postman_collection.json (three requests against
https://localhost:44301) is the reference for hitting io directly while debugging.