mirror of
https://github.com/d0zingcat/BroadcastChannel.git
synced 2026-05-13 15:09:12 +00:00
6ec262d8cf
Replaces PostCSS-based styling with Tailwind CSS v4 via Vite plugin Converts all .js files to .ts with proper type annotations Adds comprehensive type definitions for Telegram data structures Extracts reusable UI components and standardizes class utilities Improves maintainability by eliminating custom CSS in favor of Tailwind utilities and design tokens Enhances type safety across Telegram parsing, env access, and API routes Centralizes agent guidelines in AGENTS.md following repository standards Upgrades iconography to astro-icon with Remix Icon integration Expands accessible HTML patterns including ARIA labels, semantic navigation, and keyboard interaction support Refactors static proxy logic into shared utility functions Consolidates modal and image preview markup for consistency
160 lines
7.6 KiB
Markdown
160 lines
7.6 KiB
Markdown
# Repository Guidelines for Coding Agents
|
|
|
|
## 1. Scope
|
|
|
|
- This repository is an Astro 5 SSR site that turns Telegram channels into a microblog.
|
|
- Use this file as the main repo-specific guide for coding agents working in this project.
|
|
- Prefer small, surgical changes that match the existing code style and structure.
|
|
- Assume server-rendered HTML is the default; client-side JavaScript is intentionally minimal.
|
|
|
|
## 2. Instruction Sources
|
|
|
|
- Root `AGENTS.md` is the maintained agent guide for this repository.
|
|
- No `.cursor/rules/**`, `.cursorrules`, or `.github/copilot-instructions.md` files were found.
|
|
- If Cursor or Copilot rules are added later, merge them into this file.
|
|
- `CLAUDE.md` is an older short copy; prefer this file when they disagree.
|
|
|
|
## 3. Project Snapshot
|
|
|
|
- Package manager: `pnpm` only.
|
|
- Preferred Node version: `v22`.
|
|
- Framework: `astro@5`.
|
|
- Lint stack: `eslint@9` + `@antfu/eslint-config` + `eslint-plugin-astro` + `eslint-plugin-format`.
|
|
- Styling: Tailwind CSS v4 via `@tailwindcss/vite`.
|
|
|
|
## 4. Repository Map
|
|
|
|
- `src/pages/`: Astro pages and API-style route handlers.
|
|
- `src/components/`: reusable UI pieces and page fragments.
|
|
- `src/layouts/`: page shells like `base.astro`.
|
|
- `src/lib/`: Telegram fetching, parsing, env access, proxying, and shared logic.
|
|
- `src/types.ts`: shared domain interfaces.
|
|
- `dist/`, `.astro/`, and `node_modules/`: generated output; do not hand-edit.
|
|
|
|
## 5. Core Commands
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev
|
|
pnpm start
|
|
pnpm build
|
|
pnpm preview
|
|
pnpm lint:fix
|
|
```
|
|
|
|
- `pnpm eslint <path>` is the supported focused lint command.
|
|
- Use `pnpm astro ...` only when a task specifically needs extra Astro CLI behavior.
|
|
|
|
## 6. Testing Reality
|
|
|
|
- There is currently **no automated test runner** in this repo.
|
|
- There is no `pnpm test` script.
|
|
- No Vitest, Jest, Playwright, or Cypress config files are present.
|
|
- No `*.test.*` or `*.spec.*` files are present.
|
|
|
|
### Single-test guidance
|
|
|
|
- There is currently **no supported "run a single test" command**.
|
|
- If asked to run a single test, say so explicitly instead of inventing a command.
|
|
- Use `pnpm eslint <path>` for a narrow static check.
|
|
- Use `pnpm build && pnpm preview` plus manual route verification for behavior checks.
|
|
|
|
## 7. Recommended Validation
|
|
|
|
- Small refactor or one-file logic change: `pnpm eslint <file>` then `pnpm lint`.
|
|
- UI or route change: `pnpm lint`, then `pnpm build`, then `pnpm preview`.
|
|
- Feed, metadata, or sitemap change: verify `/rss.xml`, `/rss.json`, and `/sitemap.xml` manually in preview.
|
|
- Telegram parsing or proxy change: validate home, one post page, RSS output, and the relevant `/static/...` path.
|
|
- Env/config change: update docs and validate behavior with representative env values.
|
|
|
|
## 8. Formatting Rules
|
|
|
|
- Follow ESLint as the formatting source of truth; do not fight the auto-fixer.
|
|
- Indentation: 2 spaces.
|
|
- Line endings: LF.
|
|
- Charset: UTF-8.
|
|
- Quotes: single quotes.
|
|
- Semicolons are typically omitted.
|
|
- Trailing commas should follow linter/formatter output.
|
|
- Do not do unrelated whitespace churn.
|
|
|
|
## 9. Imports
|
|
|
|
- Use `import type` for type-only imports.
|
|
- Keep side-effect imports explicit, e.g. CSS, locale packs, and Prism language loaders.
|
|
- No path aliases are configured in `tsconfig.json`; use relative imports.
|
|
- Let ESLint decide final import ordering; run `pnpm lint:fix` after adding or moving imports.
|
|
- Avoid unused imports.
|
|
|
|
## 10. Naming Conventions
|
|
|
|
- Keep route filenames aligned with Astro routing: `index.astro`, `[id].astro`, `[...url].ts`, `rss.xml.ts`, etc.
|
|
- Reusable new Astro components should prefer `PascalCase.astro`.
|
|
- Preserve neighboring conventions when editing older lowercase Astro files like `header.astro`, `item.astro`, or `base.astro`.
|
|
- New helper modules should use descriptive kebab-case names when that matches existing utilities.
|
|
- Environment variables use uppercase snake case.
|
|
- Shared interfaces and types use PascalCase names.
|
|
|
|
## 11. Types
|
|
|
|
- Prefer explicit interfaces for shared domain shapes in `src/types.ts`.
|
|
- Keep shared type definitions centralized instead of re-declaring them across files.
|
|
- Prefer narrow unions when the allowed values are known, e.g. `'text' | 'service'`.
|
|
- Avoid `any`; use `unknown`, proper interfaces, or generics.
|
|
- Type exported handlers and helpers when practical, e.g. `APIRoute`, explicit return types, or typed props.
|
|
- In Astro files, keep prop shapes obvious near the top of frontmatter.
|
|
|
|
## 12. Astro and UI Patterns
|
|
|
|
- Keep page frontmatter focused on loading data and preparing view state.
|
|
- Push reusable logic into `src/lib/` instead of repeating it inside pages.
|
|
- Use `Astro.locals` for request-scoped values set by middleware.
|
|
- API-style routes in `src/pages/*.ts` should return `Response` / `Response.json`, not Express-like objects.
|
|
- Prefer semantic HTML and accessible labels.
|
|
- Keep browser-side JS near zero; the current deliberate exception is the Telegram comments widget.
|
|
- Do not add `client:*` directives or inline scripts unless the feature genuinely requires them.
|
|
- Tailwind utility classes are used heavily in `.astro` files.
|
|
- For long class strings, follow the existing pattern of extracting them into constants above the markup.
|
|
- Reuse existing visual tokens and accessible structures instead of inventing near-duplicates.
|
|
|
|
## 13. Error Handling
|
|
|
|
- Fail fast for required server-side configuration, e.g. throw when mandatory env values are missing.
|
|
- In request handlers, catch unknown errors only when you can convert them into an explicit HTTP response.
|
|
- When catching, narrow with `instanceof Error` before reading `.message`.
|
|
- Do not silently swallow fetch or parsing failures.
|
|
- Keep error messages actionable and specific.
|
|
|
|
## 14. External Fetching, Parsing, and HTML Safety
|
|
|
|
- Telegram fetching and parsing live in `src/lib/telegram/index.ts`; keep new scraping logic there.
|
|
- Preserve the static proxy whitelist behavior in `src/lib/static-proxy.ts` unless the task explicitly changes the security model.
|
|
- When proxying or forwarding requests, be careful with headers and target validation.
|
|
- `set:html` is already used in a few places; only feed it sanitized or internally generated HTML.
|
|
- If introducing new HTML transformations for feeds or pages, sanitize external content first.
|
|
- Avoid mutating cached data objects in-place when extending cached flows.
|
|
|
|
## 15. Env and Config Notes
|
|
|
|
- Never commit real secrets or tokens.
|
|
- Update `.env.example` when introducing, removing, or renaming env variables.
|
|
- Update README docs when env behavior changes.
|
|
- Prefer actual code usage over stale README text if they conflict.
|
|
- Important current code-level env names include `CHANNEL`, `LOCALE`, `TIMEZONE`, `TELEGRAM_HOST`, `STATIC_PROXY`, `COMMENTS`, `REACTIONS`, `NOINDEX`, `NOFOLLOW`, `RSS_BEAUTIFY`, `TAGS`, `LINKS`, `NAVS`, `HEADER_INJECT`, and `FOOTER_INJECT`.
|
|
- Note that `PODCASRT` is the current code-level env key in `header.astro`; keep compatibility in mind unless intentionally correcting it everywhere.
|
|
|
|
## 16. Build and Deployment Notes
|
|
|
|
- `astro.config.mjs` selects adapters for Vercel, Cloudflare Pages, Netlify, Node, and EdgeOne.
|
|
- The app is configured with `output: 'server'`.
|
|
- Do not change adapter logic casually; deployment behavior depends on environment detection.
|
|
- If you touch build configuration, run `pnpm build` before finishing.
|
|
|
|
## 17. Working Style
|
|
|
|
- Inspect nearby files before editing to match local conventions.
|
|
- Prefer updating existing patterns over introducing new abstractions.
|
|
- Keep comments sparse and explain why, not what.
|
|
- If a task would benefit from automated tests, note that the repo currently lacks a test harness instead of pretending one exists.
|
|
- If you add a real test runner in the future, update `package.json`, this file, and the single-test instructions together.
|