diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 464ceac..5d42dd3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi 2. **Setup** ```bash - npm install + npm ci npm start # Start demo and documentation site ``` @@ -25,11 +25,11 @@ This is a **monorepo** with npm workspaces containing **two main packages**: 1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm 2. **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website` -We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required. +We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required. - When developing. Use alias so that we don't have to pre-build. - When bundling. Use external and disable ts `paths` alias to leave deps out. -- When bundling `UMD` and `Website`. Bundle everything including local packages. +- When bundling `IIFE` and `Website`. Bundle everything including local packages. ## 🤝 How to Contribute @@ -61,10 +61,9 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference - Update documentation as needed 4. **Test Your Changes** - - ```bash - # TODO - ``` + - Test in our demo website + - Test it on other websites if applicable + - `@TODO: test suite` 5. **Commit and Push** @@ -94,41 +93,52 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference - It's **recommended** to heavily rely on AI (aka "vibe coding") when maintaining **demo pages and tests**. - BUT **NOT the core lib!!!** Be very careful if AI ever touched the core lib!!! - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI. -- Update the AI instructions when structure changed. - - Cursor and Cline: `./.cursor/rules` - - Github Copilot: `./.github/copilot-instructions.md` - - Claude Code: `./CLAUDE.md` +- Update the [AI instructions](AGENTS.md) when structure changed. ## 🔧 Development Workflows +### Test With Your Own LLM API + +- Create a `.env` file in the repo root with your LLM API config + + ```env + LLM_MODEL_NAME=gpt-5.2 + LLM_API_KEY=your-api-key + LLM_BASE_URL=https://api.your-llm-provider.com/v1 + ``` + +- Restart the dev server to load new env vars +- If not provided, the demo will the free testing proxy by default + ### Website Development ```bash -npm start # React development server +npm start ``` -### Core Lib Development and Testing +### Testing on Other Websites -> @TODO this part is outdated. Update this. +- Start and serve a local `iife` script -- Config your LLM API -- Start and serve a local umd script + ```bash + npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js + ``` - ```bash - npm run dev:umd # Serving UMD with auto rebuild at http://localhost:5173/page-agent.umd.cjs - ``` +- Add a new bookmark -- Add a new bookmark enable it on other website + ```javascript + javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})(); + ``` - ``` - javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5173/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})(); - ``` +- Click the bookmark on any page to load Page-Agent + +> Warning: AK in your local `.env` will be inlined in the iife script. ### Adding Documentation -1. Create `website/src/docs/section/page-name/page.tsx` -2. Add route to `website/src/router.tsx` -3. Add navigation link to `website/src/components/DocsLayout.tsx` +Ask an AI to help you add documentation to the `website/` package. Follow the existing style. + +> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated. ## 🎯 Contribution Areas @@ -143,7 +153,7 @@ We especially welcome contributions in: ## 🚫 What We Don't Accept -- Changes that break existing API compatibility +- Changes that break existing API compatibility (Discuss first) - Heavy dependencies to core library - Contributions without proper testing - Code that doesn't follow project conventions diff --git a/LICENSE b/LICENSE index a4e3eb8..2308ce4 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,7 @@ MIT License -Copyright (c) 2025 Alibaba +Copyright (c) 2026 Alibaba +Copyright (c) 2026 Simon Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/package.json b/package.json index 3b43ce1..edb15b7 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,7 @@ "build:website": "npm run build:website --workspace=@page-agent/website", "build:libs": "npm run build --workspaces --if-present", "build": "npm run build:libs && npm run build:website", - "dev:umd": "npm run dev:umd --workspace=page-agent", + "dev:iife": "npm run dev:iife --workspace=page-agent", "version": "node scripts/sync-version.js", "lint": "eslint .", "prepare": "husky" diff --git a/packages/page-agent/package.json b/packages/page-agent/package.json index ce8ec11..0ac14f5 100644 --- a/packages/page-agent/package.json +++ b/packages/page-agent/package.json @@ -37,9 +37,8 @@ }, "homepage": "https://alibaba.github.io/page-agent/", "scripts": { - "build": "vite build && vite build --config vite.umd.config.js", - "serve": "npx serve dist/umd -p 5173", - "dev:umd": "concurrently \"vite build --config vite.umd.config.js --watch\" \"npm run serve\"", + "build": "vite build", + "dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"", "prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"", "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\"" }, diff --git a/packages/page-agent/src/umd.ts b/packages/page-agent/src/iife.ts similarity index 83% rename from packages/page-agent/src/umd.ts rename to packages/page-agent/src/iife.ts index 82f3a42..84e7504 100644 --- a/packages/page-agent/src/umd.ts +++ b/packages/page-agent/src/iife.ts @@ -36,9 +36,13 @@ setTimeout(() => { } else { console.log('🚀 page-agent.js no current script detected, using default demo config') const config: PageAgentConfig = { - model: DEMO_MODEL, - baseURL: DEMO_BASE_URL, - apiKey: DEMO_API_KEY, + // model: DEMO_MODEL, + // baseURL: DEMO_BASE_URL, + // apiKey: DEMO_API_KEY, + + model: import.meta.env.LLM_MODEL_NAME ? import.meta.env.LLM_MODEL_NAME : DEMO_MODEL, + baseURL: import.meta.env.LLM_BASE_URL ? import.meta.env.LLM_BASE_URL : DEMO_BASE_URL, + apiKey: import.meta.env.LLM_API_KEY ? import.meta.env.LLM_API_KEY : DEMO_API_KEY, } window.pageAgent = new PageAgent(config) } diff --git a/packages/page-agent/vite.umd.config.js b/packages/page-agent/vite.iife.config.js similarity index 67% rename from packages/page-agent/vite.umd.config.js rename to packages/page-agent/vite.iife.config.js index 53b2e56..0346051 100644 --- a/packages/page-agent/vite.umd.config.js +++ b/packages/page-agent/vite.iife.config.js @@ -1,4 +1,5 @@ // @ts-check +import { config as dotenvConfig } from 'dotenv' import { dirname, resolve } from 'path' import { fileURLToPath } from 'url' import { defineConfig } from 'vite' @@ -6,11 +7,14 @@ import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js' const __dirname = dirname(fileURLToPath(import.meta.url)) +// Load .env from repo root +dotenvConfig({ path: resolve(__dirname, '../../.env') }) + // UMD Bundle for CDN // - alias all local packages so that they can be build in // - no external // - no d.ts. dts does not work with monorepo aliasing -export default defineConfig({ +export default defineConfig(({ mode }) => ({ plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })], publicDir: false, esbuild: { @@ -25,13 +29,14 @@ export default defineConfig({ }, build: { lib: { - entry: resolve(__dirname, 'src/umd.ts'), + entry: resolve(__dirname, 'src/iife.ts'), name: 'PageAgent', fileName: 'page-agent', - formats: ['umd'], + formats: ['iife'], }, - outDir: resolve(__dirname, 'dist', 'umd'), + outDir: resolve(__dirname, 'dist', 'iife'), cssCodeSplit: true, + minify: false, rollupOptions: { output: { // force use .js as extension @@ -44,6 +49,8 @@ export default defineConfig({ }, }, define: { - 'process.env.NODE_ENV': '"production"', + 'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME), + 'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY), + 'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL), }, -}) +})) diff --git a/packages/website/vite.config.js b/packages/website/vite.config.js index b6c3651..fcc24a5 100644 --- a/packages/website/vite.config.js +++ b/packages/website/vite.config.js @@ -16,7 +16,7 @@ const pageAgentPkg = JSON.parse( dotenvConfig({ path: resolve(__dirname, '../../.env') }) // Website Config (React Documentation Site) -export default defineConfig({ +export default defineConfig(({ mode }) => ({ base: './', clearScreen: false, plugins: [react(), tailwindcss()], @@ -43,9 +43,11 @@ export default defineConfig({ }, }, define: { - 'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME), - 'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY), - 'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL), + ...(mode === 'development' && { + 'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME), + 'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY), + 'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL), + }), 'import.meta.env.VERSION': JSON.stringify(pageAgentPkg.version), }, -}) +}))