From e99f3650e3f9151f5cdca73ceb1affdaf8a51e66 Mon Sep 17 00:00:00 2001 From: yixin-1024 Date: Wed, 24 Jun 2026 16:35:34 +0800 Subject: [PATCH] docs: align adapter contribution example with the JavaScript adapter layer The "Create a file like clis//.ts" example predates #928, which converted the entire adapter layer from TypeScript to JavaScript. The repo now ships 0 .ts and 1259 .js built-in adapters, so a contributor following the doc creates a file in the wrong format. Update the example to JavaScript (keeping a pointer to the still-supported TypeScript path), and fix the adapter test command, which pointed at src/ rather than the adapter's own clis/ test file. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/developer/contributing.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/developer/contributing.md b/docs/developer/contributing.md index 845a1bbd5..449ea566a 100644 --- a/docs/developer/contributing.md +++ b/docs/developer/contributing.md @@ -33,11 +33,11 @@ Before you start: - Normalize expected adapter failures to `CliError` subclasses instead of raw `Error` whenever possible. Prefer `AuthRequiredError`, `EmptyResultError`, `CommandExecutionError`, `TimeoutError`, and `ArgumentError` so the top-level CLI can render better messages and hints. - If you add a new adapter or make a command newly discoverable, update the matching doc page and the user-facing indexes that expose it. -### TypeScript Adapter +### Create the Adapter -Create a file like `clis//.ts`: +Built-in adapters are authored in JavaScript. Create a file like `clis//.js`: -```typescript +```javascript import { cli, Strategy } from '@jackwener/opencli/registry'; import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors'; @@ -60,7 +60,7 @@ cli({ // ... browser automation logic if (!Array.isArray(data)) throw new CommandExecutionError('MySite returned an unexpected response'); if (!data.length) throw new EmptyResultError('mysite search', 'Try a different keyword'); - return data.slice(0, Number(limit)).map((item: any) => ({ + return data.slice(0, Number(limit)).map((item) => ({ title: item.title, url: item.url, date: item.created_at, @@ -69,6 +69,8 @@ cli({ }); ``` +> TypeScript adapters are also supported — see [TypeScript Adapter](./ts-adapter). + ### Validate Your Adapter ```bash @@ -104,7 +106,7 @@ chore: bump vitest to v4 ```bash npx tsc --noEmit # Type check npm run build # Ensure dist stays healthy - npx vitest run src/.test.ts + npx vitest run clis//.test.js # Your adapter's tests npm test # Broader local gate when shared runtime changes justify it ``` 4. Commit using conventional commit format