diff --git a/AGENTS.md b/AGENTS.md index d16bab72c8..2d0c03eec3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ examples// ← Generated SDK output (checked in for verificat example.php ← Entry point: regenerates all SDKs from specs ``` -**Supported SDKs:** PHP, Web, Node, CLI, Ruby, Python, Dart, Flutter, React Native, Go, Swift, Apple, DotNet, Android, Kotlin, GraphQL, Markdown, AgentSkills, CursorPlugin, ClaudePlugin +**Supported SDKs:** PHP, Web, Node, CLI, Ruby, Python, Dart, Flutter, React Native, Go, Swift, Apple, DotNet, Android, Kotlin, GraphQL, Markdown, AgentSkills, CursorPlugin, ClaudePlugin, CodexPlugin ## Primary Workflows @@ -157,6 +157,7 @@ Pass as first argument to generate only that SDK: | `agent-skills` | AgentSkills | `examples/agent-skills/` | | `cursor-plugin` | CursorPlugin | `examples/cursor-plugin/` | | `claude-plugin` | ClaudePlugin | `examples/claude-plugin/` | +| `codex-plugin` | CodexPlugin | `examples/codex-plugin/` | ## Twig Template Variables by Scope diff --git a/example.php b/example.php index 01a7cb8140..78544401af 100644 --- a/example.php +++ b/example.php @@ -25,6 +25,7 @@ use Appwrite\SDK\Language\Markdown; use Appwrite\SDK\Language\AgentSkills; use Appwrite\SDK\Language\ClaudePlugin; +use Appwrite\SDK\Language\CodexPlugin; use Appwrite\SDK\Language\CursorPlugin; use Appwrite\SDK\Language\Rust; @@ -115,7 +116,7 @@ function configureSDK($sdk, $overrides = []) { } $version = '1.9.x'; - $speclessSDKs = ['agent-skills', 'cursor-plugin', 'claude-plugin']; + $speclessSDKs = ['agent-skills', 'cursor-plugin', 'claude-plugin', 'codex-plugin']; $needsSpec = !$requestedSdk || !in_array($requestedSdk, $speclessSDKs); if ($needsSpec) { @@ -339,6 +340,19 @@ function configureSDK($sdk, $overrides = []) { $sdk->generate(__DIR__ . '/examples/claude-plugin'); } + // Codex Plugin + if (!$requestedSdk || $requestedSdk === 'codex-plugin') { + $sdk = new SDK(new CodexPlugin(), new StaticSpec( + title: 'Appwrite', + description: 'Appwrite backend as a service', + version: $version, + licenseName: 'BSD-3-Clause', + licenseURL: 'https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE', + )); + configureSDK($sdk); + $sdk->generate(__DIR__ . '/examples/codex-plugin'); + } + // Rust if (!$requestedSdk || $requestedSdk === 'rust') { $sdk = new SDK(new Rust(), new Swagger2($spec)); diff --git a/src/SDK/Language/CodexPlugin.php b/src/SDK/Language/CodexPlugin.php new file mode 100644 index 0000000000..e6ce4c64d6 --- /dev/null +++ b/src/SDK/Language/CodexPlugin.php @@ -0,0 +1,100 @@ + 'default', + 'destination' => 'plugins/{{ spec.title | caseLower }}/skills/{{ spec.title | caseLower }}-' . $lang . '/SKILL.md', + 'template' => 'agent-skills/' . $lang . '.md.twig', + ]; + } + + $files[] = [ + 'scope' => 'default', + 'destination' => 'plugins/{{ spec.title | caseLower }}/.codex-plugin/plugin.json', + 'template' => 'codex-plugin/plugin.json.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => '.agents/plugins/marketplace.json', + 'template' => 'codex-plugin/marketplace.json.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'plugins/{{ spec.title | caseLower }}/.mcp.json', + 'template' => 'codex-plugin/.mcp.json.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'plugins/{{ spec.title | caseLower }}/skills/{{ spec.title | caseLower }}-deploy-site/SKILL.md', + 'template' => 'plugin/commands/deploy-site.md.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'plugins/{{ spec.title | caseLower }}/skills/{{ spec.title | caseLower }}-deploy-function/SKILL.md', + 'template' => 'plugin/commands/deploy-function.md.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'plugins/{{ spec.title | caseLower }}/config.toml', + 'template' => 'codex-plugin/config.toml.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'README.md', + 'template' => 'codex-plugin/README.md.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'CHANGELOG.md', + 'template' => 'agent-skills/CHANGELOG.md.twig', + ]; + + $files[] = [ + 'scope' => 'default', + 'destination' => 'LICENSE', + 'template' => 'plugin/LICENSE.twig', + ]; + + return $files; + } +} diff --git a/templates/codex-plugin/.mcp.json.twig b/templates/codex-plugin/.mcp.json.twig new file mode 100644 index 0000000000..868f609089 --- /dev/null +++ b/templates/codex-plugin/.mcp.json.twig @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "{{ spec.title | caseLower }}-docs": { + "type": "http", + "url": "https://mcp-for-docs.appwrite.io" + } + } +} diff --git a/templates/codex-plugin/README.md.twig b/templates/codex-plugin/README.md.twig new file mode 100644 index 0000000000..8cfed0027b --- /dev/null +++ b/templates/codex-plugin/README.md.twig @@ -0,0 +1,112 @@ +# {{ spec.title }} Codex CLI Plugin + +![License](https://img.shields.io/github/license/{{ sdk.gitUserName|url_encode }}/{{ sdk.gitRepoName|url_encode }}.svg?style=flat-square) +![Version](https://img.shields.io/badge/api%20version-{{ sdk.version }}-blue.svg?style=flat-square) +[![Twitter Account](https://img.shields.io/twitter/follow/appwrite?color=00acee&label=twitter&style=flat-square)](https://twitter.com/appwrite) +[![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord) + +{{ spec.title }} tools for the [OpenAI Codex CLI](https://github.com/openai/codex). This plugin packages {{ spec.title }} SDK skills, {{ spec.title }} deployment workflow skills, and the {{ spec.title }} docs MCP server. + +## Structure + +```text +plugins/{{ spec.title | caseLower }}/skills/ # Codex skills (auto-loaded by description match) +|-- {{ spec.title | caseLower }}-typescript/SKILL.md +|-- {{ spec.title | caseLower }}-dart/SKILL.md +|-- {{ spec.title | caseLower }}-kotlin/SKILL.md +|-- {{ spec.title | caseLower }}-swift/SKILL.md +|-- {{ spec.title | caseLower }}-php/SKILL.md +|-- {{ spec.title | caseLower }}-python/SKILL.md +|-- {{ spec.title | caseLower }}-ruby/SKILL.md +|-- {{ spec.title | caseLower }}-go/SKILL.md +|-- {{ spec.title | caseLower }}-rust/SKILL.md +|-- {{ spec.title | caseLower }}-dotnet/SKILL.md +|-- {{ spec.title | caseLower }}-cli/SKILL.md +|-- {{ spec.title | caseLower }}-deploy-site/SKILL.md +`-- {{ spec.title | caseLower }}-deploy-function/SKILL.md +plugins/{{ spec.title | caseLower }}/.codex-plugin/plugin.json # Codex plugin manifest +.agents/plugins/marketplace.json # Local marketplace manifest +plugins/{{ spec.title | caseLower }}/.mcp.json # MCP server config for plugin installs +plugins/{{ spec.title | caseLower }}/config.toml # MCP server config snippet for manual installs +``` + +## Installation + +Codex plugins include a `.codex-plugin/plugin.json` manifest for plugin installation. For manual installs, Codex CLI loads skills from `~/.codex/skills/` and reads MCP server configuration from `~/.codex/config.toml`. Install the generated files manually by copying them into those locations. + +To install through a local Codex marketplace, add this directory as a marketplace source using the generated `.agents/plugins/marketplace.json` file. + +### macOS / Linux + +```sh +# Copy skills +mkdir -p ~/.codex/skills +cp -R plugins/{{ spec.title | caseLower }}/skills/* ~/.codex/skills/ + +# Append the MCP config snippet to your Codex config +mkdir -p ~/.codex +cat plugins/{{ spec.title | caseLower }}/config.toml >> ~/.codex/config.toml +``` + +### Windows (PowerShell) + +```powershell +# Copy skills +New-Item -ItemType Directory -Force -Path "$HOME\.codex\skills" | Out-Null +Copy-Item -Recurse plugins\{{ spec.title | caseLower }}\skills\* "$HOME\.codex\skills\" + +# Append the MCP config snippet to your Codex config +New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null +Get-Content plugins\{{ spec.title | caseLower }}\config.toml | Add-Content "$HOME\.codex\config.toml" +``` + +## Included Skills + +Each skill ships as `plugins/{{ spec.title | caseLower }}/skills/{{ spec.title | caseLower }}-/SKILL.md`. Codex loads them based on the `description` field in the frontmatter, so they activate automatically when a session is about Appwrite work in that language: + +- `{{ spec.title | caseLower }}-typescript` +- `{{ spec.title | caseLower }}-dart` +- `{{ spec.title | caseLower }}-kotlin` +- `{{ spec.title | caseLower }}-swift` +- `{{ spec.title | caseLower }}-php` +- `{{ spec.title | caseLower }}-python` +- `{{ spec.title | caseLower }}-ruby` +- `{{ spec.title | caseLower }}-go` +- `{{ spec.title | caseLower }}-rust` +- `{{ spec.title | caseLower }}-dotnet` +- `{{ spec.title | caseLower }}-cli` +- `{{ spec.title | caseLower }}-deploy-site` +- `{{ spec.title | caseLower }}-deploy-function` + +The language skills give Codex language-specific {{ spec.title }} context for authentication, database queries, storage, realtime, functions, and server-side administration. The deployment skills walk through {{ spec.title }} Sites and Functions deployment with the {{ spec.title }} CLI. + +## Deployment Workflows + +Deployment workflows are exposed as explicit skills: + +- `${{ spec.title | caseLower }}-deploy-site` +- `${{ spec.title | caseLower }}-deploy-function` + +Use these to walk through deploying {{ spec.title }} sites and functions with the {{ spec.title }} CLI. Codex can also load them automatically when a task matches the skill description. + +## Included MCP Servers + +The bundled `plugins/{{ spec.title | caseLower }}/config.toml` registers one MCP server: + +- `{{ spec.title | caseLower }}-docs` proxies `https://mcp-for-docs.appwrite.io` through `npx mcp-remote` so Codex can search the {{ spec.title }} documentation. + +## Verify + +After copying, run `codex` and check: + +- A session about {{ spec.title }} TypeScript work loads the `{{ spec.title | caseLower }}-typescript` skill (visible in the session header). +- Typing `$` lets you invoke the `{{ spec.title | caseLower }}-deploy-*` skills explicitly. +- `codex mcp list` (or `codex --debug`) lists the `{{ spec.title | caseLower }}-docs` server. + +## Contribution + +This library is auto-generated by Appwrite custom [SDK Generator](https://github.com/appwrite/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-generator/blob/master/CONTRIBUTING.md) before sending a pull-request. + +## License + +Please see the [{{spec.licenseName}} license]({{spec.licenseURL}}) file for more information. diff --git a/templates/codex-plugin/config.toml.twig b/templates/codex-plugin/config.toml.twig new file mode 100644 index 0000000000..e7ec19d95e --- /dev/null +++ b/templates/codex-plugin/config.toml.twig @@ -0,0 +1,7 @@ +# {{ spec.title }} Codex CLI configuration +# +# Merge the contents of this file into your ~/.codex/config.toml. + +[mcp_servers.{{ spec.title | caseLower }}-docs] +command = "npx" +args = ["mcp-remote", "https://mcp-for-docs.appwrite.io"] diff --git a/templates/codex-plugin/marketplace.json.twig b/templates/codex-plugin/marketplace.json.twig new file mode 100644 index 0000000000..a1a96f8a88 --- /dev/null +++ b/templates/codex-plugin/marketplace.json.twig @@ -0,0 +1,20 @@ +{ + "name": "{{ spec.title | caseLower }}", + "interface": { + "displayName": "{{ spec.title }}" + }, + "plugins": [ + { + "name": "{{ spec.title | caseLower }}", + "source": { + "source": "local", + "path": "../../plugins/{{ spec.title | caseLower }}" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + } + ] +} diff --git a/templates/codex-plugin/plugin.json.twig b/templates/codex-plugin/plugin.json.twig new file mode 100644 index 0000000000..c924be7b7d --- /dev/null +++ b/templates/codex-plugin/plugin.json.twig @@ -0,0 +1,41 @@ +{ + "name": "{{ spec.title | caseLower }}", + "version": "{{ sdk.version }}", + "description": "{{ spec.title }} tools for Codex, including SDK skills, MCP servers, and deployment workflow skills.", + "author": { + "name": "Appwrite", + "email": "team@appwrite.io", + "url": "https://appwrite.io" + }, + "homepage": "https://appwrite.io/docs/tooling/ai/ai-dev-tools/codex", + "repository": "https://github.com/{{ sdk.gitUserName }}/{{ sdk.gitRepoName }}", + "license": "{{ spec.licenseName }}", + "keywords": [ + "{{ spec.title | caseLower }}", + "codex", + "mcp", + "skills" + ], + "skills": "../skills/", + "mcpServers": "../.mcp.json", + "interface": { + "displayName": "{{ spec.title }}", + "shortDescription": "{{ spec.title }} SDK skills, MCP servers, and deployment workflow skills for Codex.", + "longDescription": "Use {{ spec.title }} with Codex through language-specific SDK skills, project and documentation MCP servers, and guided deployment skills for sites and functions.", + "developerName": "Appwrite", + "category": "Developer Tools", + "capabilities": [ + "Interactive", + "Write" + ], + "websiteURL": "https://appwrite.io", + "privacyPolicyURL": "https://appwrite.io/privacy", + "termsOfServiceURL": "https://appwrite.io/terms", + "defaultPrompt": [ + "Build an {{ spec.title }} app with the SDK.", + "Connect Codex to my {{ spec.title }} project.", + "Deploy my {{ spec.title }} function." + ], + "brandColor": "#FD366E" + } +}