@devkong/cli-nx 0.0.67-alpha.2 → 0.0.67-alpha.20

package/src/generators/preset/files/python/README.md

@@ -0,0 +1,255 @@
+# Kong Extension
+
+Welcome to the Kong extension development workspace!
+
+To have a better experience, open this file in preview mode of your IDE.
+
+### Prerequisites
+
+Before you start, make sure you have the following installed depending on your OS:
+
+[▶ Windows](#windows-setup)
+
+[▶ Ubuntu](#ubuntu-setup)
+
+[▶ macOS](#macos-setup)
+
+To verify the installation and check the versions, run the following commands:
+
+```shell script
+node --version
+docker info
+```
+
+### Getting Started
+
+1. Make sure you're in the terminal and inside the extension folder you generated
+2. Run the following commands in your terminal:
+
+```shell script
+# configure the base Kong URL (e.g., https://sandbox.kong.dev.app-dts.net)
+kong configure
+
+# install Python dependencies from requirements.txt
+kong install --verbose
+```
+
+### Publish a New Version
+
+To automatically tag your code with an incremented version number (e.g., 1, 2, 3), run:
+
+```shell script
+kong publish-version --verbose
+```
+
+### List Available Versions
+
+To see all available versions of your extension, run:
+
+```shell script
+kong list-versions
+```
+
+### Assign an Alias to a Version
+
+You can assign an alias (e.g., stable, beta) to a specific version. This alias will appear in the UI as a separate step in the workflow. For example, to assign the alias stable to version 1, use:
+
+```shell script
+kong set-alias stable 1
+```
+
+### Using a Custom Profile
+
+If you're developing an extension that will be used in different regions (or need to work with a specific profile), you can create a new profile using `kong configure`. Then, include the `--profile <name>` parameter when running the publish-version and set-alias commands to use the desired profile.
+
+### Update CLI
+
+To install the latest version of the CLI, run:
+
+```shell script
+npm i -g @devkong/cli@latest
+```
+
+### Setup
+
+<details id="windows-setup">
+<summary><strong>Windows</strong></summary>
+
+### Install Windows Subsystem for Linux (WSL2)
+
+1. Open PowerShell as Administrator.
+2. Run the following command to install WSL and set WSL2 as the default version:
+   ```powershell
+   wsl --install
+   ```
+3. Restart your computer if prompted.
+4. After restarting, install a preferred Linux distribution (e.g., Ubuntu) by running:
+   ```powershell
+   wsl --install -d Ubuntu
+   ```
+
+### Install Docker within WSL2
+
+1. Download Docker Desktop for Windows from [Docker's official website](https://www.docker.com/products/docker-desktop).
+2. Run the installer and follow the setup instructions.
+3. During installation, ensure the "Use the WSL 2 based engine" option is selected.
+4. Once installed, open Docker Desktop, go to Settings > General, and enable "Use WSL 2 based engine" if it isn't already enabled.
+5. Confirm Docker is working in your WSL2 distribution (e.g., Ubuntu) by running:
+   ```bash
+   docker --version
+   ```
+
+### Install Node.js and npm on Windows Host
+
+1. Download the Node.js installer for Windows from the [official Node.js website](https://nodejs.org/).
+2. Run the installer, making sure to include the npm package manager during installation.
+3. Verify installation by opening a new Command Prompt and running:
+   ```cmd
+   node -v
+   npm -v
+   ```
+
+### Install Python on Windows Host
+
+1. Download the Python installer (version >= 3.10) for Windows from the [official Python website](https://www.python.org/downloads/windows/).
+2. Run the installer, making sure to check "Add Python to PATH" during setup.
+3. Verify installation by running:
+   ```cmd
+   python --version
+   pip --version
+   ```
+
+### Install Poetry on Windows Host
+
+1. Open Command Prompt or PowerShell.
+2. Run the following command:
+   ```powershell
+   (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+   ```
+3. Add Poetry to your PATH:
+   ```powershell
+   $env:Path += ";$env:USERPROFILE\.poetry\bin"
+   ```
+4. Verify installation:
+   ```powershell
+   poetry --version
+   ```
+
+</details>
+
+<details id="ubuntu-setup">
+<summary><strong>Ubuntu</strong></summary>
+
+### Install Docker
+
+1. Follow the installation instructions on [Docker's official website](https://docs.docker.com/engine/install/ubuntu/).
+2. Start Docker and enable it to start on boot:
+   ```bash
+   sudo systemctl start docker
+   sudo systemctl enable docker
+   ```
+
+### Install Node.js and npm
+
+1. Run the following commands:
+   ```bash
+   sudo apt update
+   sudo apt install -y nodejs npm
+   ```
+2. Verify installation:
+   ```bash
+   node -v
+   npm -v
+   ```
+
+### Install Python
+
+1. Run the following commands:
+   ```bash
+   sudo apt update
+   sudo apt install -y python3 python3-pip
+   ```
+2. Verify installation:
+   ```bash
+   python3 --version
+   pip3 --version
+   ```
+
+### Install Poetry
+
+1. Run the following command:
+   ```bash
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+2. Add Poetry to your PATH:
+   ```bash
+   export PATH="$HOME/.local/bin:$PATH"
+   ```
+3. Reload the shell:
+   ```bash
+   source ~/.bashrc
+   ```
+4. Verify installation:
+   ```bash
+   poetry --version
+   ```
+
+</details>
+
+<details id="macos-setup">
+<summary><strong>macOS</strong></summary>
+
+To emulate a Linux platform, you need to install Rosetta:
+
+```shell script
+softwareupdate --install-rosetta
+```
+
+### Install Docker
+
+1. Download and install Docker Desktop for Mac from [Docker's official website](https://www.docker.com/products/docker-desktop).
+
+### Install Node.js and npm
+
+1. Use Homebrew to install:
+   ```bash
+   brew install node
+   ```
+2. Verify installation:
+   ```bash
+   node -v
+   npm -v
+   ```
+
+### Install Python
+
+1. Use Homebrew to install:
+   ```bash
+   brew install python
+   ```
+2. Verify installation:
+   ```bash
+   python3 --version
+   pip3 --version
+   ```
+
+### Install Poetry
+
+1. Run the following command:
+   ```bash
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+2. Add Poetry to your PATH:
+   ```bash
+   export PATH="$HOME/.local/bin:$PATH"
+   ```
+3. Reload the shell:
+   ```bash
+   source ~/.bashrc
+   ```
+4. Verify installation:
+   ```bash
+   poetry --version
+   ```
+
+</details>

package/src/generators/preset/files/python/kong.json.template

@@ -0,0 +1,6 @@
+{
+  "id": "<%=id%>",
+  "name": "<%=name%>",
+  "sdk": "<%=platform%>",
+  "category": "unknown"
+}

package/src/generators/preset/files/python/project.json.template

@@ -0,0 +1,8 @@
+{
+  "name": "<%=name%>",
+  "$schema": "./node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "./src",
+  "targets": {},
+  "tags": []
+}

package/src/generators/preset/files/python/pyproject.toml

@@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

package/src/generators/preset/files/python/requirements-dev.txt

@@ -0,0 +1,10 @@
+black==26.5.1
+flake8==7.3.0
+isort==8.0.1
+pylint==4.0.6
+pylint-pydantic==0.4.1
+pytest==9.1.1
+pytest-asyncio==1.4.0
+pytest-cov==7.1.0
+pytest-html==4.2.0
+pytest-sugar==1.1.1

package/src/generators/preset/files/python/requirements.txt

@@ -0,0 +1,2 @@
+pydantic==2.13.4
+kong-sdk==0.0.46

package/src/generators/preset/files/python/src/frontend.py

@@ -0,0 +1,3 @@
+from kong.sdk.kong_frontend import KongFrontend, KongFrontendBuilder
+
+frontend: KongFrontend = KongFrontendBuilder().build()

package/src/generators/preset/files/python/src/input_data.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field
+
+
+class InputData(BaseModel):
+    a: int = Field(
+        examples=[1],
+        description="An integer number",
+    )
+
+    b: int = Field(
+        examples=[2],
+        description="An integer number",
+    )

package/src/generators/preset/files/python/src/main.py

@@ -0,0 +1,28 @@
+import sys
+
+from kong.sdk.app import App
+from kong.sdk.kong_function import KongFunction
+from kong.sdk.kong_function_context import KongFunctionContext
+
+from frontend import frontend
+from input_data import InputData
+from output_data import OutputData
+
+
+class Main(KongFunction):
+    async def handle(self, data: InputData, context: KongFunctionContext) -> OutputData:
+        return OutputData(
+            sum_of=data.a + data.b,
+            comment=f"sum of {data.a} and {data.b}",
+        )
+
+
+app = App(
+    InputData,
+    OutputData,
+    Main,
+    frontend,
+)
+
+if __name__ == "__main__":
+    app.run(sys.argv)

package/src/generators/preset/files/python/src/main_test.py

@@ -0,0 +1,19 @@
+from kong.sdk.conftest import ExtensionFixture, extension_test_context
+
+from frontend import frontend
+from input_data import InputData
+from main import Main
+
+
+async def test_should_return_value_from_string_field_when_input_is_provided(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        a=1,
+        b=2,
+    )
+
+    output = await extension.handle(input_data, extension_test_context(frontend))
+    assert output.sum_of == 3

package/src/generators/preset/files/python/src/output_data.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OutputData(BaseModel):
+    sum_of: int = Field(
+        examples=[3],
+        description="Result of a + b",
+    )
+
+    comment: Optional[str] = Field(
+        examples=["This example extension returns sum of a and b"],
+        description="A string field",
+    )

package/src/generators/preset/files/python-advanced/src/frontend.py

@@ -0,0 +1,9 @@
+from input_data import MySecret
+from kong.sdk.kong_frontend import KongFrontend, KongFrontendBuilder
+
+frontend: KongFrontend = (
+    KongFrontendBuilder()
+    .with_secret_types("primary", {"my-secret": MySecret})
+    .with_form()
+    .build()
+)

package/src/generators/preset/files/python-advanced/src/input_data.py

@@ -0,0 +1,47 @@
+from typing import Optional
+
+from kong.sdk.kong_function_request import KongFunctionRequest
+from pydantic import BaseModel, Field
+
+
+class MySecret(BaseModel):
+    my_key: str = Field(
+        examples=["example-0123456789"],
+        description="An example of secret field",
+    )
+
+
+class OperationData(BaseModel):
+    a: int = Field(
+        examples=[1],
+        description="An integer number",
+    )
+
+    b: int = Field(
+        examples=[2],
+        description="An integer number",
+    )
+
+
+class InputData(BaseModel):
+    request: KongFunctionRequest
+
+    sum: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'sum' operation",
+    )
+
+    sub: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'sub' operation",
+    )
+
+    multiply: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'multiply' operation",
+    )
+
+    divide: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'divide' operation",
+    )

package/src/generators/preset/files/python-advanced/src/main.py

@@ -0,0 +1,51 @@
+import sys
+
+from frontend import frontend
+from input_data import InputData, OperationData
+from kong.sdk.app import App
+from kong.sdk.kong_function import KongFunction
+from kong.sdk.kong_function_context import KongFunctionContext
+from output_data import OutputData
+
+
+class Main(KongFunction):
+    async def handle(self, data: InputData, context: KongFunctionContext) -> OutputData:
+        operation = data.request.operation
+        operands = getattr(data, operation, None)
+        if not isinstance(operands, OperationData):
+            raise ValueError(f"Missing or unsupported operation '{operation}'")
+
+        if operation == "sum":
+            result = operands.a + operands.b
+        elif operation == "sub":
+            result = operands.a - operands.b
+        elif operation == "multiply":
+            result = operands.a * operands.b
+        elif operation == "divide":
+            if operands.b == 0:
+                raise ValueError("Cannot divide by zero")
+            result = operands.a // operands.b
+        else:
+            raise ValueError(f"Unsupported operation '{operation}'")
+
+        comment = f"{operation} result is {result}"
+
+        secret = context.secret.find("primary")
+        if secret is not None:
+            comment += " (authenticated)"
+
+        return OutputData(
+            result=result,
+            comment=comment,
+        )
+
+
+app = App(
+    InputData,
+    OutputData,
+    Main,
+    frontend,
+)
+
+if __name__ == "__main__":
+    app.run(sys.argv)

package/src/generators/preset/files/python-advanced/src/main_test.py

@@ -0,0 +1,46 @@
+import json
+
+from frontend import frontend
+from input_data import InputData, OperationData
+from kong.sdk.conftest import ExtensionFixture, extension_test_context
+from kong.sdk.kong_function_request import KongFunctionRequest
+from main import Main
+
+
+async def test_should_add_operands_when_operation_is_sum(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        request=KongFunctionRequest(operation="sum"),
+        sum=OperationData(a=1, b=2),
+    )
+
+    output = await extension.handle(input_data, extension_test_context(frontend))
+    assert output.result == 3
+
+
+async def test_should_note_authentication_when_secret_is_provided(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        request=KongFunctionRequest(operation="sum"),
+        sum=OperationData(a=1, b=2),
+    )
+
+    # Secrets arrive as a `{"type", "data"}` JSON envelope keyed by purpose, exactly
+    # as the executor materializes them at runtime.
+    secrets = {
+        "primary": json.dumps(
+            {"type": "my-secret", "data": {"my_key": "example-0123456789"}}
+        )
+    }
+
+    context = extension_test_context(frontend, secrets)
+    output = await extension.handle(input_data, context)
+
+    assert output.result == 3
+    assert output.comment == "sum result is 3 (authenticated)"

package/src/generators/preset/files/python-advanced/src/output_data.py

@@ -0,0 +1,16 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OutputData(BaseModel):
+    result: int = Field(
+        examples=[3],
+        description="Result of applying the operation to a and b",
+    )
+
+    comment: Optional[str] = Field(
+        default=None,
+        examples=["sum result is 3"],
+        description="A string field",
+    )

package/src/generators/preset/generator.js

@@ -6,6 +6,7 @@ const devkit_1 = require("@nx/devkit");
 const path = tslib_1.__importStar(require("path"));
 function presetGenerator(tree, options) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a;
         const projectRoot = ".";
         const projectName = "";
         (0, devkit_1.addProjectConfiguration)(tree, projectName, {
@@ -13,7 +14,14 @@ function presetGenerator(tree, options) {
             projectType: "application",
         });
         options.os = process.platform;
+        options.variant = (_a = options.variant) !== null && _a !== void 0 ? _a : "basic";
         (0, devkit_1.generateFiles)(tree, path.join(__dirname, `files/${options.platform}`), "", options);
+        // The python preset ships a "basic" (single sum) and an "advanced" (multi-operation
+        // + secret example) template. The advanced sources are layered on top of the shared
+        // base, overwriting the basic src/*.py files.
+        if (options.platform === "python" && options.variant === "advanced") {
+            (0, devkit_1.generateFiles)(tree, path.join(__dirname, "files/python-advanced"), "", options);
+        }
         yield (0, devkit_1.formatFiles)(tree);
         try {
             const gradlewPath = (0, devkit_1.joinPathFragments)(projectRoot, "gradlew");

package/src/generators/preset/generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../src/generators/preset/generator.ts"],"names":[],"mappings":";;AAUA,0CAoBC;;AA9BD,uCAMoB;AACpB,mDAA6B;AAG7B,SAAsB,eAAe,CAAC,IAAU,EAAE,OAA8B;;QAC9E,MAAM,WAAW,GAAG,GAAG,CAAC;QACxB,MAAM,WAAW,GAAG,EAAE,CAAC;QACvB,IAAA,gCAAuB,EAAC,IAAI,EAAE,WAAW,EAAE;YACzC,IAAI,EAAE,WAAW;YACjB,WAAW,EAAE,aAAa;SAC3B,CAAC,CAAC;QAEH,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;QAC9B,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QACpF,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;QAExB,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,IAAA,0BAAiB,EAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YAC9D,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC7B,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,YAAY;YAC1D,CAAC;QACH,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;CAAA;AAED,kBAAe,eAAe,CAAC"}
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../src/generators/preset/generator.ts"],"names":[],"mappings":";;AAUA,0CA6BC;;AAvCD,uCAMoB;AACpB,mDAA6B;AAG7B,SAAsB,eAAe,CAAC,IAAU,EAAE,OAA8B;;;QAC9E,MAAM,WAAW,GAAG,GAAG,CAAC;QACxB,MAAM,WAAW,GAAG,EAAE,CAAC;QACvB,IAAA,gCAAuB,EAAC,IAAI,EAAE,WAAW,EAAE;YACzC,IAAI,EAAE,WAAW;YACjB,WAAW,EAAE,aAAa;SAC3B,CAAC,CAAC;QAEH,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;QAC9B,OAAO,CAAC,OAAO,GAAG,MAAA,OAAO,CAAC,OAAO,mCAAI,OAAO,CAAC;QAC7C,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QAEpF,oFAAoF;QACpF,oFAAoF;QACpF,8CAA8C;QAC9C,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACpE,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QAClF,CAAC;QAED,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;QAExB,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,IAAA,0BAAiB,EAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YAC9D,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC7B,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,YAAY;YAC1D,CAAC;QACH,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;CAAA;AAED,kBAAe,eAAe,CAAC"}

package/src/generators/preset/schema.d.ts

@@ -1,5 +1,11 @@
 export interface PresetGeneratorSchema {
   name: string;
-  os: string;
+  // Extension id, forwarded by the CLI and rendered into kong.json.
+  id?: string;
+  // Set by the generator at runtime from `process.platform`.
+  os?: string;
   platform: "python" | "kotlin";
+  // Which starter template to scaffold. Only the python preset currently ships more
+  // than "basic"; "advanced" adds the multi-operation + secret example variant.
+  variant?: "basic" | "advanced";
 }

package/src/generators/preset/schema.json

@@ -21,7 +21,32 @@
         "index": 1
       },
       "x-prompt": "What platform would you like to use?"
+    },
+    "variant": {
+      "type": "string",
+      "description": "Which starter template to scaffold",
+      "enum": [
+        "basic",
+        "advanced"
+      ],
+      "default": "basic",
+      "x-prompt": {
+        "message": "Which template would you like to use?",
+        "type": "list",
+        "items": [
+          {
+            "value": "basic",
+            "label": "basic - a single operation"
+          },
+          {
+            "value": "advanced",
+            "label": "advanced - multiple operations with a secret example"
+          }
+        ]
+      }
     }
   },
-  "required": ["name"]
-}
+  "required": [
+    "name"
+  ]
+}