AGENTS.md for easy app creation with coding agents

AGENTS.md

@@ -0,0 +1,76 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repository hosts Shuffle app implementations. Each app lives in a top-level folder named after the integration (e.g., `aws-ec2/`), and each release is versioned under a subfolder like `1.0.0/`. A typical app version contains:
+
+- `src/app.py`: the Shuffle SDK entry point.
+- `api.yaml`: OpenAPI definition used by Shuffle.
+- `requirements.txt`: Python dependencies for the app.
+- `Dockerfile`: container build instructions for the app.
+- `README.md`: app-specific usage and action documentation.
+- Optional assets such as screenshots (`*.png`).
+
+In `api.yaml`, prefer an `authentication` block for shared credentials (URL, tokens, keys). Actions should only include auth parameters when they truly differ per call.
+
+## Build, Test, and Development Commands
+Apps are built and run container-first via the Shuffle SDK image. From an app version directory:
+
+- `docker build -t shuffle-<app>:<version> .`: build the app image.
+- `docker run --rm shuffle-<app>:<version>`: run the app container locally.
+
+For quick iteration on code, you can also run the Python entrypoint in a virtualenv:
+
+- `pip install -r requirements.txt`
+- `python src/app.py --log-level DEBUG`
+
+## Coding Style & Naming Conventions
+Use 4-space indentation and standard Python style. Keep functions `snake_case`, classes `CamelCase`, and constants `UPPER_SNAKE_CASE`. Match existing patterns in `src/app.py` and keep action names aligned with `api.yaml`.
+
+## Creating New Shuffle Apps (Agent Workflow)
+Use an existing app as a template (e.g., `http/1.4.0/` or `aws-ec2/1.0.0/`) and follow the same folder layout. A minimal, working app version should include:
+
+- `api.yaml`: action definitions, parameters, and examples.
+- `src/app.py`: class extending the Shuffle SDK (`shuffle_sdk.AppBase`).
+- `requirements.txt`: third-party dependencies.
+- `Dockerfile`: built on `frikky/shuffle:app_sdk`.
+
+When adding actions, ensure the `api.yaml` action name matches the method name in `src/app.py` and parameter names align exactly. Keep input parsing defensive (strings vs JSON), and return JSON-serializable results. For HTTP integrations, centralize auth and base URL handling and add a TLS `verify` option. If a service requires special payloads (e.g., ADF for Jira), accept JSON strings and pass through unchanged. Keep `api.yaml` examples realistic because they show up in the Shuffle UI.
+
+## Authentication & App Configuration
+Most apps declare credentials in `api.yaml` under `authentication:` so Shuffle injects them automatically. In code, read those values as normal action arguments (Shuffle passes them into each action). Prefer a single auth helper in `src/app.py` (e.g., `_auth()` for tokens, `_build_api_base()` for base URLs) and reuse it across actions. If an integration supports multiple auth modes (token vs password), accept both and choose the provided one.
+
+Prefer small, focused actions (create, update, list, search) and document auth requirements and examples in the app `README.md`.
+
+## Manual Python App Notes (From Shuffle Docs)
+- **SDK image choices:** Shuffle provides Alpine (slim), Kali (security tooling), and Blackarch (kitchen‑sink). This repo’s Dockerfiles typically use `frikky/shuffle:app_sdk` (Alpine‑based) unless a toolset requires otherwise.
+- **Directory layout:** `api.yaml`, `Dockerfile`, `requirements.txt`, `README.md`, and `src/app.py` are expected in each app version. Complex apps can add additional modules under `src/` and import them from `app.py`.
+- **Actions & wiring:** Every action in `api.yaml` must map to a method in `src/app.py` with the same name and argument list. Authentication parameters are passed into each action automatically when declared under `authentication:`.
+- **Utility helpers:** In `AppBase`, you can use `self.get_file`, `self.set_files`, `self.update_file`, and cache helpers `self.get_cache`, `self.set_cache`, `self.delete_cache` for file and key/value workflows.
+- **Prototyping:** Build and test your Python logic locally first, then wire it into `src/app.py`. Keep return values JSON‑serializable so Shuffle can consume them.
+- **Upload & hotload:** After a prototype works, upload it to Shuffle (cloud) or hotload locally (on‑prem) by rebuilding the app image. Local Docker rebuilds are faster for iteration.
+
+## Testing, Hotloading, and CI/CD
+- **Cloud upload test:** Use the Upload App API to add the app to your org, then run a workflow to validate actions.
+- **Local hotload (on‑prem):** Place the app folder in `shuffle-apps/`, set `SHUFFLE_APP_HOTLOAD_FOLDER=./shuffle-apps`, then use the hot reload button in the UI. Allow ~20 seconds for the reload to complete.
+- **Update workflow deps:** If you update an existing app version, remove and re‑add the app in any workflows that reference it.
+- **Fast local iteration:** After the first upload, rebuild locally: `docker images | grep <appname>` then `docker build . -t <imagename>`.
+- **CI/CD pattern:** Create a test workflow, upload a test app version, run the workflow via API, and validate `workflowexecution.workflow.validation.valid` before promoting.
+
+## Publishing Apps
+- **OpenAPI apps:** Upload to your instance, then use the `/apps` page to publish so it appears on `shuffler.io`.
+- **Python apps:** Fork `https://github.com/frikky/shuffle-apps`, add your app, and open a pull request to upstream.
+
+## Testing Guidelines
+There is no repository-wide test suite. If you add tests for a specific app, keep them alongside the app version (e.g., `aws-ec2/1.0.0/tests/`) and document how to run them in that app’s `README.md`.
+
+## Commit & Pull Request Guidelines
+Commit messages are short and descriptive, sometimes using a prefix like `fix:`. Follow that style and keep commits scoped to a single app/version when possible.
+
+For pull requests, include:
+
+- A clear description of the change and impacted app/version path.
+- Updated `README.md` or `api.yaml` when behavior changes.
+- Screenshots/assets if user-facing output or UI-related docs are affected.
+
+## Security & Configuration Tips
+Many apps require API keys or credentials. Do not commit secrets; use environment variables or Shuffle configuration fields instead, and document required inputs in the app’s `README.md`.

