orbit-code-ai 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbit-code-ai",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Orbit AI – Your AI-powered IBM ACE coding companion",
   "type": "module",
   "author": "moenawaf",

package/skills/api-contract/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: api-contract
+description: Generate a CONTRACT-ONLY OpenAPI (Swagger) 2.0 or 3.0 API definition from an LLD/spec — paths, operations, fully-modeled request/response/error schemas, and a security scheme. This is the API DESIGN/interface (what consumers code against and what you import into API Connect), with NO gateway assembly (no x-ibm-configuration). Pairs with /apic-api, which adds the gateway implementation.
+trigger: /api-contract
+---
+
+# /api-contract
+
+Generate the **contract half** of an API: a clean OpenAPI 2.0 (or 3.0) document that models the
+interface — every operation, the full request/response/error schemas, and the security scheme —
+with **no** DataPower/APIC assembly. This is the artifact you hand to consumers, publish as the
+Swagger, or import into API Connect before attaching a gateway assembly.
+
+> This skill produces `swagger`/`openapi` + `paths` + `definitions` (or `components.schemas`) ONLY.
+> It NEVER emits `x-ibm-configuration`, `assembly`, `invoke`, `gatewayscript`, or any policy. If the
+> user needs the deployable gateway implementation, that is the separate **/apic-api** skill.
+
+## Usage
+
+```
+/api-contract <ApiName> [host] [description + operations + request/response/error models]
+
+Flags:
+  --openapi 2.0|3.0     target spec version — USER'S CHOICE. Ask if unspecified; do not assume.
+  --security S          consumer auth scheme: basic | apikey | clientid-secret | oauth2 | none.
+                        Ask if unspecified. (apikey/clientid-secret = API-key headers; oauth2 needs
+                        a provider/scopes, so ask for them.)
+  --host H              API host (e.g. api.example.com). Ask/placeholder if not given.
+  --basePath P          base path (default "/").
+
+Input model: paste the LLD's operation list and the request/response/error field models (tables or
+JSON samples). The skill's job is to transcribe those faithfully into OpenAPI schemas.
+```
+
+## Variables to Derive
+
+- `{ApiTitle}` = human title, e.g. `Commercial Credit Report API`.
+- `{x-ibm-name}` = kebab-case of the API name, e.g. `commercial-credit-report-api` (also the file stem).
+- `{version}` = `1.0.0` unless supplied.
+- `{host}` = `--host` or a clearly-marked placeholder (`CHANGEME.example.com`).
+- `{basePath}` = `--basePath` or `/`.
+
+Output filename: `{x-ibm-name}_{version}.yaml`
+
+---
+
+## Clarify before generating (do this FIRST)
+
+Ask for anything the prompt didn't supply, in ONE batched follow-up:
+- **OpenAPI version** — 2.0 or 3.0 (always ask if unspecified).
+- **Security scheme** — basic / API-key / OAuth2 / none. For **OAuth2**, ask for the provider name and
+  scopes; if none is available, emit a clearly-marked placeholder scheme and list it in the summary.
+- **Host / basePath** — if not given, use `CHANGEME.example.com` / `/` and flag it.
+- **The data models** — if the request/response/error field structures weren't provided, ask for them
+  (a table or a JSON sample per operation). Do NOT invent business fields you were not given.
+
+Never fabricate real-looking hosts, scopes, or business fields. Placeholders must look like
+placeholders and be listed in the summary.
+
+---
+
+## Generation rules
+
+1. **Contract-only. NEVER emit `x-ibm-configuration` or any assembly/policy.** The output is
+   `swagger`/`openapi`, `info`, `host`/`servers`, `basePath`, `schemes`, `paths`, `securityDefinitions`
+   /`components.securitySchemes`, and `definitions`/`components.schemas`. Nothing else.
+2. **The spec version is the user's choice.** Emit 2.0 from the skeleton, or apply the 3.0 transform.
+3. **One file, ALL operations.** Put every operation under `paths`. Each operation gets: `summary`,
+   `operationId` (camelCase of the operation), `tags`, `security`, request `parameters`/`requestBody`,
+   and a `responses` map.
+4. **Model every response code the LLD lists** — success (200/201) AND the error codes (400/401/422/500,
+   etc.), each with a schema `$ref`. If the LLD gives an error-response shape, model it once
+   (e.g. `ErrorResponse`) and reuse it; distinct error bodies (e.g. a different 500 shape) get their own.
+5. **Transcribe schemas FAITHFULLY (this is the whole job).** Reproduce the LLD's data model exactly:
+   nesting, arrays, required fields, enums, lengths, formats, nullability, and field descriptions. See
+   the "Schema modeling reference" below. Do not flatten nested structures or drop fields.
+6. **Reuse via `$ref`.** Give every reusable object type a named definition and `$ref` it. Don't inline
+   the same structure twice. Deeply-nested one-off objects may be inlined, but shared types must be named.
+7. **Preserve constraints from the LLD**: `required`, `enum`, `maxLength`/`minLength`, `minItems`,
+   `minimum`/`maximum`, `format` (`byte` for base64, `date`/`date-time`, `int32`/`int64`), and
+   `x-nullable: true` (2.0) / `nullable: true` (3.0) for fields the LLD marks nullable. Carry the LLD's
+   field descriptions into `description:` — including conditional rules ("mandatory if X is present").
+8. **Security scheme** per `--security` (see "Security schemes"). Reference it from each operation's
+   `security` (and/or a top-level `security`).
+9. **No invented business data.** Every field/enum/value comes from the LLD. `example:` values may be
+   added only when the LLD provides samples; otherwise omit examples or use obvious placeholders.
+
+---
+
+## OpenAPI 2.0 skeleton (contract-only)
+
+Fill `{slots}`. Example shows one POST operation with success + error responses and a few schema
+patterns; repeat the `paths` entry per operation and grow `definitions` to cover the full model.
+
+```yaml
+swagger: "2.0"
+info:
+  title: {ApiTitle}
+  version: {version}
+  x-ibm-name: {x-ibm-name}
+  description: |
+    {one-or-more lines describing the API, from the LLD purpose/scope}
+host: {host}
+basePath: {basePath}
+schemes:
+  - https
+paths:
+  {basePath-relative-path}:            # e.g. /v1.0/GetReport  (one block per operation)
+    post:                              # or get/put/delete
+      summary: {short summary}
+      operationId: {operationId}
+      tags:
+        - {Tag}
+      security:
+        - {securitySchemeName}: []
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: '#/definitions/{RequestType}'
+      responses:
+        '200':
+          description: Successful operation
+          schema:
+            $ref: '#/definitions/{ResponseType}'
+        '400':
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        '401':
+          description: Authentication failed or token expired
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        '422':
+          description: Validation Error
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        '500':
+          description: Backend / Generic Error
+          schema:
+            $ref: '#/definitions/ErrorResponse500'
+securityDefinitions:
+  # one of the blocks from "Security schemes" below
+  basicAuth:
+    type: basic
+    description: Basic authentication for API Gateway consumers.
+definitions:
+  {RequestType}:
+    type: object
+    required:
+      - {mandatoryField}
+    properties:
+      {field}:
+        type: string
+      {arrayField}:
+        type: array
+        minItems: 1
+        items:
+          $ref: '#/definitions/{ItemType}'
+  {ResponseType}:
+    type: object
+    properties:
+      status:
+        $ref: '#/definitions/Status200'
+      payload:
+        $ref: '#/definitions/{PayloadType}'
+  # Reusable status / error models (name them once, reuse):
+  Status200:
+    type: object
+    properties:
+      statusCode: { type: string, example: "200" }
+      description: { type: string, example: "Success" }
+  ErrorResponse:
+    type: object
+    properties:
+      status:
+        type: object
+        properties:
+          statusCode: { type: string, example: "E10001" }
+          description: { type: string, example: "Validation failed" }
+  ErrorResponse500:
+    type: object
+    properties:
+      status:
+        type: object
+        properties:
+          statusCode: { type: string, example: "E10999" }
+          description: { type: string, example: "Generic Error" }
+  # ... every other type the LLD models (nested objects, arrays, enums, byte, etc.) ...
+```
+
+---
+
+## Schema modeling reference (LLD → OpenAPI)
+
+Translate each LLD attribute exactly:
+
+| LLD says | OpenAPI (2.0) |
+|---|---|
+| text / string | `type: string` |
+| number / decimal | `type: number` |
+| integer | `type: integer` (add `format: int32`/`int64` if the LLD distinguishes) |
+| boolean / flag | `type: boolean` |
+| base64 / binary (e.g. PDF) | `type: string`, `format: byte` |
+| date / datetime | `type: string`, `format: date` / `date-time` |
+| max length N | `maxLength: N` (also `minLength` if given) |
+| allowed values {A,B} | `enum: [A, B]` |
+| list / repeating / (1..*) | `type: array`, `items: {...}`, add `minItems: 1` when ≥1 required |
+| object / nested group | `type: object` with `properties:` (or `$ref` a named type) |
+| mandatory (M) | add the field to the parent's `required:` list |
+| optional (O) | leave out of `required` |
+| conditional (C) | leave out of `required`; put the rule in `description:` ("mandatory if X present") |
+| nullable / may be null | `x-nullable: true` (2.0) / `nullable: true` (3.0) |
+| shared/reused structure | a named `definitions` entry, `$ref`'d everywhere it appears |
+
+Rules of thumb:
+- **Model the FULL depth.** If the LLD nests 6 levels deep, so does the schema. Don't collapse.
+- **Name shared types** (`Status200`, `ErrorResponse`, `AddressType`, …); inline only true one-offs.
+- **Descriptions carry the LLD's semantics** — especially conditional/mutually-exclusive field notes.
+
+---
+
+## Security schemes
+
+Pick per `--security` (all go under `securityDefinitions` in 2.0):
+
+```yaml
+# basic
+basicAuth: { type: basic, description: Basic authentication for API Gateway consumers. }
+
+# API key (single header)
+apiKey: { type: apiKey, in: header, name: X-API-Key }
+
+# client-id / client-secret (APIC-style pair)
+clientID:     { type: apiKey, in: header, name: X-IBM-Client-Id }
+clientSecret: { type: apiKey, in: header, name: X-IBM-Client-Secret }
+
+# oauth2 (ASK for provider + scopes; use placeholders if unknown and list them in the summary)
+oauth2:
+  type: oauth2
+  flow: application            # or accessCode/implicit/password per the provider
+  tokenUrl: https://{CHANGEME-oauth-host}/oauth2/token
+  scopes:
+    {scope}: {description}
+```
+
+Reference the scheme from each operation's `security:` (and optionally a top-level `security:`). For
+`--security none`, omit `securityDefinitions`/`security` entirely.
+
+---
+
+## OpenAPI 3.0 transform (`--openapi 3.0`)
+
+Same contract, only these structural changes:
+
+| 2.0 | 3.0 |
+|---|---|
+| `swagger: "2.0"` | `openapi: 3.0.0` |
+| `host` + `basePath` + `schemes` | `servers: [ { url: https://{host}{basePath} } ]` |
+| `definitions:` | `components.schemas:` |
+| `securityDefinitions:` | `components.securitySchemes:` (`basic`→`{type: http, scheme: basic}`) |
+| body param (`in: body`, `schema`) | `requestBody.content.application/json.schema` |
+| response `schema:` | `responses.<code>.content.application/json.schema` |
+| `$ref: '#/definitions/X'` | `$ref: '#/components/schemas/X'` |
+| `x-nullable: true` | `nullable: true` |
+
+---
+
+## After generating
+
+**Use the Write tool to create `{x-ibm-name}_{version}.yaml` in the current working directory.** Write
+the full document, then print this summary:
+
+```
+✓ {ApiTitle} — OpenAPI {2.0|3.0} contract generated → {x-ibm-name}_{version}.yaml   [api-contract rev-1]
+
+  operations      {N}  ({verb path}, …)
+  security        {basic|apikey|clientid-secret|oauth2|none}
+  responses       {per op: 200 + error codes modeled}
+  schemas         {count} definitions
+  host/basePath   {host}{basePath}
+  placeholders    {list any CHANGEME values, or "none"}
+
+Contract only — no gateway assembly. Add the DataPower implementation with /apic-api (or import this
+into API Connect and build the assembly there).
+```