mirror of
https://github.com/jackwener/OpenCLI.git
synced 2026-09-14 18:25:42 +08:00
jakevin
4fe9a73ebc
* refactor: migrate adapter imports to package exports Replace all relative imports (../../src/registry.js, ../../browser/cdp.js, etc.) with package exports (@jackwener/opencli/registry, @jackwener/opencli/errors, etc.) across all 484 adapter files. This decouples adapter import resolution from directory structure: - User CLIs in ~/.opencli/clis/ resolve via node_modules symlink - Internal adapters resolve via Node.js self-referencing - No more shim files needed for import resolution Changes: - package.json: add sub-path exports for all public modules - clis/**: replace relative imports with @jackwener/opencli/... - discovery.ts: simplify ensureUserCliCompatShims to symlink-only - registry-api.ts: export CommandArgs type - Remove root-level shim directories (browser/, download/, pipeline/) - Remove shim entries from tsconfig.json include and package.json files * test: add regression tests for package exports Prevents regressions like #788/#791 by: 1. Scanning all adapter files for forbidden relative imports (../../src/, ../../browser/, etc.) — fails if any remain 2. Verifying every package.json export maps to an existing source file 18 new test cases. * fix: use junction on Windows + broaden test patterns - discovery.ts: use 'junction' symlink type on Windows (no admin required) - package-exports.test.ts: generalize forbidden patterns to catch any depth of ../ traversal (not just ../../ and ../../../) * fix: update stale vi.mock/importActual paths in adapter tests Test files still used old relative paths for vi.mock() and vi.importActual() calls. Updated 5 test files to use package exports. Also broadened regression test patterns to catch mock/importActual paths. * fix: use rm instead of unlink for symlink cleanup, add warn on failure Addresses review feedback from Astro-Han: - rm() handles both symlinks and stale directories (unlink fails on dirs) - Log a warning when symlink creation fails instead of silent catch * docs: update import examples to use package exports Update all documentation, contributing guides, and skills to use @jackwener/opencli/registry instead of ../../src/registry.js. Without this, users following the docs would write adapters with broken imports since the old shim files are no longer created.
106 lines
3.3 KiB
Markdown
106 lines
3.3 KiB
Markdown
# TypeScript Adapter Guide
|
|
|
|
Use TypeScript adapters when you need browser-side logic, multi-step flows, DOM manipulation, or complex data extraction that goes beyond simple API fetching.
|
|
|
|
## Basic Structure
|
|
|
|
```typescript
|
|
import { cli, Strategy } from '@jackwener/opencli/registry';
|
|
import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
|
|
|
|
cli({
|
|
site: 'mysite',
|
|
name: 'search',
|
|
description: 'Search MySite',
|
|
domain: 'www.mysite.com',
|
|
strategy: Strategy.COOKIE, // PUBLIC | COOKIE | HEADER
|
|
args: [
|
|
{ name: 'query', required: true, help: 'Search query' },
|
|
{ name: 'limit', type: 'int', default: 10, help: 'Max results' },
|
|
],
|
|
columns: ['title', 'url', 'date'],
|
|
|
|
func: async (page, kwargs) => {
|
|
const { query, limit = 10 } = kwargs;
|
|
|
|
// Navigate and extract data
|
|
await page.goto('https://www.mysite.com');
|
|
|
|
const data = await page.evaluate(`
|
|
(async () => {
|
|
const res = await fetch('/api/search?q=${encodeURIComponent(String(query))}', {
|
|
credentials: 'include'
|
|
});
|
|
return (await res.json()).results;
|
|
})()
|
|
`);
|
|
|
|
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) => ({
|
|
title: item.title,
|
|
url: item.url,
|
|
date: item.created_at,
|
|
}));
|
|
},
|
|
});
|
|
```
|
|
|
|
## Strategy Types
|
|
|
|
| Strategy | Constant | Use Case |
|
|
|----------|----------|----------|
|
|
| Public | `Strategy.PUBLIC` | No auth needed |
|
|
| Cookie | `Strategy.COOKIE` | Browser session cookies |
|
|
| Header | `Strategy.HEADER` | Custom headers/tokens |
|
|
|
|
## The `page` Object
|
|
|
|
The `page` parameter provides browser interaction methods:
|
|
|
|
- `page.goto(url)` — Navigate to a URL
|
|
- `page.evaluate(script)` — Execute JavaScript in the page context
|
|
- `page.waitForSelector(selector)` — Wait for an element
|
|
- `page.click(selector)` — Click an element
|
|
- `page.type(selector, text)` — Type text into an input
|
|
|
|
## The `kwargs` Object
|
|
|
|
Contains parsed CLI arguments as key-value pairs. Always destructure with defaults:
|
|
|
|
```typescript
|
|
const { query, limit = 10, format = 'json' } = kwargs;
|
|
```
|
|
|
|
For most search/read/detail commands, the main subject should be positional (`opencli mysite search "rust"`, `opencli mysite article 123`) instead of a named flag such as `--query` or `--id`. Keep named flags for optional modifiers.
|
|
|
|
## Error Handling
|
|
|
|
Prefer throwing `CliError` subclasses from `src/errors.ts` for expected adapter failures:
|
|
|
|
- `AuthRequiredError` for missing login / cookies
|
|
- `EmptyResultError` for empty but valid responses
|
|
- `CommandExecutionError` for unexpected API or browser failures
|
|
- `TimeoutError` for site timeouts
|
|
- `ArgumentError` for invalid user input
|
|
|
|
Avoid raw `Error` for normal adapter control flow. This keeps top-level CLI output consistent and preserves hints for users.
|
|
|
|
## AI-Assisted Development
|
|
|
|
Use the AI workflow tools to accelerate adapter creation:
|
|
|
|
```bash
|
|
# Discover APIs and page structure
|
|
opencli explore https://example.com --site mysite
|
|
|
|
# Auto-generate adapter from explore artifacts
|
|
opencli synthesize mysite
|
|
|
|
# One-shot: explore → synthesize → register
|
|
opencli generate https://example.com --goal "trending"
|
|
```
|
|
|
|
See [AI Workflow](/developer/ai-workflow) for the complete guide.
|