opensearch/1.0.0/Dockerfile

@@ -0,0 +1,23 @@
+# Base our app image off of the WALKOFF App SDK image
+FROM frikky/shuffle:app_sdk as base
+
+# We're going to stage away all of the bloat from the build tools so lets create a builder stage
+FROM base as builder
+
+# Install all alpine build tools needed for our pip installs
+RUN apk --no-cache add --update alpine-sdk libffi libffi-dev musl-dev openssl-dev
+
+# Install all of our pip packages in a single directory that we can copy to our base image later
+RUN mkdir /install
+WORKDIR /install
+COPY requirements.txt /requirements.txt
+RUN pip install --prefix="/install" -r /requirements.txt
+
+# Switch back to our base image and copy in all of our built packages and source code
+FROM base
+COPY --from=builder /install /usr/local
+COPY src /app
+
+# Finally, lets run our app!
+WORKDIR /app
+CMD python app.py --log-level DEBUG

opensearch/1.0.0/README.md

@@ -0,0 +1,50 @@
+# OpenSearch
+
+OpenSearch Shuffle app using mutual TLS (client certificate) authentication.
+
+## Authentication
+
+Configure the following in the app authentication section:
+
+- `base_url`: OpenSearch base URL (e.g. `https://opensearch.example.com:9200`).
+- `client_cert`: Client certificate (PEM) file ID.
+- `client_key`: Client private key (PEM) file ID.
+- `ca_cert` (optional): CA certificate (PEM) file ID used for TLS verification.
+- `verify` (optional): `true` or `false`.
+- `timeout` (optional): Request timeout in seconds.
+
+Notes:
+- If your client certificate file already contains the private key, upload the same file for both `client_cert` and `client_key`.
+- If `verify` is `true` and `ca_cert` is provided, the CA cert is used for TLS verification.
+
+## Actions
+
+- `cluster_health`: Get cluster health status.
+- `list_indices`: List indices via `_cat/indices`.
+- `get_index`: Get index settings and mappings.
+- `create_index`: Create an index with settings/mappings.
+- `delete_index`: Delete an index.
+- `index_document`: Index a document by ID.
+- `create_document`: Create a document with an auto-generated ID.
+- `get_document`: Get a document by ID.
+- `update_document`: Update a document by ID.
+- `delete_document`: Delete a document by ID.
+- `search`: Search an index by query DSL or query string.
+- `bulk`: Bulk index/update/delete (NDJSON).
+- `raw_request`: Send a custom request to any OpenSearch endpoint.
+
+## Local development
+
+From this version directory:
+
+```bash
+docker build -t shuffle-opensearch:1.0.0 .
+docker run --rm shuffle-opensearch:1.0.0
+```
+
+Or run locally:
+
+```bash
+pip install -r requirements.txt
+python src/app.py --log-level DEBUG
+```