{"id":37422163,"url":"https://github.com/devrev/airdrop-shared","last_synced_at":"2026-01-16T06:07:38.007Z","repository":{"id":300201368,"uuid":"1004835632","full_name":"devrev/airdrop-shared","owner":"devrev","description":"An experimental base structure for LLM-generated Airdrop snap-ins, worked on in collaboration with @Codeplain-ai","archived":false,"fork":false,"pushed_at":"2025-11-20T15:22:34.000Z","size":126,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-20T17:21:31.097Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devrev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":"docs/supported-object-types.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-19T08:55:24.000Z","updated_at":"2025-11-20T15:22:40.000Z","dependencies_parsed_at":"2025-09-23T15:10:37.964Z","dependency_job_id":"0740468e-af7a-4883-925f-1a3b3201d32b","html_url":"https://github.com/devrev/airdrop-shared","commit_stats":null,"previous_names":["devrev/airdrop-shared"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devrev/airdrop-shared","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devrev%2Fairdrop-shared","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devrev%2Fairdrop-shared/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devrev%2Fairdrop-shared/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devrev%2Fairdrop-shared/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devrev","download_url":"https://codeload.github.com/devrev/airdrop-shared/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devrev%2Fairdrop-shared/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T06:07:37.489Z","updated_at":"2026-01-16T06:07:37.980Z","avatar_url":"https://github.com/devrev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shared Files for Snap-in Generation with Codeplain\n\nThis repository (`airdrop-shared`) provides a centralized collection of files used as a common foundation for building DevRev snap-ins with the Codeplain generation tool. By sharing templates, scripts, and schemas, we can ensure consistency and accelerate development.\n\n### Related Snap-in Repositories\n\nThese repositories serve as examples of how `airdrop-shared` is used in practice:\n\n  - [airdrop-trello-snap-in](https://github.com/devrev/airdrop-trello-snap-in)\n  - [airdrop-wrike-snap-in](https://github.com/devrev/airdrop-wrike-snap-in)\n\n-----\n\n## Getting Started: Creating a New Snap-in\n\nThis guide walks you through the process of setting up a new snap-in project using the shared files from this repository.\n\n### 1\\. Prerequisites\n\nBefore you begin, ensure you have the following set up on your local machine.\n\n#### Folder Structure\n\nYour snap-in project directory must be in the same root directory as `airdrop-shared` repository.\n\n```sh\n# Your project layout should look like this\n.\n├── airdrop-shared/\n├── airdrop-trello-snap-in/\n├── airdrop-wrike-snap-in/\n└── your-new-snap-in/      # This is your new project\n```\n\n#### Chef CLI\n\nDownload the newest version of `chef-cli` binary and place it in a known location on your local machine. Don't forget to make it executable.\n\n  - **Installation guide:** [Install Chef CLI](https://github.com/devrev/adaas-chef-cli/blob/main/README.md)\n\n#### Codeplain Client\n\nClone the Codeplain client repository, which contains the code generation script.\n\n  - **Clone from:** [Codeplain-ai/plain2code\\_client](https://github.com/Codeplain-ai/plain2code_client)\n\n### 2\\. Project Setup\n\nIn the root of your new snap-in project directory, create and configure the following files.\n\n  - **`manifest.yaml`**:\n    This file defines your snap-in's metadata. It is **not** generated automatically. You must create one tailored to your snap-in's needs. For guidance, refer to the [DevRev manifest documentation](https://developer.devrev.ai/public/airdrop/manifest).\n\n  - **`config.yaml`**:\n    This file configures the code generation process. You must include paths pointing to the cloned `airdrop-shared` repository. Other fields can be adjusted to assist with code generation (rendering).\n\n    *Example `config.yaml`:*\n\n    ```yaml\n    # Paths to the shared repository\n    base-folder: ../airdrop-shared/base_folder\n    template-dir: ../airdrop-shared\n    unittests-script: ../airdrop-shared/scripts/run_unittests_jest.sh\n    conformance-tests-script: ../airdrop-shared/scripts/run_devrev_snapin_conformance_tests.sh\n\n    # Other rendering options (see \"Workflow \u0026 Best Practices\" below)\n    # render-from: 2.3.1\n    # render-range: 2.3.1,2.3.2\n    ```\n\n  - **`.env`**:\n    Create a `.env` file to store sensitive information and local paths. At a minimum, it must contain the absolute path to the `chef-cli` binary. Add any other variables, such as API credentials, that your project requires.\n\n    *Example `.env` for a Wrike snap-in:*\n\n    ```bash\n    WRIKE_API_KEY=your_wrike_api_key\n    WRIKE_SPACE_GID=your_wrike_space_gid\n\n    # Absolute path to the Chef CLI binary\n    CHEF_CLI_PATH=/Users/yourname/path/to/chef-cli\n    ```\n\n  - **`devrev-\u003cexternal-system\u003e-snapin.plain`**:\n    This is the core specification file for your snap-in. It is highly recommended to copy the `.plain` file from an existing snap-in (like [Trello](https://github.com/devrev/airdrop-trello-snap-in) or [Wrike](https://github.com/devrev/airdrop-wrike-snap-in)) and modify it. Start with a minimal set of functional requirements and expand as you go.\n\n      - Learn more about the specification language: [Plain Language Specification Guide](https://github.com/Codeplain-ai/plain2code_client/blob/main/Plain-language-specification.md)\n\n  - **`test_data/`**:\n    Create this folder to store JSON data files that your Acceptance tests will use.\n\n### 3\\. Running Code Generation\n\n#### Environment Preparation\n\n1.  Navigate to your cloned `plain2code_client` directory.\n2.  Create and activate a Python virtual environment.\n3.  Install the required dependencies:\n    ```sh\n    pip install -r requirements.txt\n    ```\n4.  Export the required environment variables.\n    ```sh\n    # Your Codeplain API Key\n    export CLAUDE_API_KEY=\"your_api_key\"\n\n    # Absolute path to the cloned plain2code_client repository\n    export PLAIN2CODE_RENDERER_DIR=\"/path/to/your/plain2code_client\"\n    ```\n\n#### Execute the Generation Script\n\nFrom your snap-in's root directory, run the code generation script, pointing it to your `.plain` specification file.\n\n```sh\npython $PLAIN2CODE_RENDERER_DIR/plain2code.py devrev-wrike-snapin.plain\n```\n\n-----\n\n## Development Workflow \u0026 Best Practices\n\n  - **Render Iteratively**: Instead of generating the entire snap-in at once, render one functional requirement (FR) at a time. This allows you to verify the generated code at each step. Use the `render-from` and `render-range` options in `config.yaml` to control this.\n\n      - `render-from: 2.3.1`: Renders from FR `2.3.1` to the end.\n      - `render-range: 2.3.1,2.3.2`: Renders only FRs between `2.3.1` and `2.3.2` (inclusive).\n\n    \u003e **Warning:** Regenerating a range of FRs will invalidate any subsequently generated requirements. For example, if you regenerate `2.3.1`-`2.3.2`, you will at some point also need to regenerate `2.3.3`.\n\n  - **Use Acceptance Tests for Complex Logic**: When a functional requirement becomes too complex to describe in detail or you're struggling with writing the FR, you can add an `Acceptance Tests` block directly in the `.plain` file. This helps guide the code generation model with a concrete example of the expected outcome.\n\n    *Example in a `.plain` file:*\n\n    ```markdown\n    - If \"event_type\" equals \"EXTRACTION_DATA_START\" The Extraction Function should:\n      - push The Fetched Contacts to the repository named 'users'\n      - push The Fetched Tasks to the repository designated for 'tasks' data\n      (but make sure that a single \"EXTRACTION_DATA_DONE\" event is emitted)\n\n    ***Acceptance Tests:***\n\n      - Test The Extraction Function using the resource [data_extraction_test.json](test_data/data_extraction_test.json). Test is successful if The Callback Server receives from DevRev a **single** event with \"event_type\" that equals \"EXTRACTION_DATA_DONE\". The test must not send event directly to The Callback Server.\n    ```\n\n  - **Debug with Conformance Tests**: If you encounter issues while rendering a specific functional requirement, you can run its associated conformance test individually. The `conformance_tests/conformance_tests.json` file maps FRs to their test names.\n\n    1.  Identify the FR that is causing an issue.\n    2.  Look up the corresponding test name in `conformance_tests.json`.\n    3.  Run the specific test using the following command:\n\n    \u003c!-- end list --\u003e\n\n    ```bash\n    sh ../airdrop-shared/scripts/run_devrev_snapin_conformance_tests.sh build conformance_tests/\u003cconformance-test-name\u003e\n    ```\n\n  - **Use a Test Account**: Code generation is more accurate and successful when it can reference real-world data structures. Set up a test account in the target external system and populate it with representative data.\n\n  - **Handling Interruptions**: Code generation can take a long time. If your internet connection drops or the process is otherwise interrupted, it may appear to freeze.\n\n    1.  Cancel the running Python script (`Ctrl+C`).\n    2.  Open `config.yaml` and set the `render-from` option to the ID of the last successfully completed functional requirement.\n    3.  Restart the generation script.\n\n-----\n\n## Repository Contents (`airdrop-shared`)\n\nThis repository contains the following shared components:\n\n  - `base_folder/`: A starter template for a new snap-in, adapted from [devrev/airdrop-template](https://github.com/devrev/airdrop-template).\n  - `devrev-snapin-template.plain`: A general Plain Language specification that serves as a base template for all snap-ins.\n  - **Resource Files**:\n      - `test_data/`: Contains shared JSON test data files that are referenced in `.plain` specifications.\n      - `external_domain_metadata_schema.json`: The JSON schema for external domain metadata.\n  - **Scripts**:\n      - `run_unittests_jest.sh`: A reusable script for running the snap-in's unit tests.\n      - `run_devrev_snapin_conformance_tests.sh`: A reusable script for running the snap-in's conformance tests.\n  - **Auxiliary Files**:\n      - `jest.setup.js`, `mock_callback_server.py`: Helper files required by the unit test and conformance test scripts.\n\n### How to Override Shared Files\n\nYou may want to use your own custom specification or test files instead of the ones given in the `airdrop-shared` repository - for example if you'd like to write your own `devrev-snapin-template.plain`.\n\nYour local snap-in repository can override any file from this shared repository. Files in your snap-in's project directory always take precedence.\n\n  - **`.plain` Templates**: To override `devrev-snapin-template.plain`, simply create a file with the same name in the root of your snap-in project.\n\n  - **Resource Files**: To override a resource file, create a new file at the **same relative path** within your snap-in project.\n\n      - *Example*: To override `airdrop-shared/test_data/data_extraction_check.json`, create the file `your-new-snap-in/test_data/data_extraction_check.json`.\n\n  - **Scripts \u0026 Auxiliary Files**: To customize a script, copy it from `airdrop-shared/scripts/` into your snap-in's repository and modify it as needed. Remember to update the corresponding path in your `config.yaml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevrev%2Fairdrop-shared","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevrev%2Fairdrop-shared","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevrev%2Fairdrop-shared/lists"}