BroadcastChannel/AGENTS.md

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

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.